Previous: Magic File Names, Up: Files
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.
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:
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.
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:
(
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.
t
if the encoding function modifies the buffer, and
nil
if it works by returning a list of annotations.
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
.
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.
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.
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 specifiesnil
.
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 ininsert-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 specifiesnil
.
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 ofbuffer-file-format
for writing auto-save files. This variable is always buffer-local in all buffers.