GNU Emacs Lisp Reference Manual

22.12: 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 function to call to decode data in this format (to convert file data into the usual Emacs data representation).

The from-fn is called with two args, 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 function to call to encode data in this format (to convert the usual Emacs data representation into this format).

The to-fn is called with two args, 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

A mode function to call after visiting a file converted from this format.

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 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.

Function: 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.

Function: 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.

Function: 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 (see 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.

Function: 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.

Function: 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 (see 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; but it is used instead of buffer-file-format for writing auto-save files. This variable is always local in all buffers.