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