Function: format-decode

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

Signature

(format-decode FORMAT LENGTH &optional VISIT-FLAG)

Documentation

Decode text from any known FORMAT.

FORMAT is a symbol appearing in format-alist or a list of such symbols, or nil, in which case this function tries to guess the format of the data by matching against the regular expressions in format-alist. After a match is found and the region decoded, the alist is searched again from the beginning for another match.

Second arg LENGTH is the number of characters following point to operate on. If optional third arg VISIT-FLAG is true, set buffer-file-format to the reverted list of formats used, and call any mode functions defined for those formats.

Return the new length of the decoded region.

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

Source Code

;; Defined in /usr/src/emacs/lisp/format.el.gz
(defun format-decode (format length &optional visit-flag)
  ;; This function is called by insert-file-contents whenever a file is read.
  "Decode text from any known FORMAT.
FORMAT is a symbol appearing in `format-alist' or a list of such symbols,
or nil, in which case this function tries to guess the format of the data by
matching against the regular expressions in `format-alist'.  After a match is
found and the region decoded, the alist is searched again from the beginning
for another match.

Second arg LENGTH is the number of characters following point to operate on.
If optional third arg VISIT-FLAG is true, set `buffer-file-format'
to the reverted list of formats used, and call any mode functions defined
for those formats.

Return the new length of the decoded region.

For most purposes, consider using `format-decode-region' instead."
  (let ((mod (buffer-modified-p))
	(begin (point))
	(end (+ (point) length)))
    (unwind-protect
	(progn
	  ;; Don't record undo information for the decoding.

	  (if (null format)
	      ;; Figure out which format it is in, remember list in `format'.
	      (let ((try format-alist))
		(while try
		  (let* ((f (car try))
			 (regexp (nth 2 f))
			 (p (point)))
		    (if (and regexp (looking-at regexp)
			     (< (match-end 0) (+ begin length)))
			(progn
			  (push (car f) format)
			  ;; Decode it
			  (if (nth 3 f)
			      (setq end (format-decode-run-method (nth 3 f) begin end)))
			  ;; Call visit function if required
			  (if (and visit-flag (nth 6 f)) (funcall (nth 6 f) 1))
			  ;; Safeguard against either of the functions changing pt.
			  (goto-char p)
			  ;; Rewind list to look for another format
			  (setq try format-alist))
		      (setq try (cdr try))))))
	    ;; Deal with given format(s)
	    (or (listp format) (setq format (list format)))
	    (let ((do format) f)
	      (while do
		(or (setq f (assq (car do) format-alist))
		    (error "Unknown format %s" (car do)))
		;; Decode:
		(if (nth 3 f)
		    (setq end (format-decode-run-method (nth 3 f) begin end)))
		;; Call visit function if required
		(if (and visit-flag (nth 6 f)) (funcall (nth 6 f) 1))
		(setq do (cdr do))))
	    ;; Encode in the opposite order.
	    (setq format (reverse format)))
	  (if visit-flag
	      (setq buffer-file-format format)))

      (set-buffer-modified-p mod))

      ;; Return new length of region
    (- end begin)))