lisp/format.el

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