lisp/format.el

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