| blob | ad109a41c95b04df68da6154ceb8eca58adecebc |
1 ;;; format.el --- read and save files in multiple formats
3 ;; Copyright (c) 1994, 1995, 1997 Free Software Foundation
5 ;; Author: Boris Goldowsky <boris@gnu.ai.mit.edu>
7 ;; This file is part of GNU Emacs.
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.
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.
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.
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.
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.
62 ;;; Code:
69 enriched-decode enriched-encode t enriched-mode)
71 ;; Plain only exists so that there is an obvious neutral choice in
72 ;; the completion list.
73 nil nil nil nil nil)
85 iso-tex2iso iso-iso2tex t nil)
88 iso-gtex2iso iso-iso2gtex t nil)
103 iso-german iso-cvt-read-only t 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 NAME is a symbol, which is stored in `buffer-file-format'.
110 DOC-STR should be a single line providing more information about the
111 format. It is currently unused, but in the future will be shown to
112 the user if they ask for more information.
113 REGEXP is a regular expression to match against the beginning of the file;
114 it should match only files in that format.
115 FROM-FN is called to decode files in that format; it gets two args, BEGIN
116 and END, and can make any modifications it likes, returning the new
117 end. It must make sure that the beginning of the file no longer
118 matches REGEXP, or else it will get called again.
119 TO-FN is called to encode a region into that format; it is passed three
120 arguments: BEGIN, END, and BUFFER. BUFFER is the original buffer that
121 the data being written came from, which the function could use, for
122 example, to find the values of local variables. TO-FN should either
123 return a list of annotations like `write-region-annotate-functions',
124 or modify the region and return the new end.
125 MODIFY, if non-nil, means the TO-FN wants to modify the region. If nil,
126 TO-FN will not make any changes but will instead return a list of
127 annotations.
130 ;;; Basic Functions (called from Lisp)
133 "Translate using function or shell script METHOD the text from FROM to TO.
134 If METHOD is a string, it is a shell command;
135 otherwise, it should be a Lisp function.
136 BUFFER should be the buffer that the output originally came from."
145 "Decode using function or shell script METHOD the text from FROM to TO.
146 If METHOD is a string, it is a shell command;
147 otherwise, it should be a Lisp function."
155 "Returns annotations for writing region as FORMAT.
156 FORMAT is a symbol naming one of the formats defined in `format-alist',
157 it must be a single symbol, not a list like `buffer-file-format'.
158 FROM and TO delimit the region to be operated on in the current buffer.
159 ORIG-BUF is the original buffer that the data came from.
160 This function works like a function on `write-region-annotate-functions':
161 it either returns a list of annotations, or returns with a different buffer
162 current, which contains the modified text to write.
164 For most purposes, consider using `format-encode-region' instead."
165 ;; This function is called by write-region (actually build-annotations)
166 ;; for each element of buffer-file-format.
172 ;; To-function wants to modify region. Copy to safe place.
178 nil)
179 ;; Otherwise just call function, it will return annotations.
183 ;; This function is called by insert-file-contents whenever a file is read.
184 "Decode text from any known FORMAT.
185 FORMAT is a symbol appearing in `format-alist' or a list of such symbols,
186 or nil, in which case this function tries to guess the format of the data by
187 matching against the regular expressions in `format-alist'. After a match is
188 found and the region decoded, the alist is searched again from the beginning
189 for another match.
191 Second arg LENGTH is the number of characters following point to operate on.
192 If optional third arg VISIT-FLAG is true, set `buffer-file-format'
193 to the list of formats used, and call any mode functions defined for those
194 formats.
196 Returns the new length of the decoded region.
198 For most purposes, consider using `format-decode-region' instead."
203 ;; Figure out which format it is in, remember list in `format'.
213 ;; Decode it
216 ;; Call visit function if required
218 ;; Safeguard against either of the functions changing pt.
220 ;; Rewind list to look for another format
223 ;; Deal with given format(s)
229 ;; Decode:
232 ;; Call visit function if required
238 ;; Return new length of region
241 ;;;
242 ;;; Interactive functions & entry points
243 ;;;
246 "Translate the buffer from some FORMAT.
247 If the format is not specified, this function attempts to guess.
248 `buffer-file-format' is set to the format used, and any mode-functions
249 for the format are called."
257 "Decode the region from some format.
258 Arg FORMAT is optional; if omitted the format will be determined by looking
259 for identifying regular expressions at the beginning of the region."
268 "Translate the buffer into FORMAT.
269 FORMAT defaults to `buffer-file-format'. It is a symbol naming one of the
270 formats defined in `format-alist', or a list of such symbols."
273 buffer-file-format))))
277 "Translate the region into some FORMAT.
278 FORMAT defaults to `buffer-file-format', it is a symbol naming
279 one of the formats defined in `format-alist', or a list of such symbols."
283 buffer-file-format))))
294 result)
304 "Write current buffer into a FILE using some FORMAT.
305 Makes buffer visit that file and sets the format as the default for future
306 saves. If the buffer is already visiting a file, you can specify a directory
307 name as FILE, to write a file of the same old name in that directory."
309 ;; Same interactive spec as write-file, plus format question.
312 nil nil nil nil)
324 "Find the file FILE using data format FORMAT.
325 If FORMAT is nil then do not do any format conversion."
327 ;; Same interactive spec as write-file, plus format question.
338 "Insert the contents of file FILE using data format FORMAT.
339 If FORMAT is nil then do not do any format conversion.
340 The optional third and fourth arguments BEG and END specify
341 the part of the file to read.
343 The return value is like the value of `insert-file-contents':
344 a list (ABSOLUTE-FILE-NAME . SIZE)."
346 ;; Same interactive spec as write-file, plus format question.
358 value))
361 "Read and return the name of a format.
362 Return value is a list, like `buffer-file-format'; it may be nil.
363 Formats are defined in `format-alist'. Optional arg is the PROMPT to use."
365 format-alist))
370 ;;;
371 ;;; Below are some functions that may be useful in writing encoding and
372 ;;; decoding functions for use in format-alist.
373 ;;;
376 "Do multiple replacements on the buffer.
377 ALIST is a list of (from . to) pairs, which should be proper arguments to
378 `search-forward' and `replace-match' respectively.
379 Optional 2nd arg REVERSE, if non-nil, means the pairs are (to . from), so that
380 you can use the same list in both directions if it contains only literal
381 strings.
382 Optional args BEGIN and END specify a region of the buffer to operate on."
400 ;;; Some list-manipulation functions that we need.
403 "Remove the given CONS from LIST by side effect,
404 and return the new LIST. Since CONS could be the first element
405 of LIST, write `\(setq foo \(format-delq-cons element foo))' to be sure of
406 changing the value of `foo'."
413 ;; Now (cdr p) is the cons to delete
415 list)))
418 "Delete common elements of lists A and B, return as pair.
419 Compares using `equal'."
432 "Given two lists that have a common tail, return it.
433 Compares with `equal', and returns the part of A that is equal to the
434 equivalent part of B. If even the last items of the two are not equal,
435 returns nil."
438 ;; Make sure they are the same length
445 a)
448 "Arrange ITEMS to following partial ORDER.
449 Elements of ITEMS equal to elements of ORDER will be rearranged to follow the
450 ORDER. Unmatched items will go last."
458 items))
462 ; should be considered separately.
463 ; See format-deannotate-region and
464 ; format-annotate-region.
466 ;;;
467 ;;; Decoding
468 ;;;
471 "Translate annotations in the region into text properties.
472 This sets text properties between FROM to TO as directed by the
473 TRANSLATIONS and NEXT-FN arguments.
475 NEXT-FN is a function that searches forward from point for an annotation.
476 It should return a list of 4 elements: \(BEGIN END NAME POSITIVE). BEGIN and
477 END are buffer positions bounding the annotation, NAME is the name searched
478 for in TRANSLATIONS, and POSITIVE should be non-nil if this annotation marks
479 the beginning of a region with some property, or nil if it ends the region.
480 NEXT-FN should return nil if there are no annotations after point.
482 The basic format of the TRANSLATIONS argument is described in the
483 documentation for the `format-annotate-region' function. There are some
484 additional things to keep in mind for decoding, though:
486 When an annotation is found, the TRANSLATIONS list is searched for a
487 text-property name and value that corresponds to that annotation. If the
488 text-property has several annotations associated with it, it will be used only
489 if the other annotations are also in effect at that point. The first match
490 found whose annotations are all present is used.
492 The text property thus determined is set to the value over the region between
493 the opening and closing annotations. However, if the text-property name has a
494 non-nil `format-list-valued' property, then the value will be consed onto the
495 surrounding value of the property, rather than replacing that value.
498 the TRANSLATIONS list: PARAMETER and FUNCTION \(spelled in uppercase).
499 Annotations listed under the pseudo-property PARAMETER are considered to be
500 arguments of the immediately surrounding annotation; the text between the
501 opening and closing parameter annotations is deleted from the buffer but saved
502 as a string. The surrounding annotation should be listed under the
503 pseudo-property FUNCTION. Instead of inserting a text-property for this
504 annotation, the function listed in the VALUE slot is called to make whatever
505 changes are appropriate. The function's first two arguments are the START and
506 END locations, and the rest of the arguments are any PARAMETERs found in that
507 region.
509 Any annotations that are found by NEXT-FN but not defined by TRANSLATIONS
510 are saved as values of the `unknown' text-property \(which is list-valued).
511 The TRANSLATIONS list should usually contain an entry of the form
512 \(unknown \(nil format-annotate-value))
513 to write these unknown annotations back into the file."
526 ;; Delete the annotation
529 ;; Positive annotations are stacked, remembering location
531 ;; It is a negative annotation:
532 ;; Close the top annotation & add its text property.
533 ;; If the file's nesting is messed up, the close might not match
534 ;; the top thing on the open-annotations stack.
535 ;; If no matching annotation is open, just ignore the close.
538 ;; If one is open, but not on the top of the stack, close
539 ;; the things in between as well. Set `found' when the real
540 ;; one is closed.
551 ;; Look through property names in TRANSLATIONS
555 ;; And look through values for each property
560 ;; This annotation is listed, but still have to
561 ;; check if multiple annotations are satisfied
565 ans))
566 nil ; multiple ans not satisfied
567 ;; Yes, all set.
568 ;; If there are multiple annotations going
569 ;; into one text property, adjust the
570 ;; begin points of the other annotations
571 ;; so that we don't get double marking.
573 this-one)
581 ;; Set loop variables to nil so loop
582 ;; will exit.
584 ;; pop annotation off stack.
587 ;; Check for pseudo-properties
589 ;; This is a parameter of the top open ann:
590 ;; delete text and use as arg.
592 ;; (If nothing open, discard).
597 start loc)))
601 ;; Not a property, but a function to call.
605 ;; Normal property/value pair
608 todo)))))))
612 nil
613 ;; Didn't find any match for the annotation:
614 ;; Store as value of text-property `unknown'.
617 todo))
620 ;; Once entire file has been scanned, add the properties.
629 from to prop
633 ; list-valued properties
642 ;;;
643 ;;; Encoding
644 ;;;
647 "Apply list of annotations to buffer as `write-region' would.
648 Inserts each element of the given LIST of buffer annotations at its
649 appropriate place. Use second arg OFFSET if the annotations' locations are
650 not relative to the beginning of the buffer: annotations will be inserted
651 at their location-OFFSET+1 \(ie, the offset is treated as the character number
652 of the first character in the buffer)."
663 "Return OLD and NEW as a \(close . open) annotation pair.
664 Useful as a default function for TRANSLATIONS alist when the value of the text
665 property is the name of the annotation that you want to use, as it is for the
666 `unknown' text property."
671 "Generate annotations for text properties in the region.
672 Searches for changes between FROM and TO, and describes them with a list of
673 annotations as defined by alist TRANSLATIONS and FORMAT-FN. IGNORE lists text
674 properties not to consider; any text properties that are neither ignored nor
675 listed in TRANSLATIONS are warned about.
676 If you actually want to modify the region, give the return value of this
677 function to `format-insert-annotations'.
679 Format of the TRANSLATIONS argument:
681 Each element is a list whose car is a PROPERTY, and the following
682 elements are VALUES of that property followed by the names of zero or more
683 ANNOTATIONS. Whenever the property takes on that value, the annotations
684 \(as formatted by FORMAT-FN) are inserted into the file.
685 When the property stops having that value, the matching negated annotation
686 will be inserted \(it may actually be closed earlier and reopened, if
687 necessary, to keep proper nesting).
689 If the property's value is a list, then each element of the list is dealt with
690 separately.
692 If a VALUE is numeric, then it is assumed that there is a single annotation
693 and each occurrence of it increments the value of the property by that number.
695 changes from 4 to 12, two <indent> annotations will be generated.
697 If the VALUE is nil, then instead of annotations, a function should be
698 specified. This function is used as a default: it is called for all
699 transitions not explicitly listed in the table. The function is called with
700 two arguments, the OLD and NEW values of the property. It should return
701 lists of annotations like `format-annotate-location' does.
703 The same structure can be used in reverse for reading files."
718 ;; First do the negative (closing) annotations
720 ;; Check if it's missing. This can happen (eg, a numeric property
721 ;; going negative can generate closing annotations before there are
722 ;; any open). Warn user & ignore.
726 ;; To close anno. N, need to first close ans 1 to N-1,
727 ;; remembering to re-open them later.
731 all-ans))
733 ;; Now remove the one we're really interested in from open list.
735 ;; And put the closing annotation here.
738 all-ans)))
740 ;; Now deal with positive (opening) annotations
746 all-ans))
749 ;; Close any annotations still open
753 all-ans))
757 not-found))
760 ;;; Internal functions for format-annotate-region.
763 "Return annotation(s) needed at LOCATION.
764 This includes any properties that change between LOC-1 and LOC.
765 If ALL is true, don't look at previous location, but generate annotations for
766 all non-nil properties.
767 Third argument IGNORE is a list of text-properties not to consider.
769 Return value is a vector of 3 elements:
770 1. List of names of the annotations to close
771 2. List of the names of annotations to open.
772 3. List of properties that were ignored or couldn't be annotated."
776 p negatives positives prop props not-found)
777 ;; make list of all property names involved
793 nil ; If it's been ignored before, ignore it now.
797 nil ; no change; ignore
799 prop before after trans)))
807 "Return annotations for PROPERTY changing from OLD to NEW.
808 These are searched for in the TRANSLATIONS alist.
809 If NEW does not appear in the list, but there is a default function, then that
810 function is called.
811 Annotations to open and to close are returned as a dotted pair."
813 default)
815 nil
816 ;; If property is numeric, nil means 0
821 ;; If either old or new is a list, have to treat both that way.
826 close open)
831 close)
837 open)
843 "Internal function annotate a single property change.
844 PROP-ALIST is the relevant segment of a TRANSLATIONS list.
845 OLD and NEW are the values."
847 ;; Numerical annotation - use difference
861 ;; Standard annotation
866 ;; Call "Default" function, if any
872 ;; format.el ends here