lisp/format.el

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