lisp/format.el

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