diff options
Diffstat (limited to 'devdocs/elisp/format-conversion-round_002dtrip.html')
| -rw-r--r-- | devdocs/elisp/format-conversion-round_002dtrip.html | 35 |
1 files changed, 35 insertions, 0 deletions
diff --git a/devdocs/elisp/format-conversion-round_002dtrip.html b/devdocs/elisp/format-conversion-round_002dtrip.html new file mode 100644 index 00000000..a9c0636a --- /dev/null +++ b/devdocs/elisp/format-conversion-round_002dtrip.html @@ -0,0 +1,35 @@ + <h4 class="subsection">Round-Trip Specification</h4> <p>The most general of the two facilities is controlled by the variable <code>format-alist</code>, a list of <em>file format</em> specifications, which describe textual representations used in files for the data in an Emacs buffer. The descriptions for reading and writing are paired, which is why we call this “round-trip” specification (see <a href="format-conversion-piecemeal">Format Conversion Piecemeal</a>, for non-paired specification). </p> <dl> <dt id="format-alist">Variable: <strong>format-alist</strong> +</dt> <dd> +<p>This list contains one format definition for each defined file format. Each format definition is a list of this form: </p> <div class="example"> <pre class="example">(<var>name</var> <var>doc-string</var> <var>regexp</var> <var>from-fn</var> <var>to-fn</var> <var>modify</var> <var>mode-fn</var> <var>preserve</var>) +</pre> +</div> </dd> +</dl> <p>Here is what the elements in a format definition mean: </p> <dl compact> <dt><var>name</var></dt> <dd> +<p>The name of this format. </p> </dd> <dt><var>doc-string</var></dt> <dd> +<p>A documentation string for the format. </p> </dd> <dt><var>regexp</var></dt> <dd> +<p>A regular expression which is used to recognize files represented in this format. If <code>nil</code>, the format is never applied automatically. </p> </dd> <dt><var>from-fn</var></dt> <dd> +<p>A shell command or function to decode data in this format (to convert file data into the usual Emacs data representation). </p> <p>A shell command is represented as a string; Emacs runs the command as a filter to perform the conversion. </p> <p>If <var>from-fn</var> is a function, it is called with two arguments, <var>begin</var> and <var>end</var>, 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, <var>from-fn</var> should return the modified end position. </p> <p>One responsibility of <var>from-fn</var> is to make sure that the beginning of the file no longer matches <var>regexp</var>. Otherwise it is likely to get called again. Also, <var>from-fn</var> must not involve buffers or files other than the one being decoded, otherwise the internal buffer used for formatting might be overwritten. </p> </dd> <dt><var>to-fn</var></dt> <dd> +<p>A shell command or function to encode data in this format—that is, to convert the usual Emacs data representation into this format. </p> <p>If <var>to-fn</var> is a string, it is a shell command; Emacs runs the command as a filter to perform the conversion. </p> <p>If <var>to-fn</var> is a function, it is called with three arguments: <var>begin</var> and <var>end</var>, which specify the part of the buffer it should convert, and <var>buffer</var>, which specifies which buffer. There are two ways it can do the conversion: </p> <ul> <li> By editing the buffer in place. In this case, <var>to-fn</var> should return the end-position of the range of text, as modified. </li> +<li> By returning a list of annotations. This is a list of elements of the form <code>(<var>position</var> . <var>string</var>)</code>, where <var>position</var> is an integer specifying the relative position in the text to be written, and <var>string</var> is the annotation to add there. The list must be sorted in order of position when <var>to-fn</var> returns it. <p>When <code>write-region</code> 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. </p> +</li> +</ul> <p><var>to-fn</var> must not involve buffers or files other than the one being encoded, otherwise the internal buffer used for formatting might be overwritten. </p> </dd> <dt><var>modify</var></dt> <dd> +<p>A flag, <code>t</code> if the encoding function modifies the buffer, and <code>nil</code> if it works by returning a list of annotations. </p> </dd> <dt><var>mode-fn</var></dt> <dd> +<p>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. </p> </dd> <dt><var>preserve</var></dt> <dd><p>A flag, <code>t</code> if <code>format-write-file</code> should not remove this format from <code>buffer-file-format</code>. </p></dd> </dl> <p>The function <code>insert-file-contents</code> 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. </p> <p>Visiting a file, with <code>find-file-noselect</code> or the commands that use it, performs conversion likewise (because it calls <code>insert-file-contents</code>); 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 <code>buffer-file-format</code>. </p> <dl> <dt id="buffer-file-format">Variable: <strong>buffer-file-format</strong> +</dt> <dd><p>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. </p></dd> +</dl> <p>When <code>write-region</code> writes data into a file, it first calls the encoding functions for the formats listed in <code>buffer-file-format</code>, in the order of appearance in the list. </p> <dl> <dt id="format-write-file">Command: <strong>format-write-file</strong> <em>file format &optional confirm</em> +</dt> <dd><p>This command writes the current buffer contents into the file <var>file</var> in a format based on <var>format</var>, which is a list of format names. It constructs the actual format starting from <var>format</var>, then appending any elements from the value of <code>buffer-file-format</code> with a non-<code>nil</code> <var>preserve</var> flag (see above), if they are not already present in <var>format</var>. It then updates <code>buffer-file-format</code> with this format, making it the default for future saves. Except for the <var>format</var> argument, this command is similar to <code>write-file</code>. In particular, <var>confirm</var> has the same meaning and interactive treatment as the corresponding argument to <code>write-file</code>. See <a href="saving-buffers#Definition-of-write_002dfile">Definition of write-file</a>. </p></dd> +</dl> <dl> <dt id="format-find-file">Command: <strong>format-find-file</strong> <em>file format</em> +</dt> <dd> +<p>This command finds the file <var>file</var>, converting it according to format <var>format</var>. It also makes <var>format</var> the default if the buffer is saved later. </p> <p>The argument <var>format</var> is a list of format names. If <var>format</var> is <code>nil</code>, no conversion takes place. Interactively, typing just <tt class="key">RET</tt> for <var>format</var> specifies <code>nil</code>. </p> +</dd> +</dl> <dl> <dt id="format-insert-file">Command: <strong>format-insert-file</strong> <em>file format &optional beg end</em> +</dt> <dd> +<p>This command inserts the contents of file <var>file</var>, converting it according to format <var>format</var>. If <var>beg</var> and <var>end</var> are non-<code>nil</code>, they specify which part of the file to read, as in <code>insert-file-contents</code> (see <a href="reading-from-files">Reading from Files</a>). </p> <p>The return value is like what <code>insert-file-contents</code> returns: a list of the absolute file name and the length of the data inserted (after conversion). </p> <p>The argument <var>format</var> is a list of format names. If <var>format</var> is <code>nil</code>, no conversion takes place. Interactively, typing just <tt class="key">RET</tt> for <var>format</var> specifies <code>nil</code>. </p> +</dd> +</dl> <dl> <dt id="buffer-auto-save-file-format">Variable: <strong>buffer-auto-save-file-format</strong> +</dt> <dd><p>This variable specifies the format to use for auto-saving. Its value is a list of format names, just like the value of <code>buffer-file-format</code>; however, it is used instead of <code>buffer-file-format</code> for writing auto-save files. If the value is <code>t</code>, the default, auto-saving uses the same format as a regular save in the same buffer. This variable is always buffer-local in all buffers. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Format-Conversion-Round_002dTrip.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Format-Conversion-Round_002dTrip.html</a> + </p> +</div> |