1 ;;; format.el --- read and save files in multiple formats
3 ;; Copyright (C) 1994, 1995, 1997, 1999, 2001, 2002, 2003, 2004, 2005,
4 ;; 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
6 ;; Author: Boris Goldowsky <boris@gnu.org>
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25 ;; This file defines a unified mechanism for saving & loading files stored
26 ;; in different formats. `format-alist' contains information that directs
27 ;; Emacs to call an encoding or decoding function when reading or writing
28 ;; files that match certain conditions.
30 ;; When a file is visited, its format is determined by matching the
31 ;; beginning of the file against regular expressions stored in
32 ;; `format-alist'. If this fails, you can manually translate the buffer
33 ;; using `format-decode-buffer'. In either case, the formats used are
34 ;; listed in the variable `buffer-file-format', and become the default
35 ;; format for saving the buffer. To save a buffer in a different format,
36 ;; change this variable, or use `format-write-file'.
38 ;; Auto-save files are normally created in the same format as the visited
39 ;; file, but the variable `buffer-auto-save-file-format' can be set to a
40 ;; particularly fast or otherwise preferred format to be used for
41 ;; auto-saving (or nil to do no encoding on auto-save files, but then you
42 ;; risk losing any text-properties in the buffer).
44 ;; You can manually translate a buffer into or out of a particular format
45 ;; with the functions `format-encode-buffer' and `format-decode-buffer'.
46 ;; To translate just the region use the functions `format-encode-region'
47 ;; and `format-decode-region'.
49 ;; You can define a new format by writing the encoding and decoding
50 ;; functions, and adding an entry to `format-alist'. See enriched.el for
51 ;; an example of how to implement a file format. There are various
52 ;; functions defined in this file that may be useful for writing the
53 ;; encoding and decoding functions:
54 ;; * `format-annotate-region' and `format-deannotate-region' allow a
55 ;; single alist of information to be used for encoding and decoding.
56 ;; The alist defines a correspondence between strings in the file
57 ;; ("annotations") and text-properties in the buffer.
58 ;; * `format-replace-strings' is similarly useful for doing simple
59 ;; string->string translations in a reversible manner.
63 (put 'buffer-file-format
'permanent-local t
)
64 (put 'buffer-auto-save-file-format
'permanent-local t
)
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.
76 iso-tex2iso iso-iso2tex t nil
)
77 (gtex "German TeX (encoding)"
79 iso-gtex2iso iso-iso2gtex t nil
)
80 (html "HTML/SGML \"ISO 8879:1986//ENTITIES Added Latin 1//EN\" (encoding)"
82 iso-sgml2iso iso-iso2sgml t nil
)
85 "tr a-mn-z n-za-m" "tr a-mn-z n-za-m" t nil
)
86 (duden "Duden Ersatzdarstellung"
88 "diac" iso-iso2duden t nil
)
89 (de646 "German ASCII (ISO 646)"
91 "recode -f iso646-ge:latin1" "recode -f latin1:iso646-ge" t nil
)
94 iso-german iso-cvt-read-only t nil
)
97 iso-spanish iso-cvt-read-only t nil
))
98 "List of information about understood file formats.
99 Elements are of the form
100 \(NAME DOC-STR REGEXP FROM-FN TO-FN MODIFY MODE-FN PRESERVE).
102 NAME is a symbol, which is stored in `buffer-file-format'.
104 DOC-STR should be a single line providing more information about the
105 format. It is currently unused, but in the future will be shown to
106 the user if they ask for more information.
108 REGEXP is a regular expression to match against the beginning of the file;
109 it should match only files in that format. REGEXP may be nil, in
110 which case the format will never be applied automatically to a file.
111 Use this for formats that you only ever want to apply manually.
113 FROM-FN is called to decode files in that format; it takes two args, BEGIN
114 and END, and can make any modifications it likes, returning the new
115 end. It must make sure that the beginning of the file no longer
116 matches REGEXP, or else it will get called again.
117 Alternatively, FROM-FN can be a string, which specifies a shell command
118 (including options) to be used as a filter to perform the conversion.
120 TO-FN is called to encode a region into that format; it takes three
121 arguments: BEGIN, END, and BUFFER. BUFFER is the original buffer that
122 the data being written came from, which the function could use, for
123 example, to find the values of local variables. TO-FN should either
124 return a list of annotations like `write-region-annotate-functions',
125 or modify the region and return the new end.
126 Alternatively, TO-FN can be a string, which specifies a shell command
127 (including options) to be used as a filter to perform the conversion.
129 MODIFY, if non-nil, means the TO-FN wants to modify the region. If nil,
130 TO-FN will not make any changes but will instead return a list of
133 MODE-FN, if specified, is called when visiting a file with that format.
134 It is called with a single positive argument, on the assumption
135 that this would turn on some minor mode.
137 PRESERVE, if non-nil, means that `format-write-file' should not remove
138 this format from `buffer-file-format'.")
139 ;; Autoload if this file no longer dumped.
140 (put 'format-alist
'risky-local-variable t
)
142 ;;; Basic Functions (called from Lisp)
144 (defun format-encode-run-method (method from to
&optional buffer
)
145 "Translate using METHOD the text from FROM to TO.
146 If METHOD is a string, it is a shell command (including options);
147 otherwise, it should be a Lisp function.
148 BUFFER should be the buffer that the output originally came from."
150 (let ((error-buff (get-buffer-create "*Format Errors*"))
151 (coding-system-for-read 'no-conversion
)
153 (with-current-buffer error-buff
156 (if (and (zerop (save-window-excursion
157 (shell-command-on-region from to method t t
159 ;; gzip gives zero exit status with bad args, for instance.
160 (zerop (with-current-buffer error-buff
162 (bury-buffer error-buff
)
163 (switch-to-buffer-other-window error-buff
)
164 (error "Format encoding failed")))
165 (funcall method from to buffer
)))
167 (defun format-decode-run-method (method from to
&optional buffer
)
168 "Decode using METHOD the text from FROM to TO.
169 If METHOD is a string, it is a shell command (including options); otherwise,
170 it should be a Lisp function. Decoding is done for the given BUFFER."
172 (let ((error-buff (get-buffer-create "*Format Errors*"))
173 (coding-system-for-write 'no-conversion
)
175 (with-current-buffer error-buff
178 ;; We should perhaps go via a temporary buffer and copy it
179 ;; back, in case of errors.
180 (if (and (zerop (save-window-excursion
181 (shell-command-on-region (point-min) (point-max)
184 ;; gzip gives zero exit status with bad args, for instance.
185 (zerop (with-current-buffer error-buff
187 (bury-buffer error-buff
)
188 (switch-to-buffer-other-window error-buff
)
189 (error "Format decoding failed"))
191 (funcall method from to
)))
193 (defun format-annotate-function (format from to orig-buf format-count
)
194 "Return annotations for writing region as FORMAT.
195 FORMAT is a symbol naming one of the formats defined in `format-alist'.
196 It must be a single symbol, not a list like `buffer-file-format'.
197 FROM and TO delimit the region to be operated on in the current buffer.
198 ORIG-BUF is the original buffer that the data came from.
200 FORMAT-COUNT is an integer specifying how many times this function has
201 been called in the process of decoding ORIG-BUF.
203 This function works like a function in `write-region-annotate-functions':
204 it either returns a list of annotations, or returns with a different buffer
205 current, which contains the modified text to write. In the latter case,
206 this function's value is nil.
208 For most purposes, consider using `format-encode-region' instead."
209 ;; This function is called by write-region (actually
210 ;; build_annotations) for each element of buffer-file-format.
211 (let* ((info (assq format format-alist
))
213 (modify (nth 5 info
)))
216 ;; To-function wants to modify region. Copy to safe place.
217 (let ((copy-buf (get-buffer-create (format " *Format Temp %d*"
219 (sel-disp selective-display
)
220 (multibyte enable-multibyte-characters
)
221 (coding-system buffer-file-coding-system
))
222 (with-current-buffer copy-buf
223 (set (make-local-variable
224 'write-region-post-annotation-function
)
226 (setq selective-display sel-disp
)
227 (set-buffer-multibyte multibyte
)
228 (setq buffer-file-coding-system coding-system
))
229 (copy-to-buffer copy-buf from to
)
230 (set-buffer copy-buf
)
231 (format-insert-annotations write-region-annotations-so-far from
)
232 (format-encode-run-method to-fn
(point-min) (point-max) orig-buf
)
234 ;; Otherwise just call function, it will return annotations.
235 (funcall to-fn from to orig-buf
)))))
237 (defun format-decode (format length
&optional visit-flag
)
238 ;; This function is called by insert-file-contents whenever a file is read.
239 "Decode text from any known FORMAT.
240 FORMAT is a symbol appearing in `format-alist' or a list of such symbols,
241 or nil, in which case this function tries to guess the format of the data by
242 matching against the regular expressions in `format-alist'. After a match is
243 found and the region decoded, the alist is searched again from the beginning
246 Second arg LENGTH is the number of characters following point to operate on.
247 If optional third arg VISIT-FLAG is true, set `buffer-file-format'
248 to the reverted list of formats used, and call any mode functions defined
251 Return the new length of the decoded region.
253 For most purposes, consider using `format-decode-region' instead."
254 (let ((mod (buffer-modified-p))
256 (end (+ (point) length
)))
259 ;; Don't record undo information for the decoding.
262 ;; Figure out which format it is in, remember list in `format'.
263 (let ((try format-alist
))
268 (if (and regexp
(looking-at regexp
)
269 (< (match-end 0) (+ begin length
)))
271 (push (car f
) format
)
274 (setq end
(format-decode-run-method (nth 3 f
) begin end
)))
275 ;; Call visit function if required
276 (if (and visit-flag
(nth 6 f
)) (funcall (nth 6 f
) 1))
277 ;; Safeguard against either of the functions changing pt.
279 ;; Rewind list to look for another format
280 (setq try format-alist
))
281 (setq try
(cdr try
))))))
282 ;; Deal with given format(s)
283 (or (listp format
) (setq format
(list format
)))
286 (or (setq f
(assq (car do
) format-alist
))
287 (error "Unknown format %s" (car do
)))
290 (setq end
(format-decode-run-method (nth 3 f
) begin end
)))
291 ;; Call visit function if required
292 (if (and visit-flag
(nth 6 f
)) (funcall (nth 6 f
) 1))
294 ;; Encode in the opposite order.
295 (setq format
(reverse format
)))
297 (setq buffer-file-format format
)))
299 (set-buffer-modified-p mod
))
301 ;; Return new length of region
305 ;;; Interactive functions & entry points
308 (defun format-decode-buffer (&optional format
)
309 "Translate the buffer from some FORMAT.
310 If the format is not specified, attempt a regexp-based guess.
311 Set `buffer-file-format' to the format used, and call any
312 format-specific mode functions."
314 (list (format-read "Translate buffer from format (default guess): ")))
316 (goto-char (point-min))
317 (format-decode format
(buffer-size) t
)))
319 (defun format-decode-region (from to
&optional format
)
320 "Decode the region from some format.
321 Arg FORMAT is optional; if omitted the format will be determined by looking
322 for identifying regular expressions at the beginning of the region."
324 (list (region-beginning) (region-end)
325 (format-read "Translate region from format (default guess): ")))
328 (format-decode format
(- to from
) nil
)))
330 (defun format-encode-buffer (&optional format
)
331 "Translate the buffer into FORMAT.
332 FORMAT defaults to `buffer-file-format'. It is a symbol naming one of the
333 formats defined in `format-alist', or a list of such symbols."
335 (list (format-read (format "Translate buffer to format (default %s): "
336 buffer-file-format
))))
337 (format-encode-region (point-min) (point-max) format
))
339 (defun format-encode-region (beg end
&optional format
)
340 "Translate the region into some FORMAT.
341 FORMAT defaults to `buffer-file-format'. It is a symbol naming
342 one of the formats defined in `format-alist', or a list of such symbols."
344 (list (region-beginning) (region-end)
345 (format-read (format "Translate region to format (default %s): "
346 buffer-file-format
))))
347 (if (null format
) (setq format buffer-file-format
))
348 (if (symbolp format
) (setq format
(list format
)))
351 (let ((cur-buf (current-buffer))
352 (end (point-marker)))
354 (let* ((info (assq (car format
) format-alist
))
356 (modify (nth 5 info
))
360 (setq end
(format-encode-run-method to-fn beg end
362 (format-insert-annotations
363 (funcall to-fn beg end
(current-buffer)))))
364 (setq format
(cdr format
)))))))
366 (defun format-write-file (filename format
&optional confirm
)
367 "Write current buffer into FILENAME, using a format based on FORMAT.
368 Constructs the actual format starting from FORMAT, then appending
369 any elements from the value of `buffer-file-format' with a non-nil
370 `preserve' flag (see the documentation of `format-alist'), if they
371 are not already present in FORMAT. It then updates `buffer-file-format'
372 with this format, making it the default for future saves.
374 If the buffer is already visiting a file, you can specify a
375 directory name as FILENAME, to write a file of the same old name
378 If optional third arg CONFIRM is non-nil, asks for confirmation before
379 overwriting an existing file. Interactively, requires confirmation
380 unless you supply a prefix argument."
382 ;; Same interactive spec as write-file, plus format question.
383 (let* ((file (if buffer-file-name
384 (read-file-name "Write file: "
386 (read-file-name "Write file: "
387 (cdr (assq 'default-directory
388 (buffer-local-variables)))
389 nil nil
(buffer-name))))
390 (fmt (format-read (format "Write file `%s' in format: "
391 (file-name-nondirectory file
)))))
392 (list file fmt
(not current-prefix-arg
))))
393 (let ((old-formats buffer-file-format
)
395 (dolist (fmt old-formats
)
396 (let ((aelt (assq fmt format-alist
)))
398 (push fmt preserve-formats
))))
399 (setq buffer-file-format format
)
400 (dolist (fmt preserve-formats
)
401 (unless (memq fmt buffer-file-format
)
402 (setq buffer-file-format
(append buffer-file-format
(list fmt
))))))
403 (write-file filename confirm
))
405 (defun format-find-file (filename format
)
406 "Find the file FILENAME using data format FORMAT.
407 If FORMAT is nil then do not do any format conversion."
409 ;; Same interactive spec as write-file, plus format question.
410 (let* ((file (read-file-name "Find file: "))
411 (fmt (format-read (format "Read file `%s' in format: "
412 (file-name-nondirectory file
)))))
414 (let ((format-alist nil
))
415 (find-file filename
))
417 (format-decode-buffer format
)))
419 (defun format-insert-file (filename format
&optional beg end
)
420 "Insert the contents of file FILENAME using data format FORMAT.
421 If FORMAT is nil then do not do any format conversion.
422 The optional third and fourth arguments BEG and END specify
423 the part (in bytes) of the file to read.
425 The return value is like the value of `insert-file-contents':
426 a list (ABSOLUTE-FILE-NAME SIZE)."
428 ;; Same interactive spec as write-file, plus format question.
429 (let* ((file (read-file-name "Find file: "))
430 (fmt (format-read (format "Read file `%s' in format: "
431 (file-name-nondirectory file
)))))
433 (let (value size old-undo
)
434 ;; Record only one undo entry for the insertion. Inhibit point-motion and
435 ;; modification hooks as with `insert-file-contents'.
436 (let ((inhibit-point-motion-hooks t
)
437 (inhibit-modification-hooks t
))
438 ;; Don't bind `buffer-undo-list' to t here to assert that
439 ;; `insert-file-contents' may record whether the buffer was unmodified
441 (let ((format-alist nil
))
442 (setq value
(insert-file-contents filename nil beg end
))
443 (setq size
(nth 1 value
)))
444 (when (consp buffer-undo-list
)
445 (let ((head (car buffer-undo-list
)))
446 (when (and (consp head
)
447 (equal (car head
) (point))
448 (equal (cdr head
) (+ (point) size
)))
449 ;; Remove first entry from `buffer-undo-list', we shall insert
450 ;; another one below.
451 (setq old-undo
(cdr buffer-undo-list
)))))
453 (let ((buffer-undo-list t
))
454 (setq size
(format-decode format size
)
455 value
(list (car value
) size
)))
456 (unless (eq buffer-undo-list t
)
457 (setq buffer-undo-list
458 (cons (cons (point) (+ (point) size
)) old-undo
)))))
459 (unless inhibit-modification-hooks
460 (run-hook-with-args 'after-change-functions
(point) (+ (point) size
) 0))
463 (defun format-read (&optional prompt
)
464 "Read and return the name of a format.
465 Return value is a list, like `buffer-file-format'; it may be nil.
466 Formats are defined in `format-alist'. Optional arg is the PROMPT to use."
467 (let* ((table (mapcar (lambda (x) (list (symbol-name (car x
))))
469 (ans (completing-read (or prompt
"Format: ") table nil t
)))
470 (if (not (equal "" ans
)) (list (intern ans
)))))
474 ;;; Below are some functions that may be useful in writing encoding and
475 ;;; decoding functions for use in format-alist.
478 (defun format-replace-strings (alist &optional reverse beg end
)
479 "Do multiple replacements on the buffer.
480 ALIST is a list of (FROM . TO) pairs, which should be proper arguments to
481 `search-forward' and `replace-match', respectively.
482 Optional second arg REVERSE, if non-nil, means the pairs are (TO . FROM),
483 so that you can use the same list in both directions if it contains only
485 Optional args BEG and END specify a region of the buffer on which to operate."
488 (or beg
(setq beg
(point-min)))
489 (if end
(narrow-to-region (point-min) end
))
491 (let ((from (if reverse
(cdr (car alist
)) (car (car alist
))))
492 (to (if reverse
(car (car alist
)) (cdr (car alist
)))))
494 (while (search-forward from nil t
)
495 (goto-char (match-beginning 0))
497 (set-text-properties (- (point) (length to
)) (point)
498 (text-properties-at (point)))
499 (delete-region (point) (+ (point) (- (match-end 0)
500 (match-beginning 0)))))
501 (setq alist
(cdr alist
)))))))
503 ;;; Some list-manipulation functions that we need.
505 (defun format-delq-cons (cons list
)
506 "Remove the given CONS from LIST by side effect and return the new LIST.
507 Since CONS could be the first element of LIST, write
508 `\(setq foo \(format-delq-cons element foo))' to be sure of changing
513 (while (not (eq (cdr p
) cons
))
514 (if (null p
) (error "format-delq-cons: not an element"))
516 ;; Now (cdr p) is the cons to delete
517 (setcdr p
(cdr cons
))
520 (defun format-make-relatively-unique (a b
)
521 "Delete common elements of lists A and B, return as pair.
522 Compare using `equal'."
523 (let* ((acopy (copy-sequence a
))
524 (bcopy (copy-sequence b
))
527 (let ((dup (member (car tail
) bcopy
))
529 (if dup
(setq acopy
(format-delq-cons tail acopy
)
530 bcopy
(format-delq-cons dup bcopy
)))
534 (defun format-common-tail (a b
)
535 "Given two lists that have a common tail, return it.
536 Compare with `equal', and return the part of A that is equal to the
537 equivalent part of B. If even the last items of the two are not equal,
539 (let ((la (length a
))
541 ;; Make sure they are the same length
543 (setq a
(nthcdr (- la lb
) a
))
544 (setq b
(nthcdr (- lb la
) b
))))
545 (while (not (equal a b
))
550 (defun format-proper-list-p (list)
551 "Return t if LIST is a proper list.
552 A proper list is a list ending with a nil cdr, not with an atom "
555 (setq list
(cdr list
)))
558 (defun format-reorder (items order
)
559 "Arrange ITEMS to follow partial ORDER.
560 Elements of ITEMS equal to elements of ORDER will be rearranged
561 to follow the ORDER. Unmatched items will go last."
563 (let ((item (member (car order
) items
)))
566 (format-reorder (format-delq-cons item items
)
568 (format-reorder items
(cdr order
))))
571 (put 'face
'format-list-valued t
) ; These text-properties take values
572 (put 'unknown
'format-list-valued t
) ; that are lists, the elements of which
573 ; should be considered separately.
574 ; See format-deannotate-region and
575 ; format-annotate-region.
577 ;; This text property has list values, but they are treated atomically.
579 (put 'display
'format-list-atomic-p t
)
585 (defun format-deannotate-region (from to translations next-fn
)
586 "Translate annotations in the region into text properties.
587 This sets text properties between FROM to TO as directed by the
588 TRANSLATIONS and NEXT-FN arguments.
590 NEXT-FN is a function that searches forward from point for an annotation.
591 It should return a list of 4 elements: \(BEGIN END NAME POSITIVE). BEGIN and
592 END are buffer positions bounding the annotation, NAME is the name searched
593 for in TRANSLATIONS, and POSITIVE should be non-nil if this annotation marks
594 the beginning of a region with some property, or nil if it ends the region.
595 NEXT-FN should return nil if there are no annotations after point.
597 The basic format of the TRANSLATIONS argument is described in the
598 documentation for the `format-annotate-region' function. There are some
599 additional things to keep in mind for decoding, though:
601 When an annotation is found, the TRANSLATIONS list is searched for a
602 text-property name and value that corresponds to that annotation. If the
603 text-property has several annotations associated with it, it will be used only
604 if the other annotations are also in effect at that point. The first match
605 found whose annotations are all present is used.
607 The text property thus determined is set to the value over the region between
608 the opening and closing annotations. However, if the text-property name has a
609 non-nil `format-list-valued' property, then the value will be consed onto the
610 surrounding value of the property, rather than replacing that value.
612 There are some special symbols that can be used in the \"property\" slot of
613 the TRANSLATIONS list: PARAMETER and FUNCTION \(spelled in uppercase).
614 Annotations listed under the pseudo-property PARAMETER are considered to be
615 arguments of the immediately surrounding annotation; the text between the
616 opening and closing parameter annotations is deleted from the buffer but saved
619 The surrounding annotation should be listed under the pseudo-property
620 FUNCTION. Instead of inserting a text-property for this annotation,
621 the function listed in the VALUE slot is called to make whatever
622 changes are appropriate. It can also return a list of the form
623 \(START LOC PROP VALUE) which specifies a property to put on. The
624 function's first two arguments are the START and END locations, and
625 the rest of the arguments are any PARAMETERs found in that region.
627 Any annotations that are found by NEXT-FN but not defined by TRANSLATIONS
628 are saved as values of the `unknown' text-property \(which is list-valued).
629 The TRANSLATIONS list should usually contain an entry of the form
630 \(unknown \(nil format-annotate-value))
631 to write these unknown annotations back into the file."
634 (narrow-to-region (point-min) to
)
636 (let (next open-ans todo loc unknown-ans
)
637 (while (setq next
(funcall next-fn
))
638 (let* ((loc (nth 0 next
))
641 (positive (nth 3 next
))
644 ;; Delete the annotation
645 (delete-region loc end
)
647 ;; Positive annotations are stacked, remembering location
648 (positive (push `(,name
((,loc . nil
))) open-ans
))
649 ;; It is a negative annotation:
650 ;; Close the top annotation & add its text property.
651 ;; If the file's nesting is messed up, the close might not match
652 ;; the top thing on the open-annotations stack.
653 ;; If no matching annotation is open, just ignore the close.
654 ((not (assoc name open-ans
))
655 (message "Extra closing annotation (%s) in file" name
))
656 ;; If one is open, but not on the top of the stack, close
657 ;; the things in between as well. Set `found' when the real
661 (let* ((top (car open-ans
)) ; first on stack: should match.
662 (top-name (car top
)) ; text property name
663 (top-extents (nth 1 top
)) ; property regions
664 (params (cdr (cdr top
))) ; parameters
665 (aalist translations
)
667 (if (equal name top-name
)
669 (message "Improper nesting in file."))
670 ;; Look through property names in TRANSLATIONS
672 (let ((prop (car (car aalist
)))
673 (alist (cdr (car aalist
))))
674 ;; And look through values for each property
676 (let ((value (car (car alist
)))
677 (ans (cdr (car alist
))))
678 (if (member top-name ans
)
679 ;; This annotation is listed, but still have to
680 ;; check if multiple annotations are satisfied
681 (if (member nil
(mapcar (lambda (r)
684 nil
; multiple ans not satisfied
685 ;; If there are multiple annotations going
686 ;; into one text property, split up the other
687 ;; annotations so they apply individually to
688 ;; the other regions.
689 (setcdr (car top-extents
) loc
)
690 (let ((to-split ans
) this-one extents
)
693 (assoc (car to-split
) open-ans
)
694 extents
(nth 1 this-one
))
695 (if (not (eq this-one top
))
696 (setcar (cdr this-one
)
697 (format-subtract-regions
698 extents top-extents
)))
699 (setq to-split
(cdr to-split
))))
700 ;; Set loop variables to nil so loop
702 (setq alist nil aalist nil matched t
703 ;; pop annotation off stack.
704 open-ans
(cdr open-ans
))
705 (let ((extents top-extents
)
706 (start (car (car top-extents
)))
707 (loc (cdr (car top-extents
))))
710 ;; Check for pseudo-properties
711 ((eq prop
'PARAMETER
)
712 ;; A parameter of the top open ann:
713 ;; delete text and use as arg.
715 ;; (If nothing open, discard).
718 (append (car open-ans
)
723 (delete-region start loc
))
725 ;; Not a property, but a function.
727 (apply value start loc params
)))
728 (if rtn
(push rtn todo
))))
730 ;; Normal property/value pair
732 (cons (list start loc prop value
)
734 (setq extents
(cdr extents
)
735 start
(car (car extents
))
736 loc
(cdr (car extents
))))))))
737 (setq alist
(cdr alist
))))
738 (setq aalist
(cdr aalist
)))
740 ;; Didn't find any match for the annotation:
741 ;; Store as value of text-property `unknown'.
742 (let ((extents top-extents
)
743 (start (car (car top-extents
)))
744 (loc (or (cdr (car top-extents
)) loc
)))
746 (setq open-ans
(cdr open-ans
)
747 todo
(cons (list start loc
'unknown top-name
)
749 unknown-ans
(cons name unknown-ans
)
750 extents
(cdr extents
)
751 start
(car (car extents
))
752 loc
(cdr (car extents
))))))))))))
754 ;; Once entire file has been scanned, add the properties.
756 (let* ((item (car todo
))
762 (if (numberp val
) ; add to ambient value if numeric
763 (format-property-increment-region from to prop val
0)
766 (cond ((get prop
'format-list-valued
) ; value gets consed onto
767 ; list-valued properties
768 (let ((prev (get-text-property from prop
)))
769 (cons val
(if (listp prev
) prev
(list prev
)))))
770 (t val
))))) ; normally, just set to val.
771 (setq todo
(cdr todo
)))
774 (message "Unknown annotations: %s" unknown-ans
))))))
776 (defun format-subtract-regions (minu subtra
)
777 "Remove from the regions in MINUEND the regions in SUBTRAHEND.
778 A region is a dotted pair (FROM . TO). Both parameters are lists of
779 regions. Each list must contain nonoverlapping, noncontiguous
780 regions, in descending order. The result is also nonoverlapping,
781 noncontiguous, and in descending order. The first element of MINUEND
782 can have a cdr of nil, indicating that the end of that region is not
785 \(fn MINUEND SUBTRAHEND)"
786 (let* ((minuend (copy-alist minu
))
787 (subtrahend (copy-alist subtra
))
791 (while (and minuend subtrahend
)
793 ;; The minuend starts after the subtrahend ends; keep it.
796 (setq minuend
(cdr minuend
)
798 ;; The minuend extends beyond the end of the subtrahend. Chop it off.
799 ((or (null (cdr m
)) (> (cdr m
) (cdr s
)))
800 (push (cons (1+ (cdr s
)) (cdr m
)) results
)
802 ;; The subtrahend starts after the minuend ends; throw it away.
804 (setq subtrahend
(cdr subtrahend
) s
(car subtrahend
)))
805 ;; The subtrahend extends beyond the end of the minuend. Chop it off.
806 (t ;(<= (cdr m) (cdr s)))
807 (if (>= (car m
) (car s
))
808 (setq minuend
(cdr minuend
) m
(car minuend
))
809 (setcdr m
(1- (car s
)))
810 (setq subtrahend
(cdr subtrahend
) s
(car subtrahend
))))))
811 (nconc (nreverse results
) minuend
)))
813 ;; This should probably go somewhere other than format.el. Then again,
814 ;; indent.el has alter-text-property. NOTE: We can also use
815 ;; next-single-property-change instead of text-property-not-all, but then
816 ;; we have to see if we passed TO.
817 (defun format-property-increment-region (from to prop delta default
)
818 "In the region from FROM to TO increment property PROP by amount DELTA.
819 DELTA may be negative. If property PROP is nil anywhere
820 in the region, it is treated as though it were DEFAULT."
821 (let ((cur from
) val newval next
)
823 (setq val
(get-text-property cur prop
)
824 newval
(+ (or val default
) delta
)
825 next
(text-property-not-all cur to prop val
))
826 (put-text-property cur
(or next to
) prop newval
)
833 (defun format-insert-annotations (list &optional offset
)
834 "Apply list of annotations to buffer as `write-region' would.
835 Insert each element of the given LIST of buffer annotations at its
836 appropriate place. Use second arg OFFSET if the annotations' locations are
837 not relative to the beginning of the buffer: annotations will be inserted
838 at their location-OFFSET+1 \(ie, the offset is treated as the position of
839 the first character in the buffer)."
842 (setq offset
(1- offset
)))
843 (let ((l (reverse list
)))
845 (goto-char (- (car (car l
)) offset
))
846 (insert (cdr (car l
)))
849 (defun format-annotate-value (old new
)
850 "Return OLD and NEW as a \(CLOSE . OPEN) annotation pair.
851 Useful as a default function for TRANSLATIONS alist when the value of the text
852 property is the name of the annotation that you want to use, as it is for the
853 `unknown' text property."
854 (cons (if old
(list old
))
855 (if new
(list new
))))
857 (defun format-annotate-region (from to translations format-fn ignore
)
858 "Generate annotations for text properties in the region.
859 Search for changes between FROM and TO, and describe them with a list of
860 annotations as defined by alist TRANSLATIONS and FORMAT-FN. IGNORE lists text
861 properties not to consider; any text properties that are neither ignored nor
862 listed in TRANSLATIONS are warned about.
863 If you actually want to modify the region, give the return value of this
864 function to `format-insert-annotations'.
866 Format of the TRANSLATIONS argument:
868 Each element is a list whose car is a PROPERTY, and the following
869 elements have the form (VALUE ANNOTATIONS...).
870 Whenever the property takes on the value VALUE, the annotations
871 \(as formatted by FORMAT-FN) are inserted into the file.
872 When the property stops having that value, the matching negated annotation
873 will be inserted \(it may actually be closed earlier and reopened, if
874 necessary, to keep proper nesting).
876 If VALUE is a list, then each element of the list is dealt with
879 If a VALUE is numeric, then it is assumed that there is a single annotation
880 and each occurrence of it increments the value of the property by that number.
881 Thus, given the entry \(left-margin \(4 \"indent\")), if the left margin
882 changes from 4 to 12, two <indent> annotations will be generated.
884 If the VALUE is nil, then instead of annotations, a function should be
885 specified. This function is used as a default: it is called for all
886 transitions not explicitly listed in the table. The function is called with
887 two arguments, the OLD and NEW values of the property. It should return
888 a cons cell (CLOSE . OPEN) as `format-annotate-single-property-change' does.
890 The same TRANSLATIONS structure can be used in reverse for reading files."
891 (let ((all-ans nil
) ; All annotations - becomes return value
892 (open-ans nil
) ; Annotations not yet closed
893 (loc nil
) ; Current location
894 (not-found nil
)) ; Properties that couldn't be saved
895 (while (or (null loc
)
896 (and (setq loc
(next-property-change loc nil to
))
898 (or loc
(setq loc from
))
899 (let* ((ans (format-annotate-location loc
(= loc from
) ignore translations
))
900 (neg-ans (format-reorder (aref ans
0) open-ans
))
901 (pos-ans (aref ans
1))
902 (ignored (aref ans
2)))
903 (setq not-found
(append ignored not-found
)
904 ignore
(append ignored ignore
))
905 ;; First do the negative (closing) annotations
907 ;; Check if it's missing. This can happen (eg, a numeric property
908 ;; going negative can generate closing annotations before there are
909 ;; any open). Warn user & ignore.
910 (if (not (member (car neg-ans
) open-ans
))
911 (message "Can't close %s: not open." (car neg-ans
))
912 (while (not (equal (car neg-ans
) (car open-ans
)))
913 ;; To close anno. N, need to first close ans 1 to N-1,
914 ;; remembering to re-open them later.
915 (push (car open-ans
) pos-ans
)
917 (cons (cons loc
(funcall format-fn
(car open-ans
) nil
))
919 (setq open-ans
(cdr open-ans
)))
920 ;; Now remove the one we're really interested in from open list.
921 (setq open-ans
(cdr open-ans
))
922 ;; And put the closing annotation here.
923 (push (cons loc
(funcall format-fn
(car neg-ans
) nil
))
925 (setq neg-ans
(cdr neg-ans
)))
926 ;; Now deal with positive (opening) annotations
929 (push (car pos-ans
) open-ans
)
930 (push (cons loc
(funcall format-fn
(car pos-ans
) t
))
932 (setq pos-ans
(cdr pos-ans
))))))
934 ;; Close any annotations still open
937 (cons (cons to
(funcall format-fn
(car open-ans
) nil
))
939 (setq open-ans
(cdr open-ans
)))
941 (message "These text properties could not be saved:\n %s"
945 ;;; Internal functions for format-annotate-region.
947 (defun format-annotate-location (loc all ignore translations
)
948 "Return annotation(s) needed at location LOC.
949 This includes any properties that change between LOC - 1 and LOC.
950 If ALL is true, don't look at previous location, but generate annotations for
951 all non-nil properties.
952 Third argument IGNORE is a list of text-properties not to consider.
953 Use the TRANSLATIONS alist (see `format-annotate-region' for doc).
955 Return value is a vector of 3 elements:
956 1. List of annotations to close
957 2. List of annotations to open.
958 3. List of properties that were ignored or couldn't be annotated.
960 The annotations in lists 1 and 2 need not be strings.
961 They can be whatever the FORMAT-FN in `format-annotate-region'
962 can handle. If that is `enriched-make-annotation', they can be
963 either strings, or lists of the form (PARAMETER VALUE)."
964 (let* ((prev-loc (1- loc
))
965 (before-plist (if all nil
(text-properties-at prev-loc
)))
966 (after-plist (text-properties-at loc
))
967 p negatives positives prop props not-found
)
968 ;; make list of all property names involved
969 (setq p before-plist
)
971 (if (not (memq (car p
) props
))
972 (push (car p
) props
))
973 (setq p
(cdr (cdr p
))))
976 (if (not (memq (car p
) props
))
977 (push (car p
) props
))
978 (setq p
(cdr (cdr p
))))
981 (setq prop
(pop props
))
982 (if (memq prop ignore
)
983 nil
; If it's been ignored before, ignore it now.
984 (let ((before (if all nil
(car (cdr (memq prop before-plist
)))))
985 (after (car (cdr (memq prop after-plist
)))))
986 (if (equal before after
)
987 nil
; no change; ignore
988 (let ((result (format-annotate-single-property-change
989 prop before after translations
)))
991 (push prop not-found
)
992 (setq negatives
(nconc negatives
(car result
))
993 positives
(nconc positives
(cdr result
)))))))))
994 (vector negatives positives not-found
)))
996 (defun format-annotate-single-property-change (prop old new translations
)
997 "Return annotations for property PROP changing from OLD to NEW.
998 These are searched for in the translations alist TRANSLATIONS
999 (see `format-annotate-region' for the format).
1000 If NEW does not appear in the list, but there is a default function,
1001 then call that function.
1002 Return a cons of the form (CLOSE . OPEN)
1003 where CLOSE is a list of annotations to close
1004 and OPEN is a list of annotations to open.
1006 The annotations in CLOSE and OPEN need not be strings.
1007 They can be whatever the FORMAT-FN in `format-annotate-region'
1008 can handle. If that is `enriched-make-annotation', they can be
1009 either strings, or lists of the form (PARAMETER VALUE)."
1011 (let ((prop-alist (cdr (assoc prop translations
)))
1013 (if (not prop-alist
)
1015 ;; If either old or new is a list, have to treat both that way.
1016 (if (and (or (listp old
) (listp new
))
1017 (not (get prop
'format-list-atomic-p
)))
1018 (if (or (not (format-proper-list-p old
))
1019 (not (format-proper-list-p new
)))
1020 (format-annotate-atomic-property-change prop-alist old new
)
1021 (let* ((old (if (listp old
) old
(list old
)))
1022 (new (if (listp new
) new
(list new
)))
1023 (tail (format-common-tail old new
))
1027 (append (car (format-annotate-atomic-property-change
1028 prop-alist
(car old
) nil
))
1033 (append (cdr (format-annotate-atomic-property-change
1034 prop-alist nil
(car new
)))
1037 (format-make-relatively-unique close open
)))
1038 (format-annotate-atomic-property-change prop-alist old new
)))))
1040 (defun format-annotate-atomic-property-change (prop-alist old new
)
1041 "Internal function to annotate a single property change.
1042 PROP-ALIST is the relevant element of a TRANSLATIONS list.
1043 OLD and NEW are the values."
1045 ;; If old and new values are numbers,
1046 ;; look for a number in PROP-ALIST.
1047 (if (and (or (null old
) (numberp old
))
1048 (or (null new
) (numberp new
)))
1050 (setq num-ann prop-alist
)
1051 (while (and num-ann
(not (numberp (car (car num-ann
)))))
1052 (setq num-ann
(cdr num-ann
)))))
1054 ;; Numerical annotation - use difference
1056 ;; If property is numeric, nil means 0
1057 (cond ((and (numberp old
) (null new
))
1059 ((and (numberp new
) (null old
))
1062 (let* ((entry (car num-ann
))
1063 (increment (car entry
))
1064 (n (ceiling (/ (float (- new old
)) (float increment
))))
1065 (anno (car (cdr entry
))))
1067 (cons nil
(make-list n anno
))
1068 (cons (make-list (- n
) anno
) nil
))))
1070 ;; Standard annotation
1071 (let ((close (and old
(cdr (assoc old prop-alist
))))
1072 (open (and new
(cdr (assoc new prop-alist
)))))
1074 (format-make-relatively-unique close open
)
1075 ;; Call "Default" function, if any
1076 (let ((default (assq nil prop-alist
)))
1078 (funcall (car (cdr default
)) old new
))))))))
1082 ;; arch-tag: c387e9c7-a93d-47bf-89bc-8ca67e96755a
1083 ;;; format.el ends here