diff options
Diffstat (limited to 'devdocs/elisp/lisp-and-coding-systems.html')
| -rw-r--r-- | devdocs/elisp/lisp-and-coding-systems.html | 55 |
1 files changed, 55 insertions, 0 deletions
diff --git a/devdocs/elisp/lisp-and-coding-systems.html b/devdocs/elisp/lisp-and-coding-systems.html new file mode 100644 index 00000000..e17e1ff2 --- /dev/null +++ b/devdocs/elisp/lisp-and-coding-systems.html @@ -0,0 +1,55 @@ + <h4 class="subsection">Coding Systems in Lisp</h4> <p>Here are the Lisp facilities for working with coding systems: </p> <dl> <dt id="coding-system-list">Function: <strong>coding-system-list</strong> <em>&optional base-only</em> +</dt> <dd><p>This function returns a list of all coding system names (symbols). If <var>base-only</var> is non-<code>nil</code>, the value includes only the base coding systems. Otherwise, it includes alias and variant coding systems as well. </p></dd> +</dl> <dl> <dt id="coding-system-p">Function: <strong>coding-system-p</strong> <em>object</em> +</dt> <dd><p>This function returns <code>t</code> if <var>object</var> is a coding system name or <code>nil</code>. </p></dd> +</dl> <dl> <dt id="check-coding-system">Function: <strong>check-coding-system</strong> <em>coding-system</em> +</dt> <dd><p>This function checks the validity of <var>coding-system</var>. If that is valid, it returns <var>coding-system</var>. If <var>coding-system</var> is <code>nil</code>, the function returns <code>nil</code>. For any other values, it signals an error whose <code>error-symbol</code> is <code>coding-system-error</code> (see <a href="signaling-errors">signal</a>). </p></dd> +</dl> <dl> <dt id="coding-system-eol-type">Function: <strong>coding-system-eol-type</strong> <em>coding-system</em> +</dt> <dd> +<p>This function returns the type of end-of-line (a.k.a. <em>eol</em>) conversion used by <var>coding-system</var>. If <var>coding-system</var> specifies a certain eol conversion, the return value is an integer 0, 1, or 2, standing for <code>unix</code>, <code>dos</code>, and <code>mac</code>, respectively. If <var>coding-system</var> doesn’t specify eol conversion explicitly, the return value is a vector of coding systems, each one with one of the possible eol conversion types, like this: </p> <div class="lisp"> <pre class="lisp">(coding-system-eol-type 'latin-1) + ⇒ [latin-1-unix latin-1-dos latin-1-mac] +</pre> +</div> <p>If this function returns a vector, Emacs will decide, as part of the text encoding or decoding process, what eol conversion to use. For decoding, the end-of-line format of the text is auto-detected, and the eol conversion is set to match it (e.g., DOS-style CRLF format will imply <code>dos</code> eol conversion). For encoding, the eol conversion is taken from the appropriate default coding system (e.g., default value of <code>buffer-file-coding-system</code> for <code>buffer-file-coding-system</code>), or from the default eol conversion appropriate for the underlying platform. </p> +</dd> +</dl> <dl> <dt id="coding-system-change-eol-conversion">Function: <strong>coding-system-change-eol-conversion</strong> <em>coding-system eol-type</em> +</dt> <dd> +<p>This function returns a coding system which is like <var>coding-system</var> except for its eol conversion, which is specified by <code>eol-type</code>. <var>eol-type</var> should be <code>unix</code>, <code>dos</code>, <code>mac</code>, or <code>nil</code>. If it is <code>nil</code>, the returned coding system determines the end-of-line conversion from the data. </p> <p><var>eol-type</var> may also be 0, 1 or 2, standing for <code>unix</code>, <code>dos</code> and <code>mac</code>, respectively. </p> +</dd> +</dl> <dl> <dt id="coding-system-change-text-conversion">Function: <strong>coding-system-change-text-conversion</strong> <em>eol-coding text-coding</em> +</dt> <dd><p>This function returns a coding system which uses the end-of-line conversion of <var>eol-coding</var>, and the text conversion of <var>text-coding</var>. If <var>text-coding</var> is <code>nil</code>, it returns <code>undecided</code>, or one of its variants according to <var>eol-coding</var>. </p></dd> +</dl> <dl> <dt id="find-coding-systems-region">Function: <strong>find-coding-systems-region</strong> <em>from to</em> +</dt> <dd> +<p>This function returns a list of coding systems that could be used to encode a text between <var>from</var> and <var>to</var>. All coding systems in the list can safely encode any multibyte characters in that portion of the text. </p> <p>If the text contains no multibyte characters, the function returns the list <code>(undecided)</code>. </p> +</dd> +</dl> <dl> <dt id="find-coding-systems-string">Function: <strong>find-coding-systems-string</strong> <em>string</em> +</dt> <dd><p>This function returns a list of coding systems that could be used to encode the text of <var>string</var>. All coding systems in the list can safely encode any multibyte characters in <var>string</var>. If the text contains no multibyte characters, this returns the list <code>(undecided)</code>. </p></dd> +</dl> <dl> <dt id="find-coding-systems-for-charsets">Function: <strong>find-coding-systems-for-charsets</strong> <em>charsets</em> +</dt> <dd><p>This function returns a list of coding systems that could be used to encode all the character sets in the list <var>charsets</var>. </p></dd> +</dl> <dl> <dt id="check-coding-systems-region">Function: <strong>check-coding-systems-region</strong> <em>start end coding-system-list</em> +</dt> <dd> +<p>This function checks whether coding systems in the list <code>coding-system-list</code> can encode all the characters in the region between <var>start</var> and <var>end</var>. If all of the coding systems in the list can encode the specified text, the function returns <code>nil</code>. If some coding systems cannot encode some of the characters, the value is an alist, each element of which has the form <code>(<var>coding-system1</var> <var>pos1</var> <var>pos2</var> …)</code>, meaning that <var>coding-system1</var> cannot encode characters at buffer positions <var>pos1</var>, <var>pos2</var>, <small class="enddots">...</small>. </p> <p><var>start</var> may be a string, in which case <var>end</var> is ignored and the returned value references string indices instead of buffer positions. </p> +</dd> +</dl> <dl> <dt id="detect-coding-region">Function: <strong>detect-coding-region</strong> <em>start end &optional highest</em> +</dt> <dd> +<p>This function chooses a plausible coding system for decoding the text from <var>start</var> to <var>end</var>. This text should be a byte sequence, i.e., unibyte text or multibyte text with only <acronym>ASCII</acronym> and eight-bit characters (see <a href="explicit-encoding">Explicit Encoding</a>). </p> <p>Normally this function returns a list of coding systems that could handle decoding the text that was scanned. They are listed in order of decreasing priority. But if <var>highest</var> is non-<code>nil</code>, then the return value is just one coding system, the one that is highest in priority. </p> <p>If the region contains only <acronym>ASCII</acronym> characters except for such ISO-2022 control characters ISO-2022 as <code>ESC</code>, the value is <code>undecided</code> or <code>(undecided)</code>, or a variant specifying end-of-line conversion, if that can be deduced from the text. </p> <p>If the region contains null bytes, the value is <code>no-conversion</code>, even if the region contains text encoded in some coding system. </p> +</dd> +</dl> <dl> <dt id="detect-coding-string">Function: <strong>detect-coding-string</strong> <em>string &optional highest</em> +</dt> <dd><p>This function is like <code>detect-coding-region</code> except that it operates on the contents of <var>string</var> instead of bytes in the buffer. </p></dd> +</dl> <dl> <dt id="inhibit-null-byte-detection">Variable: <strong>inhibit-null-byte-detection</strong> +</dt> <dd><p>If this variable has a non-<code>nil</code> value, null bytes are ignored when detecting the encoding of a region or a string. This allows the encoding of text that contains null bytes to be correctly detected, such as Info files with Index nodes. </p></dd> +</dl> <dl> <dt id="inhibit-iso-escape-detection">Variable: <strong>inhibit-iso-escape-detection</strong> +</dt> <dd><p>If this variable has a non-<code>nil</code> value, ISO-2022 escape sequences are ignored when detecting the encoding of a region or a string. The result is that no text is ever detected as encoded in some ISO-2022 encoding, and all escape sequences become visible in a buffer. <strong>Warning:</strong> <em>Use this variable with extreme caution, because many files in the Emacs distribution use ISO-2022 encoding.</em> </p></dd> +</dl> <dl> <dt id="coding-system-charset-list">Function: <strong>coding-system-charset-list</strong> <em>coding-system</em> +</dt> <dd> +<p>This function returns the list of character sets (see <a href="character-sets">Character Sets</a>) supported by <var>coding-system</var>. Some coding systems that support too many character sets to list them all yield special values: </p> +<ul> <li> If <var>coding-system</var> supports all Emacs characters, the value is <code>(emacs)</code>. </li> +<li> If <var>coding-system</var> supports all Unicode characters, the value is <code>(unicode)</code>. </li> +<li> If <var>coding-system</var> supports all ISO-2022 charsets, the value is <code>iso-2022</code>. </li> +<li> If <var>coding-system</var> supports all the characters in the internal coding system used by Emacs version 21 (prior to the implementation of internal Unicode support), the value is <code>emacs-mule</code>. </li> +</ul> </dd> +</dl> <p>See <a href="process-information#Coding-systems-for-a-subprocess">Process Information</a>, in particular the description of the functions <code>process-coding-system</code> and <code>set-process-coding-system</code>, for how to examine or set the coding systems used for I/O to a subprocess. </p><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/Lisp-and-Coding-Systems.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Lisp-and-Coding-Systems.html</a> + </p> +</div> |