lisp/format.el

   1 ;;; format.el --- read and save files in multiple formats
   2
   3 ;; Copyright (C) 1994, 1995, 1997, 1999, 2001, 2002, 2003, 2004, 2005,
   4 ;;   2006, 2007, 2008, 2009  Free Software Foundation, Inc.
   5
   6 ;; Author: Boris Goldowsky <boris@gnu.org>
   7
   8 ;; This file is part of GNU Emacs.
   9
  10 ;; GNU Emacs is free software: you can redistribute it and/or modify
  11 ;; it under the terms of the GNU General Public License as published by
  12 ;; the Free Software Foundation, either version 3 of the License, or
  13 ;; (at your option) any later version.
  14
  15 ;; GNU Emacs is distributed in the hope that it will be useful,
  16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 ;; GNU General Public License for more details.
  19
  20 ;; You should have received a copy of the GNU General Public License
  21 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  22
  23 ;;; Commentary:
  24
  25 ;; This file defines a unified mechanism for saving & loading files stored
  26 ;; in different formats.  `format-alist' contains information that directs
  27 ;; Emacs to call an encoding or decoding function when reading or writing
  28 ;; files that match certain conditions.
  29 ;;
  30 ;; When a file is visited, its format is determined by matching the
  31 ;; beginning of the file against regular expressions stored in
  32 ;; `format-alist'.  If this fails, you can manually translate the buffer
  33 ;; using `format-decode-buffer'.  In either case, the formats used are
  34 ;; listed in the variable `buffer-file-format', and become the default
  35 ;; format for saving the buffer.  To save a buffer in a different format,
  36 ;; change this variable, or use `format-write-file'.
  37 ;;
  38 ;; Auto-save files are normally created in the same format as the visited
  39 ;; file, but the variable `buffer-auto-save-file-format' can be set to a
  40 ;; particularly fast or otherwise preferred format to be used for
  41 ;; auto-saving (or nil to do no encoding on auto-save files, but then you
  42 ;; risk losing any text-properties in the buffer).
  43 ;;
  44 ;; You can manually translate a buffer into or out of a particular format
  45 ;; with the functions `format-encode-buffer' and `format-decode-buffer'.
  46 ;; To translate just the region use the functions `format-encode-region'
  47 ;; and `format-decode-region'.
  48 ;;
  49 ;; You can define a new format by writing the encoding and decoding
  50 ;; functions, and adding an entry to `format-alist'.  See enriched.el for
  51 ;; an example of how to implement a file format.  There are various
  52 ;; functions defined in this file that may be useful for writing the
  53 ;; encoding and decoding functions:
  54 ;;  * `format-annotate-region' and `format-deannotate-region' allow a
  55 ;;     single alist of information to be used for encoding and decoding.
  56 ;;     The alist defines a correspondence between strings in the file
  57 ;;     ("annotations") and text-properties in the buffer.
  58 ;;  * `format-replace-strings' is similarly useful for doing simple
  59 ;;     string->string translations in a reversible manner.
  60
  61 ;;; Code:
  62
  63 (put 'buffer-file-format 'permanent-local t)
  64 (put 'buffer-auto-save-file-format 'permanent-local t)
  65
  66 (defvar format-alist
  67   ;; FIXME: maybe each item can be purecopied instead of just the strings.
  68   `((text/enriched ,(purecopy "Extended MIME text/enriched format.")
  69                    ,(purecopy "Content-[Tt]ype:[ \t]*text/enriched")
  70                    enriched-decode enriched-encode t enriched-mode)
  71     (plain ,(purecopy "ISO 8859-1 standard format, no text properties.")
  72            ;; Plain only exists so that there is an obvious neutral choice in
  73            ;; the completion list.
  74            nil nil nil nil nil)
  75     (TeX   ,(purecopy "TeX (encoding)")
  76            nil
  77            iso-tex2iso iso-iso2tex t nil)
  78     (gtex  ,(purecopy "German TeX (encoding)")
  79            nil
  80            iso-gtex2iso iso-iso2gtex t nil)
  81     (html  ,(purecopy "HTML/SGML \"ISO 8879:1986//ENTITIES Added Latin 1//EN\" (encoding)")
  82            nil
  83            iso-sgml2iso iso-iso2sgml t nil)
  84     (rot13 ,(purecopy "rot13")
  85            nil
  86            ,(purecopy "tr a-mn-z n-za-m") ,(purecopy "tr a-mn-z n-za-m") t nil)
  87     (duden ,(purecopy "Duden Ersatzdarstellung")
  88            nil
  89            ,(purecopy "diac") iso-iso2duden t nil)
  90     (de646 ,(purecopy "German ASCII (ISO 646)")
  91            nil
  92            ,(purecopy "recode -f iso646-ge:latin1")
  93            ,(purecopy "recode -f latin1:iso646-ge") t nil)
  94     (denet ,(purecopy "net German")
  95            nil
  96            iso-german iso-cvt-read-only t nil)
  97     (esnet ,(purecopy "net Spanish")
  98            nil
  99            iso-spanish iso-cvt-read-only t nil))
 100   "List of information about understood file formats.
 101 Elements are of the form
 102 \(NAME DOC-STR REGEXP FROM-FN TO-FN MODIFY MODE-FN PRESERVE).
 103
 104 NAME    is a symbol, which is stored in `buffer-file-format'.
 105
 106 DOC-STR should be a single line providing more information about the
 107         format.  It is currently unused, but in the future will be shown to
 108         the user if they ask for more information.
 109
 110 REGEXP  is a regular expression to match against the beginning of the file;
 111         it should match only files in that format.  REGEXP may be nil, in
 112         which case the format will never be applied automatically to a file.
 113         Use this for formats that you only ever want to apply manually.
 114
 115 FROM-FN is called to decode files in that format; it takes two args, BEGIN
 116         and END, and can make any modifications it likes, returning the new
 117         end.  It must make sure that the beginning of the file no longer
 118         matches REGEXP, or else it will get called again.
 119         Alternatively, FROM-FN can be a string, which specifies a shell command
 120         (including options) to be used as a filter to perform the conversion.
 121
 122 TO-FN   is called to encode a region into that format; it takes three
 123         arguments: BEGIN, END, and BUFFER.  BUFFER is the original buffer that
 124         the data being written came from, which the function could use, for
 125         example, to find the values of local variables.  TO-FN should either
 126         return a list of annotations like `write-region-annotate-functions',
 127         or modify the region and return the new end.
 128         Alternatively, TO-FN can be a string, which specifies a shell command
 129         (including options) to be used as a filter to perform the conversion.
 130
 131 MODIFY, if non-nil, means the TO-FN wants to modify the region.  If nil,
 132         TO-FN will not make any changes but will instead return a list of
 133         annotations.
 134
 135 MODE-FN, if specified, is called when visiting a file with that format.
 136          It is called with a single positive argument, on the assumption
 137          that this would turn on some minor mode.
 138
 139 PRESERVE, if non-nil, means that `format-write-file' should not remove
 140           this format from `buffer-file-format'.")
 141 ;;;###autoload
 142 (put 'format-alist 'risky-local-variable t)
 143
 144 ;;; Basic Functions (called from Lisp)
 145
 146 (defun format-encode-run-method (method from to &optional buffer)
 147   "Translate using METHOD the text from FROM to TO.
 148 If METHOD is a string, it is a shell command (including options);
 149 otherwise, it should be a Lisp function.
 150 BUFFER should be the buffer that the output originally came from."
 151   (if (stringp method)
 152       (let ((error-buff (get-buffer-create "*Format Errors*"))
 153             (coding-system-for-read 'no-conversion)
 154             format-alist)
 155         (with-current-buffer error-buff
 156           (widen)
 157           (erase-buffer))
 158         (if (and (zerop (save-window-excursion
 159                           (shell-command-on-region from to method t t
 160                                                    error-buff)))
 161                  ;; gzip gives zero exit status with bad args, for instance.
 162                  (zerop (with-current-buffer error-buff
 163                           (buffer-size))))
 164             (bury-buffer error-buff)
 165           (switch-to-buffer-other-window error-buff)
 166           (error "Format encoding failed")))
 167     (funcall method from to buffer)))
 168
 169 (defun format-decode-run-method (method from to &optional buffer)
 170   "Decode using METHOD the text from FROM to TO.
 171 If METHOD is a string, it is a shell command (including options); otherwise,
 172 it should be a Lisp function.  Decoding is done for the given BUFFER."
 173   (if (stringp method)
 174       (let ((error-buff (get-buffer-create "*Format Errors*"))
 175             (coding-system-for-write 'no-conversion)
 176             format-alist)
 177         (with-current-buffer error-buff
 178           (widen)
 179           (erase-buffer))
 180         ;; We should perhaps go via a temporary buffer and copy it
 181         ;; back, in case of errors.
 182         (if (and (zerop (save-window-excursion
 183                           (shell-command-on-region (point-min) (point-max)
 184                                                    method t t
 185                                                    error-buff)))
 186                  ;; gzip gives zero exit status with bad args, for instance.
 187                  (zerop (with-current-buffer error-buff
 188                           (buffer-size))))
 189             (bury-buffer error-buff)
 190           (switch-to-buffer-other-window error-buff)
 191           (error "Format decoding failed"))
 192         (point))
 193     (funcall method from to)))
 194
 195 (defun format-annotate-function (format from to orig-buf format-count)
 196   "Return annotations for writing region as FORMAT.
 197 FORMAT is a symbol naming one of the formats defined in `format-alist'.
 198 It must be a single symbol, not a list like `buffer-file-format'.
 199 FROM and TO delimit the region to be operated on in the current buffer.
 200 ORIG-BUF is the original buffer that the data came from.
 201
 202 FORMAT-COUNT is an integer specifying how many times this function has
 203 been called in the process of decoding ORIG-BUF.
 204
 205 This function works like a function in `write-region-annotate-functions':
 206 it either returns a list of annotations, or returns with a different buffer
 207 current, which contains the modified text to write.  In the latter case,
 208 this function's value is nil.
 209
 210 For most purposes, consider using `format-encode-region' instead."
 211   ;; This function is called by write-region (actually
 212   ;; build_annotations) for each element of buffer-file-format.
 213   (let* ((info (assq format format-alist))
 214          (to-fn  (nth 4 info))
 215          (modify (nth 5 info)))
 216     (if to-fn
 217         (if modify
 218             ;; To-function wants to modify region.  Copy to safe place.
 219             (let ((copy-buf (get-buffer-create (format " *Format Temp %d*"
 220                                                        format-count)))
 221                   (sel-disp selective-display)
 222                   (multibyte enable-multibyte-characters)
 223                   (coding-system buffer-file-coding-system))
 224               (with-current-buffer copy-buf
 225                 (set (make-local-variable
 226                       'write-region-post-annotation-function)
 227                      'kill-buffer)
 228                 (setq selective-display sel-disp)
 229                 (set-buffer-multibyte multibyte)
 230                 (setq buffer-file-coding-system coding-system))
 231               (copy-to-buffer copy-buf from to)
 232               (set-buffer copy-buf)
 233               (format-insert-annotations write-region-annotations-so-far from)
 234               (format-encode-run-method to-fn (point-min) (point-max) orig-buf)
 235               nil)
 236           ;; Otherwise just call function, it will return annotations.
 237           (funcall to-fn from to orig-buf)))))
 238
 239 (defun format-decode (format length &optional visit-flag)
 240   ;; This function is called by insert-file-contents whenever a file is read.
 241   "Decode text from any known FORMAT.
 242 FORMAT is a symbol appearing in `format-alist' or a list of such symbols,
 243 or nil, in which case this function tries to guess the format of the data by
 244 matching against the regular expressions in `format-alist'.  After a match is
 245 found and the region decoded, the alist is searched again from the beginning
 246 for another match.
 247
 248 Second arg LENGTH is the number of characters following point to operate on.
 249 If optional third arg VISIT-FLAG is true, set `buffer-file-format'
 250 to the reverted list of formats used, and call any mode functions defined
 251 for those formats.
 252
 253 Return the new length of the decoded region.
 254
 255 For most purposes, consider using `format-decode-region' instead."
 256   (let ((mod (buffer-modified-p))
 257         (begin (point))
 258         (end (+ (point) length)))
 259     (unwind-protect
 260         (progn
 261           ;; Don't record undo information for the decoding.
 262
 263           (if (null format)
 264               ;; Figure out which format it is in, remember list in `format'.
 265               (let ((try format-alist))
 266                 (while try
 267                   (let* ((f (car try))
 268                          (regexp (nth 2 f))
 269                          (p (point)))
 270                     (if (and regexp (looking-at regexp)
 271                              (< (match-end 0) (+ begin length)))
 272                         (progn
 273                           (push (car f) format)
 274                           ;; Decode it
 275                           (if (nth 3 f)
 276                               (setq end (format-decode-run-method (nth 3 f) begin end)))
 277                           ;; Call visit function if required
 278                           (if (and visit-flag (nth 6 f)) (funcall (nth 6 f) 1))
 279                           ;; Safeguard against either of the functions changing pt.
 280                           (goto-char p)
 281                           ;; Rewind list to look for another format
 282                           (setq try format-alist))
 283                       (setq try (cdr try))))))
 284             ;; Deal with given format(s)
 285             (or (listp format) (setq format (list format)))
 286             (let ((do format) f)
 287               (while do
 288                 (or (setq f (assq (car do) format-alist))
 289                     (error "Unknown format %s" (car do)))
 290                 ;; Decode:
 291                 (if (nth 3 f)
 292                     (setq end (format-decode-run-method (nth 3 f) begin end)))
 293                 ;; Call visit function if required
 294                 (if (and visit-flag (nth 6 f)) (funcall (nth 6 f) 1))
 295                 (setq do (cdr do))))
 296             ;; Encode in the opposite order.
 297             (setq format (reverse format)))
 298           (if visit-flag
 299               (setq buffer-file-format format)))
 300
 301       (set-buffer-modified-p mod))
 302
 303       ;; Return new length of region
 304     (- end begin)))
 305
 306 ;;;
 307 ;;; Interactive functions & entry points
 308 ;;;
 309
 310 (defun format-decode-buffer (&optional format)
 311   "Translate the buffer from some FORMAT.
 312 If the format is not specified, attempt a regexp-based guess.
 313 Set `buffer-file-format' to the format used, and call any
 314 format-specific mode functions."
 315   (interactive
 316    (list (format-read "Translate buffer from format (default guess): ")))
 317   (save-excursion
 318     (goto-char (point-min))
 319     (format-decode format (buffer-size) t)))
 320
 321 (defun format-decode-region (from to &optional format)
 322   "Decode the region from some format.
 323 Arg FORMAT is optional; if omitted the format will be determined by looking
 324 for identifying regular expressions at the beginning of the region."
 325   (interactive
 326    (list (region-beginning) (region-end)
 327          (format-read "Translate region from format (default guess): ")))
 328   (save-excursion
 329     (goto-char from)
 330     (format-decode format (- to from) nil)))
 331
 332 (defun format-encode-buffer (&optional format)
 333   "Translate the buffer into FORMAT.
 334 FORMAT defaults to `buffer-file-format'.  It is a symbol naming one of the
 335 formats defined in `format-alist', or a list of such symbols."
 336   (interactive
 337    (list (format-read (format "Translate buffer to format (default %s): "
 338                               buffer-file-format))))
 339   (format-encode-region (point-min) (point-max) format))
 340
 341 (defun format-encode-region (beg end &optional format)
 342   "Translate the region into some FORMAT.
 343 FORMAT defaults to `buffer-file-format'.  It is a symbol naming
 344 one of the formats defined in `format-alist', or a list of such symbols."
 345   (interactive
 346    (list (region-beginning) (region-end)
 347          (format-read (format "Translate region to format (default %s): "
 348                               buffer-file-format))))
 349   (if (null format)    (setq format buffer-file-format))
 350   (if (symbolp format) (setq format (list format)))
 351   (save-excursion
 352     (goto-char end)
 353     (let ((cur-buf (current-buffer))
 354           (end (point-marker)))
 355       (while format
 356         (let* ((info (assq (car format) format-alist))
 357                (to-fn  (nth 4 info))
 358                (modify (nth 5 info))
 359                result)
 360           (if to-fn
 361               (if modify
 362                   (setq end (format-encode-run-method to-fn beg end
 363                                                       (current-buffer)))
 364                 (format-insert-annotations
 365                  (funcall to-fn beg end (current-buffer)))))
 366           (setq format (cdr format)))))))
 367
 368 (defun format-write-file (filename format &optional confirm)
 369   "Write current buffer into FILENAME, using a format based on FORMAT.
 370 Constructs the actual format starting from FORMAT, then appending
 371 any elements from the value of `buffer-file-format' with a non-nil
 372 `preserve' flag (see the documentation of `format-alist'), if they
 373 are not already present in FORMAT.  It then updates `buffer-file-format'
 374 with this format, making it the default for future saves.
 375
 376 If the buffer is already visiting a file, you can specify a
 377 directory name as FILENAME, to write a file of the same old name
 378 in that directory.
 379
 380 If optional third arg CONFIRM is non-nil, asks for confirmation before
 381 overwriting an existing file.  Interactively, requires confirmation
 382 unless you supply a prefix argument."
 383   (interactive
 384    ;; Same interactive spec as write-file, plus format question.
 385    (let* ((file (if buffer-file-name
 386                     (read-file-name "Write file: "
 387                                     nil nil nil nil)
 388                   (read-file-name "Write file: "
 389                                   (cdr (assq 'default-directory
 390                                              (buffer-local-variables)))
 391                                   nil nil (buffer-name))))
 392           (fmt (format-read (format "Write file `%s' in format: "
 393                                     (file-name-nondirectory file)))))
 394      (list file fmt (not current-prefix-arg))))
 395   (let ((old-formats buffer-file-format)
 396         preserve-formats)
 397     (dolist (fmt old-formats)
 398       (let ((aelt (assq fmt format-alist)))
 399         (if (nth 7 aelt)
 400             (push fmt preserve-formats))))
 401     (setq buffer-file-format format)
 402     (dolist (fmt preserve-formats)
 403       (unless (memq fmt buffer-file-format)
 404         (setq buffer-file-format (append buffer-file-format (list fmt))))))
 405   (write-file filename confirm))
 406
 407 (defun format-find-file (filename format)
 408   "Find the file FILENAME using data format FORMAT.
 409 If FORMAT is nil then do not do any format conversion."
 410   (interactive
 411    ;; Same interactive spec as write-file, plus format question.
 412    (let* ((file (read-file-name "Find file: "))
 413           (fmt (format-read (format "Read file `%s' in format: "
 414                                     (file-name-nondirectory file)))))
 415      (list file fmt)))
 416   (let ((format-alist nil))
 417      (find-file filename))
 418   (if format
 419       (format-decode-buffer format)))
 420
 421 (defun format-insert-file (filename format &optional beg end)
 422   "Insert the contents of file FILENAME using data format FORMAT.
 423 If FORMAT is nil then do not do any format conversion.
 424 The optional third and fourth arguments BEG and END specify
 425 the part (in bytes) of the file to read.
 426
 427 The return value is like the value of `insert-file-contents':
 428 a list (ABSOLUTE-FILE-NAME SIZE)."
 429   (interactive
 430    ;; Same interactive spec as write-file, plus format question.
 431    (let* ((file (read-file-name "Find file: "))
 432           (fmt (format-read (format "Read file `%s' in format: "
 433                                     (file-name-nondirectory file)))))
 434      (list file fmt)))
 435   (let (value size old-undo)
 436     ;; Record only one undo entry for the insertion.  Inhibit point-motion and
 437     ;; modification hooks as with `insert-file-contents'.
 438     (let ((inhibit-point-motion-hooks t)
 439           (inhibit-modification-hooks t))
 440       ;; Don't bind `buffer-undo-list' to t here to assert that
 441       ;; `insert-file-contents' may record whether the buffer was unmodified
 442       ;; before.
 443       (let ((format-alist nil))
 444         (setq value (insert-file-contents filename nil beg end))
 445         (setq size (nth 1 value)))
 446       (when (consp buffer-undo-list)
 447         (let ((head (car buffer-undo-list)))
 448           (when (and (consp head)
 449                      (equal (car head) (point))
 450                      (equal (cdr head) (+ (point) size)))
 451             ;; Remove first entry from `buffer-undo-list', we shall insert
 452             ;; another one below.
 453             (setq old-undo (cdr buffer-undo-list)))))
 454       (when format
 455         (let ((buffer-undo-list t))
 456           (setq size (format-decode format size)
 457                 value (list (car value) size)))
 458         (unless (eq buffer-undo-list t)
 459           (setq buffer-undo-list
 460                 (cons (cons (point) (+ (point) size)) old-undo)))))
 461     (unless inhibit-modification-hooks
 462       (run-hook-with-args 'after-change-functions (point) (+ (point) size) 0))
 463     value))
 464
 465 (defun format-read (&optional prompt)
 466   "Read and return the name of a format.
 467 Return value is a list, like `buffer-file-format'; it may be nil.
 468 Formats are defined in `format-alist'.  Optional arg is the PROMPT to use."
 469   (let* ((table (mapcar (lambda (x) (list (symbol-name (car x))))
 470                         format-alist))
 471          (ans (completing-read (or prompt "Format: ") table nil t)))
 472     (if (not (equal "" ans)) (list (intern ans)))))
 473
 474
 475 ;;;
 476 ;;; Below are some functions that may be useful in writing encoding and
 477 ;;; decoding functions for use in format-alist.
 478 ;;;
 479
 480 (defun format-replace-strings (alist &optional reverse beg end)
 481   "Do multiple replacements on the buffer.
 482 ALIST is a list of (FROM . TO) pairs, which should be proper arguments to
 483 `search-forward' and `replace-match', respectively.
 484 Optional second arg REVERSE, if non-nil, means the pairs are (TO . FROM),
 485 so that you can use the same list in both directions if it contains only
 486 literal strings.
 487 Optional args BEG and END specify a region of the buffer on which to operate."
 488   (save-excursion
 489     (save-restriction
 490       (or beg (setq beg (point-min)))
 491       (if end (narrow-to-region (point-min) end))
 492       (while alist
 493         (let ((from (if reverse (cdr (car alist)) (car (car alist))))
 494               (to   (if reverse (car (car alist)) (cdr (car alist)))))
 495           (goto-char beg)
 496           (while (search-forward from nil t)
 497             (goto-char (match-beginning 0))
 498             (insert to)
 499             (set-text-properties (- (point) (length to)) (point)
 500                                  (text-properties-at (point)))
 501             (delete-region (point) (+ (point) (- (match-end 0)
 502                                                  (match-beginning 0)))))
 503           (setq alist (cdr alist)))))))
 504
 505 ;;; Some list-manipulation functions that we need.
 506
 507 (defun format-delq-cons (cons list)
 508   "Remove the given CONS from LIST by side effect and return the new LIST.
 509 Since CONS could be the first element of LIST, write
 510 `\(setq foo \(format-delq-cons element foo))' to be sure of changing
 511 the value of `foo'."
 512   (if (eq cons list)
 513       (cdr list)
 514     (let ((p list))
 515       (while (not (eq (cdr p) cons))
 516         (if (null p) (error "format-delq-cons: not an element"))
 517         (setq p (cdr p)))
 518       ;; Now (cdr p) is the cons to delete
 519       (setcdr p (cdr cons))
 520       list)))
 521
 522 (defun format-make-relatively-unique (a b)
 523   "Delete common elements of lists A and B, return as pair.
 524 Compare using `equal'."
 525   (let* ((acopy (copy-sequence a))
 526          (bcopy (copy-sequence b))
 527          (tail acopy))
 528     (while tail
 529       (let ((dup (member (car tail) bcopy))
 530             (next (cdr tail)))
 531         (if dup (setq acopy (format-delq-cons tail acopy)
 532                       bcopy (format-delq-cons dup  bcopy)))
 533         (setq tail next)))
 534     (cons acopy bcopy)))
 535
 536 (defun format-common-tail (a b)
 537   "Given two lists that have a common tail, return it.
 538 Compare with `equal', and return the part of A that is equal to the
 539 equivalent part of B.  If even the last items of the two are not equal,
 540 return nil."
 541   (let ((la (length a))
 542         (lb (length b)))
 543     ;; Make sure they are the same length
 544     (if (> la lb)
 545         (setq a (nthcdr (- la lb) a))
 546       (setq b (nthcdr (- lb la) b))))
 547   (while (not (equal a b))
 548     (setq a (cdr a)
 549           b (cdr b)))
 550   a)
 551
 552 (defun format-proper-list-p (list)
 553   "Return t if LIST is a proper list.
 554 A proper list is a list ending with a nil cdr, not with an atom "
 555   (when (listp list)
 556     (while (consp list)
 557       (setq list (cdr list)))
 558     (null list)))
 559
 560 (defun format-reorder (items order)
 561   "Arrange ITEMS to follow partial ORDER.
 562 Elements of ITEMS equal to elements of ORDER will be rearranged
 563 to follow the ORDER.  Unmatched items will go last."
 564   (if order
 565       (let ((item (member (car order) items)))
 566         (if item
 567             (cons (car item)
 568                   (format-reorder (format-delq-cons item items)
 569                            (cdr order)))
 570           (format-reorder items (cdr order))))
 571     items))
 572
 573 (put 'face 'format-list-valued t)       ; These text-properties take values
 574 (put 'unknown 'format-list-valued t)    ; that are lists, the elements of which
 575                                         ; should be considered separately.
 576                                         ; See format-deannotate-region and
 577                                         ; format-annotate-region.
 578
 579 ;; This text property has list values, but they are treated atomically.
 580
 581 (put 'display 'format-list-atomic-p t)
 582
 583 ;;;
 584 ;;; Decoding
 585 ;;;
 586
 587 (defun format-deannotate-region (from to translations next-fn)
 588   "Translate annotations in the region into text properties.
 589 This sets text properties between FROM to TO as directed by the
 590 TRANSLATIONS and NEXT-FN arguments.
 591
 592 NEXT-FN is a function that searches forward from point for an annotation.
 593 It should return a list of 4 elements: \(BEGIN END NAME POSITIVE).  BEGIN and
 594 END are buffer positions bounding the annotation, NAME is the name searched
 595 for in TRANSLATIONS, and POSITIVE should be non-nil if this annotation marks
 596 the beginning of a region with some property, or nil if it ends the region.
 597 NEXT-FN should return nil if there are no annotations after point.
 598
 599 The basic format of the TRANSLATIONS argument is described in the
 600 documentation for the `format-annotate-region' function.  There are some
 601 additional things to keep in mind for decoding, though:
 602
 603 When an annotation is found, the TRANSLATIONS list is searched for a
 604 text-property name and value that corresponds to that annotation.  If the
 605 text-property has several annotations associated with it, it will be used only
 606 if the other annotations are also in effect at that point.  The first match
 607 found whose annotations are all present is used.
 608
 609 The text property thus determined is set to the value over the region between
 610 the opening and closing annotations.  However, if the text-property name has a
 611 non-nil `format-list-valued' property, then the value will be consed onto the
 612 surrounding value of the property, rather than replacing that value.
 613
 614 There are some special symbols that can be used in the \"property\" slot of
 615 the TRANSLATIONS list: PARAMETER and FUNCTION \(spelled in uppercase).
 616 Annotations listed under the pseudo-property PARAMETER are considered to be
 617 arguments of the immediately surrounding annotation; the text between the
 618 opening and closing parameter annotations is deleted from the buffer but saved
 619 as a string.
 620
 621 The surrounding annotation should be listed under the pseudo-property
 622 FUNCTION.  Instead of inserting a text-property for this annotation,
 623 the function listed in the VALUE slot is called to make whatever
 624 changes are appropriate.  It can also return a list of the form
 625 \(START LOC PROP VALUE) which specifies a property to put on.  The
 626 function's first two arguments are the START and END locations, and
 627 the rest of the arguments are any PARAMETERs found in that region.
 628
 629 Any annotations that are found by NEXT-FN but not defined by TRANSLATIONS
 630 are saved as values of the `unknown' text-property \(which is list-valued).
 631 The TRANSLATIONS list should usually contain an entry of the form
 632     \(unknown \(nil format-annotate-value))
 633 to write these unknown annotations back into the file."
 634   (save-excursion
 635     (save-restriction
 636       (narrow-to-region (point-min) to)
 637       (goto-char from)
 638       (let (next open-ans todo loc unknown-ans)
 639         (while (setq next (funcall next-fn))
 640           (let* ((loc      (nth 0 next))
 641                  (end      (nth 1 next))
 642                  (name     (nth 2 next))
 643                  (positive (nth 3 next))
 644                  (found    nil))
 645
 646             ;; Delete the annotation
 647             (delete-region loc end)
 648             (cond
 649              ;; Positive annotations are stacked, remembering location
 650              (positive (push `(,name ((,loc . nil))) open-ans))
 651              ;; It is a negative annotation:
 652              ;; Close the top annotation & add its text property.
 653              ;; If the file's nesting is messed up, the close might not match
 654              ;; the top thing on the open-annotations stack.
 655              ;; If no matching annotation is open, just ignore the close.
 656              ((not (assoc name open-ans))
 657               (message "Extra closing annotation (%s) in file" name))
 658              ;; If one is open, but not on the top of the stack, close
 659              ;; the things in between as well.  Set `found' when the real
 660              ;; one is closed.
 661              (t
 662               (while (not found)
 663                 (let* ((top (car open-ans))     ; first on stack: should match.
 664                        (top-name (car top))     ; text property name
 665                        (top-extents (nth 1 top)) ; property regions
 666                        (params (cdr (cdr top))) ; parameters
 667                        (aalist translations)
 668                        (matched nil))
 669                   (if (equal name top-name)
 670                       (setq found t)
 671                     (message "Improper nesting in file."))
 672                   ;; Look through property names in TRANSLATIONS
 673                   (while aalist
 674                     (let ((prop (car (car aalist)))
 675                           (alist (cdr (car aalist))))
 676                       ;; And look through values for each property
 677                       (while alist
 678                         (let ((value (car (car alist)))
 679                               (ans (cdr (car alist))))
 680                           (if (member top-name ans)
 681                               ;; This annotation is listed, but still have to
 682                               ;; check if multiple annotations are satisfied
 683                               (if (member nil (mapcar (lambda (r)
 684                                                         (assoc r open-ans))
 685                                                       ans))
 686                                   nil   ; multiple ans not satisfied
 687                                 ;; If there are multiple annotations going
 688                                 ;; into one text property, split up the other
 689                                 ;; annotations so they apply individually to
 690                                 ;; the other regions.
 691                                 (setcdr (car top-extents) loc)
 692                                 (let ((to-split ans) this-one extents)
 693                                   (while to-split
 694                                     (setq this-one
 695                                           (assoc (car to-split) open-ans)
 696                                           extents (nth 1 this-one))
 697                                     (if (not (eq this-one top))
 698                                         (setcar (cdr this-one)
 699                                                 (format-subtract-regions
 700                                                  extents top-extents)))
 701                                     (setq to-split (cdr to-split))))
 702                                 ;; Set loop variables to nil so loop
 703                                 ;; will exit.
 704                                 (setq alist nil aalist nil matched t
 705                                       ;; pop annotation off stack.
 706                                       open-ans (cdr open-ans))
 707                                 (let ((extents top-extents)
 708                                       (start (car (car top-extents)))
 709                                       (loc (cdr (car top-extents))))
 710                                   (while extents
 711                                     (cond
 712                                      ;; Check for pseudo-properties
 713                                      ((eq prop 'PARAMETER)
 714                                       ;; A parameter of the top open ann:
 715                                       ;; delete text and use as arg.
 716                                       (if open-ans
 717                                           ;; (If nothing open, discard).
 718                                           (setq open-ans
 719                                                 (cons
 720                                                  (append (car open-ans)
 721                                                          (list
 722                                                           (buffer-substring
 723                                                            start loc)))
 724                                                  (cdr open-ans))))
 725                                       (delete-region start loc))
 726                                      ((eq prop 'FUNCTION)
 727                                       ;; Not a property, but a function.
 728                                       (let ((rtn
 729                                              (apply value start loc params)))
 730                                         (if rtn (push rtn todo))))
 731                                      (t
 732                                       ;; Normal property/value pair
 733                                       (setq todo
 734                                             (cons (list start loc prop value)
 735                                                   todo))))
 736                                     (setq extents (cdr extents)
 737                                           start (car (car extents))
 738                                           loc (cdr (car extents))))))))
 739                         (setq alist (cdr alist))))
 740                     (setq aalist (cdr aalist)))
 741                   (if (not matched)
 742                       ;; Didn't find any match for the annotation:
 743                       ;; Store as value of text-property `unknown'.
 744                       (let ((extents top-extents)
 745                             (start (car (car top-extents)))
 746                             (loc (or (cdr (car top-extents)) loc)))
 747                         (while extents
 748                           (setq open-ans (cdr open-ans)
 749                                 todo (cons (list start loc 'unknown top-name)
 750                                            todo)
 751                                 unknown-ans (cons name unknown-ans)
 752                                 extents (cdr extents)
 753                                 start (car (car extents))
 754                                 loc (cdr (car extents))))))))))))
 755
 756         ;; Once entire file has been scanned, add the properties.
 757         (while todo
 758           (let* ((item (car todo))
 759                  (from (nth 0 item))
 760                  (to   (nth 1 item))
 761                  (prop (nth 2 item))
 762                  (val  (nth 3 item)))
 763
 764             (if (numberp val)   ; add to ambient value if numeric
 765                 (format-property-increment-region from to prop val 0)
 766               (put-text-property
 767                from to prop
 768                (cond ((get prop 'format-list-valued) ; value gets consed onto
 769                                                      ; list-valued properties
 770                       (let ((prev (get-text-property from prop)))
 771                         (cons val (if (listp prev) prev (list prev)))))
 772                      (t val))))) ; normally, just set to val.
 773           (setq todo (cdr todo)))
 774
 775         (if unknown-ans
 776             (message "Unknown annotations: %s" unknown-ans))))))
 777
 778 (defun format-subtract-regions (minu subtra)
 779   "Remove from the regions in MINUEND the regions in SUBTRAHEND.
 780 A region is a dotted pair (FROM . TO).  Both parameters are lists of
 781 regions.  Each list must contain nonoverlapping, noncontiguous
 782 regions, in descending order.  The result is also nonoverlapping,
 783 noncontiguous, and in descending order.  The first element of MINUEND
 784 can have a cdr of nil, indicating that the end of that region is not
 785 yet known.
 786
 787 \(fn MINUEND SUBTRAHEND)"
 788   (let* ((minuend (copy-alist minu))
 789          (subtrahend (copy-alist subtra))
 790          (m (car minuend))
 791          (s (car subtrahend))
 792          results)
 793     (while (and minuend subtrahend)
 794       (cond
 795        ;; The minuend starts after the subtrahend ends; keep it.
 796        ((> (car m) (cdr s))
 797         (push m results)
 798         (setq minuend (cdr minuend)
 799               m (car minuend)))
 800        ;; The minuend extends beyond the end of the subtrahend.  Chop it off.
 801        ((or (null (cdr m)) (> (cdr m) (cdr s)))
 802         (push (cons (1+ (cdr s)) (cdr m)) results)
 803         (setcdr m (cdr s)))
 804        ;; The subtrahend starts after the minuend ends; throw it away.
 805        ((< (cdr m) (car s))
 806         (setq subtrahend (cdr subtrahend) s (car subtrahend)))
 807        ;; The subtrahend extends beyond the end of the minuend.  Chop it off.
 808        (t       ;(<= (cdr m) (cdr s)))
 809         (if (>= (car m) (car s))
 810             (setq minuend (cdr minuend) m (car minuend))
 811           (setcdr m (1- (car s)))
 812           (setq subtrahend (cdr subtrahend) s (car subtrahend))))))
 813     (nconc (nreverse results) minuend)))
 814
 815 ;; This should probably go somewhere other than format.el.  Then again,
 816 ;; indent.el has alter-text-property.  NOTE: We can also use
 817 ;; next-single-property-change instead of text-property-not-all, but then
 818 ;; we have to see if we passed TO.
 819 (defun format-property-increment-region (from to prop delta default)
 820   "In the region from FROM to TO increment property PROP by amount DELTA.
 821 DELTA may be negative.  If property PROP is nil anywhere
 822 in the region, it is treated as though it were DEFAULT."
 823   (let ((cur from) val newval next)
 824     (while cur
 825       (setq val    (get-text-property cur prop)
 826             newval (+ (or val default) delta)
 827             next   (text-property-not-all cur to prop val))
 828       (put-text-property cur (or next to) prop newval)
 829       (setq cur next))))
 830
 831 ;;;
 832 ;;; Encoding
 833 ;;;
 834
 835 (defun format-insert-annotations (list &optional offset)
 836   "Apply list of annotations to buffer as `write-region' would.
 837 Insert each element of the given LIST of buffer annotations at its
 838 appropriate place.  Use second arg OFFSET if the annotations' locations are
 839 not relative to the beginning of the buffer: annotations will be inserted
 840 at their location-OFFSET+1 \(ie, the offset is treated as the position of
 841 the first character in the buffer)."
 842   (if (not offset)
 843       (setq offset 0)
 844     (setq offset (1- offset)))
 845   (let ((l (reverse list)))
 846     (while l
 847       (goto-char (- (car (car l)) offset))
 848       (insert (cdr (car l)))
 849       (setq l (cdr l)))))
 850
 851 (defun format-annotate-value (old new)
 852   "Return OLD and NEW as a \(CLOSE . OPEN) annotation pair.
 853 Useful as a default function for TRANSLATIONS alist when the value of the text
 854 property is the name of the annotation that you want to use, as it is for the
 855 `unknown' text property."
 856   (cons (if old (list old))
 857         (if new (list new))))
 858
 859 (defun format-annotate-region (from to translations format-fn ignore)
 860   "Generate annotations for text properties in the region.
 861 Search for changes between FROM and TO, and describe them with a list of
 862 annotations as defined by alist TRANSLATIONS and FORMAT-FN.  IGNORE lists text
 863 properties not to consider; any text properties that are neither ignored nor
 864 listed in TRANSLATIONS are warned about.
 865 If you actually want to modify the region, give the return value of this
 866 function to `format-insert-annotations'.
 867
 868 Format of the TRANSLATIONS argument:
 869
 870 Each element is a list whose car is a PROPERTY, and the following
 871 elements have the form (VALUE ANNOTATIONS...).
 872 Whenever the property takes on the value VALUE, the annotations
 873 \(as formatted by FORMAT-FN) are inserted into the file.
 874 When the property stops having that value, the matching negated annotation
 875 will be inserted \(it may actually be closed earlier and reopened, if
 876 necessary, to keep proper nesting).
 877
 878 If VALUE is a list, then each element of the list is dealt with
 879 separately.
 880
 881 If a VALUE is numeric, then it is assumed that there is a single annotation
 882 and each occurrence of it increments the value of the property by that number.
 883 Thus, given the entry \(left-margin \(4 \"indent\")), if the left margin
 884 changes from 4 to 12, two <indent> annotations will be generated.
 885
 886 If the VALUE is nil, then instead of annotations, a function should be
 887 specified.  This function is used as a default: it is called for all
 888 transitions not explicitly listed in the table.  The function is called with
 889 two arguments, the OLD and NEW values of the property.  It should return
 890 a cons cell (CLOSE . OPEN) as `format-annotate-single-property-change' does.
 891
 892 The same TRANSLATIONS structure can be used in reverse for reading files."
 893   (let ((all-ans nil)    ; All annotations - becomes return value
 894         (open-ans nil)   ; Annotations not yet closed
 895         (loc nil)        ; Current location
 896         (not-found nil)) ; Properties that couldn't be saved
 897     (while (or (null loc)
 898                (and (setq loc (next-property-change loc nil to))
 899                     (< loc to)))
 900       (or loc (setq loc from))
 901       (let* ((ans (format-annotate-location loc (= loc from) ignore translations))
 902              (neg-ans (format-reorder (aref ans 0) open-ans))
 903              (pos-ans (aref ans 1))
 904              (ignored (aref ans 2)))
 905         (setq not-found (append ignored not-found)
 906               ignore    (append ignored ignore))
 907         ;; First do the negative (closing) annotations
 908         (while neg-ans
 909           ;; Check if it's missing.  This can happen (eg, a numeric property
 910           ;; going negative can generate closing annotations before there are
 911           ;; any open).  Warn user & ignore.
 912           (if (not (member (car neg-ans) open-ans))
 913               (message "Can't close %s: not open." (car neg-ans))
 914             (while (not (equal (car neg-ans) (car open-ans)))
 915               ;; To close anno. N, need to first close ans 1 to N-1,
 916               ;; remembering to re-open them later.
 917               (push (car open-ans) pos-ans)
 918               (setq all-ans
 919                     (cons (cons loc (funcall format-fn (car open-ans) nil))
 920                           all-ans))
 921               (setq open-ans (cdr open-ans)))
 922             ;; Now remove the one we're really interested in from open list.
 923             (setq open-ans (cdr open-ans))
 924             ;; And put the closing annotation here.
 925             (push (cons loc (funcall format-fn (car neg-ans) nil))
 926                   all-ans))
 927           (setq neg-ans (cdr neg-ans)))
 928         ;; Now deal with positive (opening) annotations
 929         (let ((p pos-ans))
 930           (while pos-ans
 931             (push (car pos-ans) open-ans)
 932             (push (cons loc (funcall format-fn (car pos-ans) t))
 933                   all-ans)
 934             (setq pos-ans (cdr pos-ans))))))
 935
 936     ;; Close any annotations still open
 937     (while open-ans
 938       (setq all-ans
 939             (cons (cons to (funcall format-fn (car open-ans) nil))
 940                   all-ans))
 941       (setq open-ans (cdr open-ans)))
 942     (if not-found
 943         (message "These text properties could not be saved:\n    %s"
 944                  not-found))
 945     (nreverse all-ans)))
 946
 947 ;;; Internal functions for format-annotate-region.
 948
 949 (defun format-annotate-location (loc all ignore translations)
 950   "Return annotation(s) needed at location LOC.
 951 This includes any properties that change between LOC - 1 and LOC.
 952 If ALL is true, don't look at previous location, but generate annotations for
 953 all non-nil properties.
 954 Third argument IGNORE is a list of text-properties not to consider.
 955 Use the TRANSLATIONS alist (see `format-annotate-region' for doc).
 956
 957 Return value is a vector of 3 elements:
 958 1. List of annotations to close
 959 2. List of annotations to open.
 960 3. List of properties that were ignored or couldn't be annotated.
 961
 962 The annotations in lists 1 and 2 need not be strings.
 963 They can be whatever the FORMAT-FN in `format-annotate-region'
 964 can handle.  If that is `enriched-make-annotation', they can be
 965 either strings, or lists of the form (PARAMETER VALUE)."
 966   (let* ((prev-loc (1- loc))
 967          (before-plist (if all nil (text-properties-at prev-loc)))
 968          (after-plist (text-properties-at loc))
 969          p negatives positives prop props not-found)
 970     ;; make list of all property names involved
 971     (setq p before-plist)
 972     (while p
 973       (if (not (memq (car p) props))
 974           (push (car p) props))
 975       (setq p (cdr (cdr p))))
 976     (setq p after-plist)
 977     (while p
 978       (if (not (memq (car p) props))
 979           (push (car p) props))
 980       (setq p (cdr (cdr p))))
 981
 982     (while props
 983       (setq prop (pop props))
 984       (if (memq prop ignore)
 985           nil  ; If it's been ignored before, ignore it now.
 986         (let ((before (if all nil (car (cdr (memq prop before-plist)))))
 987               (after (car (cdr (memq prop after-plist)))))
 988           (if (equal before after)
 989               nil ; no change; ignore
 990             (let ((result (format-annotate-single-property-change
 991                            prop before after translations)))
 992               (if (not result)
 993                   (push prop not-found)
 994                 (setq negatives (nconc negatives (car result))
 995                       positives (nconc positives (cdr result)))))))))
 996     (vector negatives positives not-found)))
 997
 998 (defun format-annotate-single-property-change (prop old new translations)
 999   "Return annotations for property PROP changing from OLD to NEW.
1000 These are searched for in the translations alist TRANSLATIONS
1001  (see `format-annotate-region' for the format).
1002 If NEW does not appear in the list, but there is a default function,
1003 then call that function.
1004 Return a cons of the form (CLOSE . OPEN)
1005 where CLOSE is a list of annotations to close
1006 and OPEN is a list of annotations to open.
1007
1008 The annotations in CLOSE and OPEN need not be strings.
1009 They can be whatever the FORMAT-FN in `format-annotate-region'
1010 can handle.  If that is `enriched-make-annotation', they can be
1011 either strings, or lists of the form (PARAMETER VALUE)."
1012
1013   (let ((prop-alist (cdr (assoc prop translations)))
1014         default)
1015     (if (not prop-alist)
1016         nil
1017       ;; If either old or new is a list, have to treat both that way.
1018       (if (and (or (listp old) (listp new))
1019                (not (get prop 'format-list-atomic-p)))
1020           (if (or (not (format-proper-list-p old))
1021                   (not (format-proper-list-p new)))
1022               (format-annotate-atomic-property-change prop-alist old new)
1023             (let* ((old (if (listp old) old (list old)))
1024                    (new (if (listp new) new (list new)))
1025                    (tail (format-common-tail old new))
1026                    close open)
1027               (while old
1028                 (setq close
1029                       (append (car (format-annotate-atomic-property-change
1030                                     prop-alist (car old) nil))
1031                               close)
1032                       old (cdr old)))
1033               (while new
1034                 (setq open
1035                       (append (cdr (format-annotate-atomic-property-change
1036                                     prop-alist nil (car new)))
1037                               open)
1038                       new (cdr new)))
1039               (format-make-relatively-unique close open)))
1040         (format-annotate-atomic-property-change prop-alist old new)))))
1041
1042 (defun format-annotate-atomic-property-change (prop-alist old new)
1043   "Internal function to annotate a single property change.
1044 PROP-ALIST is the relevant element of a TRANSLATIONS list.
1045 OLD and NEW are the values."
1046   (let (num-ann)
1047     ;; If old and new values are numbers,
1048     ;; look for a number in PROP-ALIST.
1049     (if (and (or (null old) (numberp old))
1050              (or (null new) (numberp new)))
1051         (progn
1052           (setq num-ann prop-alist)
1053           (while (and num-ann (not (numberp (car (car num-ann)))))
1054             (setq num-ann (cdr num-ann)))))
1055     (if num-ann
1056         ;; Numerical annotation - use difference
1057         (progn
1058           ;; If property is numeric, nil means 0
1059           (cond ((and (numberp old) (null new))
1060                  (setq new 0))
1061                 ((and (numberp new) (null old))
1062                  (setq old 0)))
1063
1064           (let* ((entry (car num-ann))
1065                  (increment (car entry))
1066                  (n (ceiling (/ (float (- new old)) (float increment))))
1067                  (anno (car (cdr entry))))
1068             (if (> n 0)
1069                 (cons nil (make-list n anno))
1070               (cons (make-list (- n) anno) nil))))
1071
1072       ;; Standard annotation
1073       (let ((close (and old (cdr (assoc old prop-alist))))
1074             (open  (and new (cdr (assoc new prop-alist)))))
1075         (if (or close open)
1076             (format-make-relatively-unique close open)
1077           ;; Call "Default" function, if any
1078           (let ((default (assq nil prop-alist)))
1079             (if default
1080                 (funcall (car (cdr default)) old new))))))))
1081
1082 (provide 'format)
1083
1084 ;; arch-tag: c387e9c7-a93d-47bf-89bc-8ca67e96755a
1085 ;;; format.el ends here