lisp/format.el

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