| blob | 872f5894ca9ea0305461ba778a5d8a3ada2b0d8a |
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:
72 enriched-decode enriched-encode t enriched-mode)
74 ;; Plain only exists so that there is an obvious neutral choice in
75 ;; the completion list.
76 nil nil nil nil nil)
88 iso-tex2iso iso-iso2tex t nil)
91 iso-gtex2iso iso-iso2gtex t nil)
106 iso-german iso-cvt-read-only t nil)
109 iso-spanish iso-cvt-read-onlyt nil))
110 "List of information about understood file formats.
111 Elements are of the form \(NAME DOC-STR REGEXP FROM-FN TO-FN MODIFY MODE-FN).
112 NAME is a symbol, which is stored in `buffer-file-format'.
113 DOC-STR should be a single line providing more information about the
114 format. It is currently unused, but in the future will be shown to
115 the user if they ask for more information.
116 REGEXP is a regular expression to match against the beginning of the file;
117 it should match only files in that format.
118 FROM-FN is called to decode files in that format; it gets two args, BEGIN
119 and END, and can make any modifications it likes, returning the new
120 end. It must make sure that the beginning of the file no longer
121 matches REGEXP, or else it will get called again.
122 TO-FN is called to encode a region into that format; it is passed three
123 arguments: BEGIN, END, and BUFFER. BUFFER is the original buffer that
124 the data being written came from, which the function could use, for
125 example, to find the values of local variables. TO-FN should either
126 return a list of annotations like `write-region-annotate-functions',
127 or modify the region and return the new end.
128 MODIFY, if non-nil, means the TO-FN wants to modify the region. If nil,
129 TO-FN will not make any changes but will instead return a list of
130 annotations.
133 ;;; Basic Functions (called from Lisp)
136 "Translate using function or shell script METHOD the text from FROM to TO.
137 If METHOD is a string, it is a shell command;
138 otherwise, it should be a Lisp function.
139 BUFFER should be the buffer that the output originally came from."
148 "Decode using function or shell script METHOD the text from FROM to TO.
149 If METHOD is a string, it is a shell command;
150 otherwise, it should be a Lisp function."
158 "Returns annotations for writing region as FORMAT.
159 FORMAT is a symbol naming one of the formats defined in `format-alist',
160 it must be a single symbol, not a list like `buffer-file-format'.
161 FROM and TO delimit the region to be operated on in the current buffer.
162 ORIG-BUF is the original buffer that the data came from.
163 This function works like a function on `write-region-annotate-functions':
164 it either returns a list of annotations, or returns with a different buffer
165 current, which contains the modified text to write.
167 For most purposes, consider using `format-encode-region' instead."
168 ;; This function is called by write-region (actually build-annotations)
169 ;; for each element of buffer-file-format.
175 ;; To-function wants to modify region. Copy to safe place.
181 nil)
182 ;; Otherwise just call function, it will return annotations.
186 ;; This function is called by insert-file-contents whenever a file is read.
187 "Decode text from any known FORMAT.
188 FORMAT is a symbol appearing in `format-alist' or a list of such symbols,
189 or nil, in which case this function tries to guess the format of the data by
190 matching against the regular expressions in `format-alist'. After a match is
191 found and the region decoded, the alist is searched again from the beginning
192 for another match.
194 Second arg LENGTH is the number of characters following point to operate on.
195 If optional third arg VISIT-FLAG is true, set `buffer-file-format'
196 to the list of formats used, and call any mode functions defined for those
197 formats.
199 Returns the new length of the decoded region.
201 For most purposes, consider using `format-decode-region' instead."
206 ;; Figure out which format it is in, remember list in `format'.
216 ;; Decode it
219 ;; Call visit function if required
221 ;; Safeguard against either of the functions changing pt.
223 ;; Rewind list to look for another format
226 ;; Deal with given format(s)
232 ;; Decode:
235 ;; Call visit function if required
241 ;; Return new length of region
244 ;;;
245 ;;; Interactive functions & entry points
246 ;;;
249 "Translate the buffer from some FORMAT.
250 If the format is not specified, this function attempts to guess.
251 `buffer-file-format' is set to the format used, and any mode-functions
252 for the format are called."
260 "Decode the region from some format.
261 Arg FORMAT is optional; if omitted the format will be determined by looking
262 for identifying regular expressions at the beginning of the region."
271 "Translate the buffer into FORMAT.
272 FORMAT defaults to `buffer-file-format'. It is a symbol naming one of the
273 formats defined in `format-alist', or a list of such symbols."
276 buffer-file-format))))
280 "Translate the region into some FORMAT.
281 FORMAT defaults to `buffer-file-format', it is a symbol naming
282 one of the formats defined in `format-alist', or a list of such symbols."
286 buffer-file-format))))
297 result)
307 "Write current buffer into a FILE using some FORMAT.
308 Makes buffer visit that file and sets the format as the default for future
309 saves. If the buffer is already visiting a file, you can specify a directory
310 name as FILE, to write a file of the same old name in that directory."
312 ;; Same interactive spec as write-file, plus format question.
315 nil nil nil nil)
327 "Find the file FILE using data format FORMAT.
328 If FORMAT is nil then do not do any format conversion."
330 ;; Same interactive spec as write-file, plus format question.
341 "Insert the contents of file FILE using data format FORMAT.
342 If FORMAT is nil then do not do any format conversion.
343 The optional third and fourth arguments BEG and END specify
344 the part of the file to read.
346 The return value is like the value of `insert-file-contents':
347 a list (ABSOLUTE-FILE-NAME . SIZE)."
349 ;; Same interactive spec as write-file, plus format question.
361 value))
364 "Read and return the name of a format.
365 Return value is a list, like `buffer-file-format'; it may be nil.
366 Formats are defined in `format-alist'. Optional arg is the PROMPT to use."
368 format-alist))
373 ;;;
374 ;;; Below are some functions that may be useful in writing encoding and
375 ;;; decoding functions for use in format-alist.
376 ;;;
379 "Do multiple replacements on the buffer.
380 ALIST is a list of (from . to) pairs, which should be proper arguments to
381 `search-forward' and `replace-match' respectively.
382 Optional 2nd arg REVERSE, if non-nil, means the pairs are (to . from), so that
383 you can use the same list in both directions if it contains only literal
384 strings.
385 Optional args BEGIN and END specify a region of the buffer to operate on."
403 ;;; Some list-manipulation functions that we need.
406 "Remove the given CONS from LIST by side effect,
407 and return the new LIST. Since CONS could be the first element
408 of LIST, write `\(setq foo \(format-delq-cons element foo))' to be sure of
409 changing the value of `foo'."
416 ;; Now (cdr p) is the cons to delete
418 list)))
421 "Delete common elements of lists A and B, return as pair.
422 Compares using `equal'."
435 "Given two lists that have a common tail, return it.
436 Compares with `equal', and returns the part of A that is equal to the
437 equivalent part of B. If even the last items of the two are not equal,
438 returns nil."
441 ;; Make sure they are the same length
448 a)
451 "Arrange ITEMS to following partial ORDER.
452 Elements of ITEMS equal to elements of ORDER will be rearranged to follow the
453 ORDER. Unmatched items will go last."
461 items))
465 ; should be considered separately.
466 ; See format-deannotate-region and
467 ; format-annotate-region.
469 ;;;
470 ;;; Decoding
471 ;;;
474 "Translate annotations in the region into text properties.
475 This sets text properties between FROM to TO as directed by the
476 TRANSLATIONS and NEXT-FN arguments.
478 NEXT-FN is a function that searches forward from point for an annotation.
479 It should return a list of 4 elements: \(BEGIN END NAME POSITIVE). BEGIN and
480 END are buffer positions bounding the annotation, NAME is the name searched
481 for in TRANSLATIONS, and POSITIVE should be non-nil if this annotation marks
482 the beginning of a region with some property, or nil if it ends the region.
483 NEXT-FN should return nil if there are no annotations after point.
485 The basic format of the TRANSLATIONS argument is described in the
486 documentation for the `format-annotate-region' function. There are some
487 additional things to keep in mind for decoding, though:
489 When an annotation is found, the TRANSLATIONS list is searched for a
490 text-property name and value that corresponds to that annotation. If the
491 text-property has several annotations associated with it, it will be used only
492 if the other annotations are also in effect at that point. The first match
493 found whose annotations are all present is used.
495 The text property thus determined is set to the value over the region between
496 the opening and closing annotations. However, if the text-property name has a
497 non-nil `format-list-valued' property, then the value will be consed onto the
498 surrounding value of the property, rather than replacing that value.
501 the TRANSLATIONS list: PARAMETER and FUNCTION \(spelled in uppercase).
502 Annotations listed under the pseudo-property PARAMETER are considered to be
503 arguments of the immediately surrounding annotation; the text between the
504 opening and closing parameter annotations is deleted from the buffer but saved
505 as a string. The surrounding annotation should be listed under the
506 pseudo-property FUNCTION. Instead of inserting a text-property for this
507 annotation, the function listed in the VALUE slot is called to make whatever
508 changes are appropriate. The function's first two arguments are the START and
509 END locations, and the rest of the arguments are any PARAMETERs found in that
510 region.
512 Any annotations that are found by NEXT-FN but not defined by TRANSLATIONS
513 are saved as values of the `unknown' text-property \(which is list-valued).
514 The TRANSLATIONS list should usually contain an entry of the form
515 \(unknown \(nil format-annotate-value))
516 to write these unknown annotations back into the file."
529 ;; Delete the annotation
532 ;; Positive annotations are stacked, remembering location
534 ;; It is a negative annotation:
535 ;; Close the top annotation & add its text property.
536 ;; If the file's nesting is messed up, the close might not match
537 ;; the top thing on the open-annotations stack.
538 ;; If no matching annotation is open, just ignore the close.
541 ;; If one is open, but not on the top of the stack, close
542 ;; the things in between as well. Set `found' when the real
543 ;; one is closed.
554 ;; Look through property names in TRANSLATIONS
558 ;; And look through values for each property
563 ;; This annotation is listed, but still have to
564 ;; check if multiple annotations are satisfied
568 ans))
569 nil ; multiple ans not satisfied
570 ;; Yes, all set.
571 ;; If there are multiple annotations going
572 ;; into one text property, adjust the
573 ;; begin points of the other annotations
574 ;; so that we don't get double marking.
576 this-one)
584 ;; Set loop variables to nil so loop
585 ;; will exit.
587 ;; pop annotation off stack.
590 ;; Check for pseudo-properties
592 ;; This is a parameter of the top open ann:
593 ;; delete text and use as arg.
595 ;; (If nothing open, discard).
600 start loc)))
604 ;; Not a property, but a function to call.
608 ;; Normal property/value pair
611 todo)))))))
615 nil
616 ;; Didn't find any match for the annotation:
617 ;; Store as value of text-property `unknown'.
620 todo))
623 ;; Once entire file has been scanned, add the properties.
632 from to prop
636 ; list-valued properties
645 ;;;
646 ;;; Encoding
647 ;;;
650 "Apply list of annotations to buffer as `write-region' would.
651 Inserts each element of the given LIST of buffer annotations at its
652 appropriate place. Use second arg OFFSET if the annotations' locations are
653 not relative to the beginning of the buffer: annotations will be inserted
654 at their location-OFFSET+1 \(ie, the offset is treated as the character number
655 of the first character in the buffer)."
666 "Return OLD and NEW as a \(close . open) annotation pair.
667 Useful as a default function for TRANSLATIONS alist when the value of the text
668 property is the name of the annotation that you want to use, as it is for the
669 `unknown' text property."
674 "Generate annotations for text properties in the region.
675 Searches for changes between FROM and TO, and describes them with a list of
676 annotations as defined by alist TRANSLATIONS and FORMAT-FN. IGNORE lists text
677 properties not to consider; any text properties that are neither ignored nor
678 listed in TRANSLATIONS are warned about.
679 If you actually want to modify the region, give the return value of this
680 function to `format-insert-annotations'.
682 Format of the TRANSLATIONS argument:
684 Each element is a list whose car is a PROPERTY, and the following
685 elements are VALUES of that property followed by the names of zero or more
686 ANNOTATIONS. Whenever the property takes on that value, the annotations
687 \(as formatted by FORMAT-FN) are inserted into the file.
688 When the property stops having that value, the matching negated annotation
689 will be inserted \(it may actually be closed earlier and reopened, if
690 necessary, to keep proper nesting).
692 If the property's value is a list, then each element of the list is dealt with
693 separately.
695 If a VALUE is numeric, then it is assumed that there is a single annotation
696 and each occurrence of it increments the value of the property by that number.
698 changes from 4 to 12, two <indent> annotations will be generated.
700 If the VALUE is nil, then instead of annotations, a function should be
701 specified. This function is used as a default: it is called for all
702 transitions not explicitly listed in the table. The function is called with
703 two arguments, the OLD and NEW values of the property. It should return
704 lists of annotations like `format-annotate-location' does.
706 The same structure can be used in reverse for reading files."
721 ;; First do the negative (closing) annotations
723 ;; Check if it's missing. This can happen (eg, a numeric property
724 ;; going negative can generate closing annotations before there are
725 ;; any open). Warn user & ignore.
729 ;; To close anno. N, need to first close ans 1 to N-1,
730 ;; remembering to re-open them later.
734 all-ans))
736 ;; Now remove the one we're really interested in from open list.
738 ;; And put the closing annotation here.
741 all-ans)))
743 ;; Now deal with positive (opening) annotations
749 all-ans))
752 ;; Close any annotations still open
756 all-ans))
760 not-found))
763 ;;; Internal functions for format-annotate-region.
766 "Return annotation(s) needed at LOCATION.
767 This includes any properties that change between LOC-1 and LOC.
768 If ALL is true, don't look at previous location, but generate annotations for
769 all non-nil properties.
770 Third argument IGNORE is a list of text-properties not to consider.
772 Return value is a vector of 3 elements:
773 1. List of names of the annotations to close
774 2. List of the names of annotations to open.
775 3. List of properties that were ignored or couldn't be annotated."
779 p negatives positives prop props not-found)
780 ;; make list of all property names involved
796 nil ; If it's been ignored before, ignore it now.
800 nil ; no change; ignore
802 prop before after trans)))
810 "Return annotations for PROPERTY changing from OLD to NEW.
811 These are searched for in the TRANSLATIONS alist.
812 If NEW does not appear in the list, but there is a default function, then that
813 function is called.
814 Annotations to open and to close are returned as a dotted pair."
816 default)
818 nil
819 ;; If property is numeric, nil means 0
824 ;; If either old or new is a list, have to treat both that way.
829 close open)
834 close)
840 open)
846 "Internal function annotate a single property change.
847 PROP-ALIST is the relevant segment of a TRANSLATIONS list.
848 OLD and NEW are the values."
850 ;; Numerical annotation - use difference
864 ;; Standard annotation
869 ;; Call "Default" function, if any
875 ;; format.el ends here