GNU Info

(elisp)Format Conversion

---

Prev: Magic File Names Up: Files

---

Enter node , (file) or (file)node

File Format Conversion
======================

   The variable `format-alist' defines a list of "file formats", which
describe textual representations used in files for the data (text,
text-properties, and possibly other information) in an Emacs buffer.
Emacs performs format conversion if appropriate when reading and writing
files.

 - Variable: format-alist
     This list contains one format definition for each defined file
     format.

   Each format definition is a list of this form:

     (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)

   Here is what the elements in a format definition mean:

NAME
     The name of this format.

DOC-STRING
     A documentation string for the format.

REGEXP
     A regular expression which is used to recognize files represented
     in this format.

FROM-FN
     A shell command or function to decode data in this format (to
     convert file data into the usual Emacs data representation).

     A shell command is represented as a string; Emacs runs the command
     as a filter to perform the conversion.

     If FROM-FN is a function, it is called with two arguments, BEGIN
     and END, which specify the part of the buffer it should convert.
     It should convert the text by editing it in place.  Since this can
     change the length of the text, FROM-FN should return the modified
     end position.

     One responsibility of FROM-FN is to make sure that the beginning
     of the file no longer matches REGEXP.  Otherwise it is likely to
     get called again.

TO-FN
     A shell command or function to encode data in this format--that
     is, to convert the usual Emacs data representation into this
     format.

     If TO-FN is a string, it is a shell command; Emacs runs the
     command as a filter to perform the conversion.

     If TO-FN is a function, it is called with two arguments, BEGIN and
     END, which specify the part of the buffer it should convert.
     There are two ways it can do the conversion:

        * By editing the buffer in place.  In this case, TO-FN should
          return the end-position of the range of text, as modified.

        * By returning a list of annotations.  This is a list of
          elements of the form `(POSITION . STRING)', where POSITION is
          an integer specifying the relative position in the text to be
          written, and STRING is the annotation to add there.  The list
          must be sorted in order of position when TO-FN returns it.

          When `write-region' actually writes the text from the buffer
          to the file, it intermixes the specified annotations at the
          corresponding positions.  All this takes place without
          modifying the buffer.

MODIFY
     A flag, `t' if the encoding function modifies the buffer, and
     `nil' if it works by returning a list of annotations.

MODE-FN
     A minor-mode function to call after visiting a file converted from
     this format.  The function is called with one argument, the
     integer 1; that tells a minor-mode function to enable the mode.

   The function `insert-file-contents' automatically recognizes file
formats when it reads the specified file.  It checks the text of the
beginning of the file against the regular expressions of the format
definitions, and if it finds a match, it calls the decoding function for
that format.  Then it checks all the known formats over again.  It
keeps checking them until none of them is applicable.

   Visiting a file, with `find-file-noselect' or the commands that use
it, performs conversion likewise (because it calls
`insert-file-contents'); it also calls the mode function for each
format that it decodes.  It stores a list of the format names in the
buffer-local variable `buffer-file-format'.

 - Variable: buffer-file-format
     This variable states the format of the visited file.  More
     precisely, this is a list of the file format names that were
     decoded in the course of visiting the current buffer's file.  It
     is always buffer-local in all buffers.

   When `write-region' writes data into a file, it first calls the
encoding functions for the formats listed in `buffer-file-format', in
the order of appearance in the list.

 - Command: format-write-file file format
     This command writes the current buffer contents into the file FILE
     in format FORMAT, and makes that format the default for future
     saves of the buffer.  The argument FORMAT is a list of format
     names.

 - Command: format-find-file file format
     This command finds the file FILE, converting it according to
     format FORMAT.  It also makes FORMAT the default if the buffer is
     saved later.

     The argument FORMAT is a list of format names.  If FORMAT is
     `nil', no conversion takes place.  Interactively, typing just
     <RET> for FORMAT specifies `nil'.

 - Command: format-insert-file file format &optional beg end
     This command inserts the contents of file FILE, converting it
     according to format FORMAT.  If BEG and END are non-`nil', they
     specify which part of the file to read, as in
     `insert-file-contents' (Note: Reading from Files).

     The return value is like what `insert-file-contents' returns: a
     list of the absolute file name and the length of the data inserted
     (after conversion).

     The argument FORMAT is a list of format names.  If FORMAT is
     `nil', no conversion takes place.  Interactively, typing just
     <RET> for FORMAT specifies `nil'.

 - Variable: auto-save-file-format
     This variable specifies the format to use for auto-saving.  Its
     value is a list of format names, just like the value of
     `buffer-file-format'; however, it is used instead of
     `buffer-file-format' for writing auto-save files.  This variable is
     always buffer-local in all buffers.