Function: format-annotate-function

format-annotate-function is a byte-compiled function defined in format.el.gz.

Signature

(format-annotate-function FORMAT FROM TO ORIG-BUF FORMAT-COUNT)

Documentation

Return annotations for writing region as FORMAT.

FORMAT is a symbol naming one of the formats defined in format-alist. It must be a single symbol, not a list like buffer-file-format. FROM and TO delimit the region to be operated on in the current buffer. ORIG-BUF is the original buffer that the data came from.

FORMAT-COUNT is an integer specifying how many times this function has been called in the process of decoding ORIG-BUF.

This function works like a function in write-region-annotate-functions: it either returns a list of annotations, or returns with a different buffer current, which contains the modified text to write. In the latter case, this function's value is nil.

For most purposes, consider using format-encode-region instead.

Source Code

;; Defined in /usr/src/emacs/lisp/format.el.gz
(defun format-annotate-function (format from to orig-buf format-count)
  "Return annotations for writing region as FORMAT.
FORMAT is a symbol naming one of the formats defined in `format-alist'.
It must be a single symbol, not a list like `buffer-file-format'.
FROM and TO delimit the region to be operated on in the current buffer.
ORIG-BUF is the original buffer that the data came from.

FORMAT-COUNT is an integer specifying how many times this function has
been called in the process of decoding ORIG-BUF.

This function works like a function in `write-region-annotate-functions':
it either returns a list of annotations, or returns with a different buffer
current, which contains the modified text to write.  In the latter case,
this function's value is nil.

For most purposes, consider using `format-encode-region' instead."
  ;; This function is called by write-region (actually
  ;; build_annotations) for each element of buffer-file-format.
  (let* ((info (assq format format-alist))
	 (to-fn  (nth 4 info))
	 (modify (nth 5 info)))
    (if to-fn
	(if modify
	    ;; To-function wants to modify region.  Copy to safe place.
	    (let ((copy-buf (get-buffer-create (format " *Format Temp %d*"
						       format-count)))
		  (sel-disp selective-display)
		  (multibyte enable-multibyte-characters)
		  (coding-system buffer-file-coding-system))
	      (with-current-buffer copy-buf
		(setq selective-display sel-disp)
		(set-buffer-multibyte multibyte)
		(setq buffer-file-coding-system coding-system))
	      (let ((inhibit-read-only t)) ; bug#14887
		(copy-to-buffer copy-buf from to)
		(set-buffer copy-buf)
		(format-insert-annotations write-region-annotations-so-far from)
		(format-encode-run-method to-fn (point-min) (point-max)
					  orig-buf))
              (when (buffer-live-p copy-buf)
                (with-current-buffer copy-buf
                  ;; Set write-region-post-annotation-function to
                  ;; delete the buffer once the write is done, but do
                  ;; it after running to-fn so it doesn't affect
                  ;; write-region calls in to-fn.
                  (setq-local write-region-post-annotation-function
                              #'kill-buffer)))
	      nil)
	  ;; Otherwise just call function, it will return annotations.
	  (funcall to-fn from to orig-buf)))))