annotate doc/lispref/nonascii.texi @ 101349:191a3121c949

* frame.el (make-frame-on-tty): Remove function, inline contents in the only user ... * server.el (server-create-tty-frame): ... here. * frames.texi (Multiple Displays): Remove documentation for removed function make-frame-on-tty.
author Dan Nicolaescu <dann@ics.uci.edu>
date Thu, 22 Jan 2009 06:58:10 +0000
parents e053f08d03ae
children 8f7ed9f9309f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3 @c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004,
100974
cb5d2387102c Add 2009 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 100248
diff changeset
4 @c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
84116
0ba80d073e27 (setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents: 84090
diff changeset
6 @setfilename ../../info/characters
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7 @node Non-ASCII Characters, Searching and Matching, Text, Top
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8 @chapter Non-@acronym{ASCII} Characters
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9 @cindex multibyte characters
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10 @cindex characters, multi-byte
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11 @cindex non-@acronym{ASCII} characters
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12
99313
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
13 This chapter covers the special issues relating to characters and
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
14 how they are stored in strings and buffers.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16 @menu
99313
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
17 * Text Representations:: How Emacs represents text.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18 * Converting Representations:: Converting unibyte to multibyte and vice versa.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19 * Selecting a Representation:: Treating a byte sequence as unibyte or multi.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20 * Character Codes:: How unibyte and multibyte relate to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21 codes of individual characters.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
22 * Character Properties:: Character attributes that define their
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
23 behavior and handling.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
24 * Character Sets:: The space of possible character codes
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
25 is divided into various character sets.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
26 * Scanning Charsets:: Which character sets are used in a buffer?
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
27 * Translation of Characters:: Translation tables are used for conversion.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
28 * Coding Systems:: Coding systems are conversions for saving files.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
29 * Input Methods:: Input methods allow users to enter various
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
30 non-ASCII characters without special keyboards.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
31 * Locales:: Interacting with the POSIX locale.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
32 @end menu
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
33
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
34 @node Text Representations
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
35 @section Text Representations
99313
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
36 @cindex text representation
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
37
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
38 Emacs buffers and strings support a large repertoire of characters
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
39 from many different scripts. This is so users could type and display
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
40 text in most any known written language.
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
41
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
42 @cindex character codepoint
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
43 @cindex codespace
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
44 @cindex Unicode
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
45 To support this multitude of characters and scripts, Emacs closely
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
46 follows the @dfn{Unicode Standard}. The Unicode Standard assigns a
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
47 unique number, called a @dfn{codepoint}, to each and every character.
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
48 The range of codepoints defined by Unicode, or the Unicode
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
49 @dfn{codespace}, is @code{0..10FFFF} (in hex), inclusive. Emacs
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
50 extends this range with codepoints in the range @code{110000..3FFFFF},
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
51 which it uses for representing characters that are not unified with
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
52 Unicode and raw 8-bit bytes that cannot be interpreted as characters
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
53 (the latter occupy the range @code{3FFF80..3FFFFF}). Thus, a
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
54 character codepoint in Emacs is a 22-bit integer number.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
55
99313
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
56 @cindex internal representation of characters
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
57 @cindex characters, representation in buffers and strings
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
58 @cindex multibyte text
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
59 To conserve memory, Emacs does not hold fixed-length 22-bit numbers
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
60 that are codepoints of text characters within buffers and strings.
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
61 Rather, Emacs uses a variable-length internal representation of
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
62 characters, that stores each character as a sequence of 1 to 5 8-bit
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
63 bytes, depending on the magnitude of its codepoint@footnote{
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
64 This internal representation is based on one of the encodings defined
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
65 by the Unicode Standard, called @dfn{UTF-8}, for representing any
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
66 Unicode codepoint, but Emacs extends UTF-8 to represent the additional
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
67 codepoints it uses for raw 8-bit bytes and characters not unified with
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
68 Unicode.}.
99313
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
69 For example, any @acronym{ASCII} character takes up only 1 byte, a
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
70 Latin-1 character takes up 2 bytes, etc. We call this representation
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
71 of text @dfn{multibyte}, because it uses several bytes for each
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
72 character.
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
73
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
74 Outside Emacs, characters can be represented in many different
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
75 encodings, such as ISO-8859-1, GB-2312, Big-5, etc. Emacs converts
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
76 between these external encodings and the internal representation, as
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
77 appropriate, when it reads text into a buffer or a string, or when it
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
78 writes text to a disk file or passes it to some other process.
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
79
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
80 Occasionally, Emacs needs to hold and manipulate encoded text or
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
81 binary non-text data in its buffers or strings. For example, when
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
82 Emacs visits a file, it first reads the file's text verbatim into a
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
83 buffer, and only then converts it to the internal representation.
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
84 Before the conversion, the buffer holds encoded text.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
85
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
86 @cindex unibyte text
99313
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
87 Encoded text is not really text, as far as Emacs is concerned, but
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
88 rather a sequence of raw 8-bit bytes. We call buffers and strings
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
89 that hold encoded text @dfn{unibyte} buffers and strings, because
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
90 Emacs treats them as a sequence of individual bytes. In particular,
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
91 Emacs usually displays unibyte buffers and strings as octal codes such
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
92 as @code{\237}. We recommend that you never use unibyte buffers and
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
93 strings except for manipulating encoded text or binary non-text data.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
94
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
95 In a buffer, the buffer-local value of the variable
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
96 @code{enable-multibyte-characters} specifies the representation used.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
97 The representation for a string is determined and recorded in the string
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
98 when the string is constructed.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
99
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
100 @defvar enable-multibyte-characters
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
101 This variable specifies the current buffer's text representation.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
102 If it is non-@code{nil}, the buffer contains multibyte text; otherwise,
99313
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
103 it contains unibyte encoded text or binary non-text data.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
104
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
105 You cannot set this variable directly; instead, use the function
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
106 @code{set-buffer-multibyte} to change a buffer's representation.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
107 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
108
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
109 @defvar default-enable-multibyte-characters
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
110 This variable's value is entirely equivalent to @code{(default-value
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
111 'enable-multibyte-characters)}, and setting this variable changes that
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
112 default value. Setting the local binding of
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
113 @code{enable-multibyte-characters} in a specific buffer is not allowed,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
114 but changing the default value is supported, and it is a reasonable
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
115 thing to do, because it has no effect on existing buffers.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
116
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
117 The @samp{--unibyte} command line option does its job by setting the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
118 default value to @code{nil} early in startup.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
119 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
120
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
121 @defun position-bytes position
99313
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
122 Buffer positions are measured in character units. This function
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
123 returns the byte-position corresponding to buffer position
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
124 @var{position} in the current buffer. This is 1 at the start of the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
125 buffer, and counts upward in bytes. If @var{position} is out of
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
126 range, the value is @code{nil}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
127 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
128
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
129 @defun byte-to-position byte-position
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
130 Return the buffer position, in character units, corresponding to given
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
131 @var{byte-position} in the current buffer. If @var{byte-position} is
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
132 out of range, the value is @code{nil}. In a multibyte buffer, an
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
133 arbitrary value of @var{byte-position} can be not at character
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
134 boundary, but inside a multibyte sequence representing a single
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
135 character; in this case, this function returns the buffer position of
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
136 the character whose multibyte sequence includes @var{byte-position}.
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
137 In other words, the value does not change for all byte positions that
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
138 belong to the same character.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
139 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
140
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
141 @defun multibyte-string-p string
99313
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
142 Return @code{t} if @var{string} is a multibyte string, @code{nil}
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
143 otherwise.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
144 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
145
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
146 @defun string-bytes string
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
147 @cindex string, number of bytes
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
148 This function returns the number of bytes in @var{string}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
149 If @var{string} is a multibyte string, this can be greater than
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
150 @code{(length @var{string})}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
151 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
152
99313
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
153 @defun unibyte-string &rest bytes
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
154 This function concatenates all its argument @var{bytes} and makes the
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
155 result a unibyte string.
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
156 @end defun
175420e76f65 (Text Representations): Rewrite to make consistent with Emacs 23
Eli Zaretskii <eliz@gnu.org>
parents: 99044
diff changeset
157
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
158 @node Converting Representations
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
159 @section Converting Text Representations
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
160
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
161 Emacs can convert unibyte text to multibyte; it can also convert
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
162 multibyte text to unibyte, provided that the multibyte text contains
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
163 only @acronym{ASCII} and 8-bit raw bytes. In general, these
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
164 conversions happen when inserting text into a buffer, or when putting
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
165 text from several strings together in one string. You can also
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
166 explicitly convert a string's contents to either representation.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
167
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
168 Emacs chooses the representation for a string based on the text that
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
169 it is constructed from. The general rule is to convert unibyte text to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
170 multibyte text when combining it with other multibyte text, because the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
171 multibyte representation is more general and can hold whatever
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
172 characters the unibyte text has.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
173
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
174 When inserting text into a buffer, Emacs converts the text to the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
175 buffer's representation, as specified by
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
176 @code{enable-multibyte-characters} in that buffer. In particular, when
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
177 you insert multibyte text into a unibyte buffer, Emacs converts the text
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
178 to unibyte, even though this conversion cannot in general preserve all
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
179 the characters that might be in the multibyte text. The other natural
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
180 alternative, to convert the buffer contents to multibyte, is not
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
181 acceptable because the buffer's representation is a choice made by the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
182 user that cannot be overridden automatically.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
183
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
184 Converting unibyte text to multibyte text leaves @acronym{ASCII} characters
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
185 unchanged, and converts bytes with codes 128 through 159 to the
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
186 multibyte representation of raw eight-bit bytes.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
187
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
188 Converting multibyte text to unibyte converts all @acronym{ASCII}
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
189 and eight-bit characters to their single-byte form, but loses
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
190 information for non-@acronym{ASCII} characters by discarding all but
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
191 the low 8 bits of each character's codepoint. Converting unibyte text
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
192 to multibyte and back to unibyte reproduces the original unibyte text.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
193
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
194 The next two functions either return the argument @var{string}, or a
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
195 newly created string with no text properties.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
196
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
197 @defun string-to-multibyte string
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
198 This function returns a multibyte string containing the same sequence
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
199 of characters as @var{string}. If @var{string} is a multibyte string,
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
200 it is returned unchanged. The function assumes that @var{string}
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
201 includes only @acronym{ASCII} characters and raw 8-bit bytes; the
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
202 latter are converted to their multibyte representation corresponding
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
203 to the codepoints in the @code{3FFF80..3FFFFF} area (@pxref{Text
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
204 Representations, codepoints}).
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
205 @end defun
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
206
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
207 @defun string-to-unibyte string
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
208 This function returns a unibyte string containing the same sequence of
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
209 characters as @var{string}. It signals an error if @var{string}
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
210 contains a non-@acronym{ASCII} character. If @var{string} is a
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
211 unibyte string, it is returned unchanged. Use this function for
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
212 @var{string} arguments that contain only @acronym{ASCII} and eight-bit
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
213 characters.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
214 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
215
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
216 @defun multibyte-char-to-unibyte char
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
217 This convert the multibyte character @var{char} to a unibyte
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
218 character. If @var{char} is a character that is neither
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
219 @acronym{ASCII} nor eight-bit, the value is -1.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
220 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
221
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
222 @defun unibyte-char-to-multibyte char
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
223 This convert the unibyte character @var{char} to a multibyte
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
224 character, assuming @var{char} is either @acronym{ASCII} or raw 8-bit
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
225 byte.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
226 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
227
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
228 @node Selecting a Representation
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
229 @section Selecting a Representation
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
230
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
231 Sometimes it is useful to examine an existing buffer or string as
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
232 multibyte when it was unibyte, or vice versa.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
233
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
234 @defun set-buffer-multibyte multibyte
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
235 Set the representation type of the current buffer. If @var{multibyte}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
236 is non-@code{nil}, the buffer becomes multibyte. If @var{multibyte}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
237 is @code{nil}, the buffer becomes unibyte.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
238
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
239 This function leaves the buffer contents unchanged when viewed as a
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
240 sequence of bytes. As a consequence, it can change the contents
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
241 viewed as characters; a sequence of three bytes which is treated as
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
242 one character in multibyte representation will count as three
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
243 characters in unibyte representation. Eight-bit characters
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
244 representing raw bytes are an exception. They are represented by one
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
245 byte in a unibyte buffer, but when the buffer is set to multibyte,
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
246 they are converted to two-byte sequences, and vice versa.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
247
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
248 This function sets @code{enable-multibyte-characters} to record which
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
249 representation is in use. It also adjusts various data in the buffer
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
250 (including overlays, text properties and markers) so that they cover the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
251 same text as they did before.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
252
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
253 You cannot use @code{set-buffer-multibyte} on an indirect buffer,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
254 because indirect buffers always inherit the representation of the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
255 base buffer.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
256 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
257
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
258 @defun string-as-unibyte string
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
259 This function returns a string with the same bytes as @var{string} but
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
260 treating each byte as a character. This means that the value may have
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
261 more characters than @var{string} has. Eight-bit characters
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
262 representing raw bytes are an exception: each one of them is converted
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
263 to a single byte.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
264
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
265 If @var{string} is already a unibyte string, then the value is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
266 @var{string} itself. Otherwise it is a newly created string, with no
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
267 text properties.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
268 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
269
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
270 @defun string-as-multibyte string
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
271 This function returns a string with the same bytes as @var{string} but
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
272 treating each multibyte sequence as one character. This means that
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
273 the value may have fewer characters than @var{string} has. If a byte
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
274 sequence in @var{string} is invalid as a multibyte representation of a
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
275 single character, each byte in the sequence is treated as raw 8-bit
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
276 byte.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
277
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
278 If @var{string} is already a multibyte string, then the value is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
279 @var{string} itself. Otherwise it is a newly created string, with no
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
280 text properties.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
281 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
282
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
283 @node Character Codes
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
284 @section Character Codes
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
285 @cindex character codes
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
286
99044
7c989edf1f9f (Character Codes): Remove obsolete function char-valid-p, and document
Chong Yidong <cyd@stupidchicken.com>
parents: 98710
diff changeset
287 The unibyte and multibyte text representations use different
7c989edf1f9f (Character Codes): Remove obsolete function char-valid-p, and document
Chong Yidong <cyd@stupidchicken.com>
parents: 98710
diff changeset
288 character codes. The valid character codes for unibyte representation
7c989edf1f9f (Character Codes): Remove obsolete function char-valid-p, and document
Chong Yidong <cyd@stupidchicken.com>
parents: 98710
diff changeset
289 range from 0 to 255---the values that can fit in one byte. The valid
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
290 character codes for multibyte representation range from 0 to 4194303
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
291 (#x3FFFFF). In this code space, values 0 through 127 are for
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
292 @acronym{ASCII} charcters, and values 129 through 4194175 (#x3FFF7F)
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
293 are for non-@acronym{ASCII} characters. Values 0 through 1114111
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
294 (#10FFFF) corresponds to Unicode characters of the same codepoint,
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
295 while values 4194176 (#x3FFF80) through 4194303 (#x3FFFFF) are for
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
296 representing eight-bit raw bytes.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
297
99044
7c989edf1f9f (Character Codes): Remove obsolete function char-valid-p, and document
Chong Yidong <cyd@stupidchicken.com>
parents: 98710
diff changeset
298 @defun characterp charcode
7c989edf1f9f (Character Codes): Remove obsolete function char-valid-p, and document
Chong Yidong <cyd@stupidchicken.com>
parents: 98710
diff changeset
299 This returns @code{t} if @var{charcode} is a valid character, and
7c989edf1f9f (Character Codes): Remove obsolete function char-valid-p, and document
Chong Yidong <cyd@stupidchicken.com>
parents: 98710
diff changeset
300 @code{nil} otherwise.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
301
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
302 @example
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
303 @group
99044
7c989edf1f9f (Character Codes): Remove obsolete function char-valid-p, and document
Chong Yidong <cyd@stupidchicken.com>
parents: 98710
diff changeset
304 (characterp 65)
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
305 @result{} t
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
306 @end group
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
307 @group
99044
7c989edf1f9f (Character Codes): Remove obsolete function char-valid-p, and document
Chong Yidong <cyd@stupidchicken.com>
parents: 98710
diff changeset
308 (characterp 4194303)
7c989edf1f9f (Character Codes): Remove obsolete function char-valid-p, and document
Chong Yidong <cyd@stupidchicken.com>
parents: 98710
diff changeset
309 @result{} t
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
310 @end group
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
311 @group
99044
7c989edf1f9f (Character Codes): Remove obsolete function char-valid-p, and document
Chong Yidong <cyd@stupidchicken.com>
parents: 98710
diff changeset
312 (characterp 4194304)
7c989edf1f9f (Character Codes): Remove obsolete function char-valid-p, and document
Chong Yidong <cyd@stupidchicken.com>
parents: 98710
diff changeset
313 @result{} nil
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
314 @end group
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
315 @end example
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
316 @end defun
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
317
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
318 @cindex maximum value of character codepoint
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
319 @cindex codepoint, largest value
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
320 @defun max-char
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
321 This function returns the largest value that a valid character
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
322 codepoint can have.
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
323
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
324 @example
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
325 @group
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
326 (characterp (max-char))
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
327 @result{} t
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
328 @end group
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
329 @group
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
330 (characterp (1+ (max-char)))
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
331 @result{} nil
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
332 @end group
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
333 @end example
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
334 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
335
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
336 @defun get-byte pos &optional string
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
337 This function returns the byte at current buffer's character position
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
338 @var{pos}. If the current buffer is unibyte, this is literally the
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
339 byte at that position. If the buffer is multibyte, byte values of
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
340 @acronym{ASCII} characters are the same as character codepoints,
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
341 whereas eight-bit raw bytes are converted to their 8-bit codes. The
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
342 function signals an error if the character at @var{pos} is
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
343 non-@acronym{ASCII}.
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
344
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
345 The optional argument @var{string} means to get a byte value from that
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
346 string instead of the current buffer.
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
347 @end defun
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
348
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
349 @node Character Properties
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
350 @section Character Properties
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
351 @cindex character properties
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
352 A @dfn{character property} is a named attribute of a character that
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
353 specifies how the character behaves and how it should be handled
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
354 during text processing and display. Thus, character properties are an
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
355 important part of specifying the character's semantics.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
356
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
357 Emacs generally follows the Unicode Standard in its implementation
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
358 of character properties. In particular, Emacs supports the
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
359 @uref{http://www.unicode.org/reports/tr23/, Unicode Character Property
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
360 Model}, and the Emacs character property database is derived from the
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
361 Unicode Character Database (@acronym{UCD}). See the
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
362 @uref{http://www.unicode.org/versions/Unicode5.0.0/ch04.pdf, Character
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
363 Properties chapter of the Unicode Standard}, for detailed description
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
364 of Unicode character properties and their meaning. This section
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
365 assumes you are already familiar with that chapter of the Unicode
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
366 Standard, and want to apply that knowledge to Emacs Lisp programs.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
367
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
368 The facilities documented in this section are useful for setting and
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
369 retrieving properties of characters.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
370
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
371 In Emacs, each property has a name, which is a symbol, and a set of
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
372 possible values, whose types depend on the property; if a character
101046
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
373 does not have a certain property, the value is @code{nil}. As a
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
374 general rule, the names of character properties in Emacs are produced
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
375 from the corresponding Unicode properties by downcasing them and
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
376 replacing each @samp{_} character with a dash @samp{-}. For example,
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
377 @code{Canonical_Combining_Class} becomes
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
378 @code{canonical-combining-class}. However, sometimes we shorten the
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
379 names to make their use easier.
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
380
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
381 Here's the full list of value types for all the character properties
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
382 that Emacs knows about:
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
383
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
384 @table @code
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
385 @item name
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
386 This property corresponds to the Unicode @code{Name} property. The
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
387 value is a string consisting of upper-case Latin letters A to Z,
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
388 digits, spaces, and hyphen @samp{-} characters.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
389
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
390 @item general-category
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
391 This property corresponds to the Unicode @code{General_Category}
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
392 property. The value is a symbol whose name is a 2-letter abbreviation
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
393 of the character's classification.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
394
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
395 @item canonical-combining-class
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
396 Corresponds to the Unicode @code{Canonical_Combining_Class} property.
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
397 The value is an integer number.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
398
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
399 @item bidi-class
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
400 Corresponds to the Unicode @code{Bidi_Class} property. The value is a
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
401 symbol whose name is the Unicode @dfn{directional type} of the
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
402 character.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
403
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
404 @item decomposition
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
405 Corresponds to the Unicode @code{Decomposition_Type} and
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
406 @code{Decomposition_Value} properties. The value is a list, whose
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
407 first element may be a symbol representing a compatibility formatting
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
408 tag, such as @code{small}@footnote{
101046
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
409 Note that the Unicode spec writes these tag names inside
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
410 @samp{<..>} brackets. The tag names in Emacs do not include the
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
411 brackets; e.g., Unicode specifies @samp{<small>} where Emacs uses
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
412 @samp{small}.
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
413 }; the other elements are characters that give the compatibility
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
414 decomposition sequence of this character.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
415
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
416 @item decimal-digit-value
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
417 Corresponds to the Unicode @code{Numeric_Value} property for
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
418 characters whose @code{Numeric_Type} is @samp{Digit}. The value is an
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
419 integer number.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
420
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
421 @item digit
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
422 Corresponds to the Unicode @code{Numeric_Value} property for
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
423 characters whose @code{Numeric_Type} is @samp{Decimal}. The value is
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
424 an integer number. Examples of such characters include compatibility
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
425 subscript and superscript digits, for which the value is the
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
426 corresponding number.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
427
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
428 @item numeric-value
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
429 Corresponds to the Unicode @code{Numeric_Value} property for
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
430 characters whose @code{Numeric_Type} is @samp{Numeric}. The value of
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
431 this property is an integer of a floating-point number. Examples of
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
432 characters that have this property include fractions, subscripts,
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
433 superscripts, Roman numerals, currency numerators, and encircled
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
434 numbers. For example, the value of this property for the character
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
435 @code{U+2155} (@sc{vulgar fraction one fifth}) is @code{0.2}.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
436
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
437 @item mirrored
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
438 Corresponds to the Unicode @code{Bidi_Mirrored} property. The value
101046
0ce4bafe2b99 (Character Properties): Improve wording.
Eli Zaretskii <eliz@gnu.org>
parents: 101044
diff changeset
439 of this property is a symbol, either @code{Y} or @code{N}.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
440
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
441 @item old-name
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
442 Corresponds to the Unicode @code{Unicode_1_Name} property. The value
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
443 is a string.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
444
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
445 @item iso-10646-comment
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
446 Corresponds to the Unicode @code{ISO_Comment} property. The value is
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
447 a string.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
448
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
449 @item uppercase
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
450 Corresponds to the Unicode @code{Simple_Uppercase_Mapping} property.
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
451 The value of this property is a single character.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
452
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
453 @item lowercase
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
454 Corresponds to the Unicode @code{Simple_Lowercase_Mapping} property.
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
455 The value of this property is a single character.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
456
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
457 @item titlecase
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
458 Corresponds to the Unicode @code{Simple_Titlecase_Mapping} property.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
459 @dfn{Title case} is a special form of a character used when the first
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
460 character of a word needs to be capitalized. The value of this
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
461 property is a single character.
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
462 @end table
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
463
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
464 @defun get-char-code-property char propname
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
465 This function returns the value of @var{char}'s @var{propname} property.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
466
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
467 @example
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
468 @group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
469 (get-char-code-property ? 'general-category)
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
470 @result{} Zs
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
471 @end group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
472 @group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
473 (get-char-code-property ?1 'general-category)
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
474 @result{} Nd
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
475 @end group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
476 @group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
477 (get-char-code-property ?\u2084 'digit-value) ; subscript 4
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
478 @result{} 4
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
479 @end group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
480 @group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
481 (get-char-code-property ?\u2155 'numeric-value) ; one fifth
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
482 @result{} 1/5
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
483 @end group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
484 @group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
485 (get-char-code-property ?\u2163 'numeric-value) ; Roman IV
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
486 @result{} \4
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
487 @end group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
488 @end example
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
489 @end defun
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
490
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
491 @defun char-code-property-description prop value
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
492 This function returns the description string of property @var{prop}'s
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
493 @var{value}, or @code{nil} if @var{value} has no description.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
494
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
495 @example
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
496 @group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
497 (char-code-property-description 'general-category 'Zs)
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
498 @result{} "Separator, Space"
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
499 @end group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
500 @group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
501 (char-code-property-description 'general-category 'Nd)
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
502 @result{} "Number, Decimal Digit"
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
503 @end group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
504 @group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
505 (char-code-property-description 'numeric-value '1/5)
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
506 @result{} nil
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
507 @end group
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
508 @end example
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
509 @end defun
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
510
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
511 @defun put-char-code-property char propname value
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
512 This function stores @var{value} as the value of the property
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
513 @var{propname} for the character @var{char}.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
514 @end defun
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
515
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
516 @defvar char-script-table
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
517 The value of this variable is a char-table (@pxref{Char-Tables}) that
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
518 specifies, for each character, a symbol whose name is the script to
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
519 which the character belongs, according to the Unicode Standard
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
520 classification of the Unicode code space into script-specific blocks.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
521 This char-table has a single extra slot whose value is the list of all
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
522 script symbols.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
523 @end defvar
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
524
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
525 @defvar char-width-table
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
526 The value of this variable is a char-table that specifies the width of
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
527 each character in columns that it will occupy on the screen.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
528 @end defvar
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
529
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
530 @defvar printable-chars
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
531 The value of this variable is a char-table that specifies, for each
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
532 character, whether it is printable or not. That is, if evaluating
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
533 @code{(aref printable-chars char)} results in @code{t}, the character
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
534 is printable, and if it results in @code{nil}, it is not.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
535 @end defvar
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
536
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
537 @node Character Sets
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
538 @section Character Sets
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
539 @cindex character sets
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
540
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
541 @cindex charset
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
542 @cindex coded character set
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
543 An Emacs @dfn{character set}, or @dfn{charset}, is a set of characters
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
544 in which each character is assigned a numeric code point. (The
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
545 Unicode standard calls this a @dfn{coded character set}.) Each Emacs
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
546 charset has a name which is a symbol. A single character can belong
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
547 to any number of different character sets, but it will generally have
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
548 a different code point in each charset. Examples of character sets
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
549 include @code{ascii}, @code{iso-8859-1}, @code{greek-iso8859-7}, and
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
550 @code{windows-1255}. The code point assigned to a character in a
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
551 charset is usually different from its code point used in Emacs buffers
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
552 and strings.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
553
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
554 @cindex @code{emacs}, a charset
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
555 @cindex @code{unicode}, a charset
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
556 @cindex @code{eight-bit}, a charset
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
557 Emacs defines several special character sets. The character set
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
558 @code{unicode} includes all the characters whose Emacs code points are
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
559 in the range @code{0..10FFFF}. The character set @code{emacs}
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
560 includes all @acronym{ASCII} and non-@acronym{ASCII} characters.
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
561 Finally, the @code{eight-bit} charset includes the 8-bit raw bytes;
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
562 Emacs uses it to represent raw bytes encountered in text.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
563
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
564 @defun charsetp object
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
565 Returns @code{t} if @var{object} is a symbol that names a character set,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
566 @code{nil} otherwise.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
567 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
568
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
569 @defvar charset-list
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
570 The value is a list of all defined character set names.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
571 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
572
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
573 @defun charset-priority-list &optional highestp
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
574 This functions returns a list of all defined character sets ordered by
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
575 their priority. If @var{highestp} is non-@code{nil}, the function
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
576 returns a single character set of the highest priority.
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
577 @end defun
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
578
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
579 @defun set-charset-priority &rest charsets
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
580 This function makes @var{charsets} the highest priority character sets.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
581 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
582
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
583 @defun char-charset character
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
584 This function returns the name of the character set of highest
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
585 priority that @var{character} belongs to. @acronym{ASCII} characters
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
586 are an exception: for them, this function always returns @code{ascii}.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
587 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
588
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
589 @defun charset-plist charset
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
590 This function returns the property list of the character set
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
591 @var{charset}. Although @var{charset} is a symbol, this is not the
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
592 same as the property list of that symbol. Charset properties include
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
593 important information about the charset, such as its documentation
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
594 string, short name, etc.
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
595 @end defun
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
596
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
597 @defun put-charset-property charset propname value
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
598 This function sets the @var{propname} property of @var{charset} to the
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
599 given @var{value}.
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
600 @end defun
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
601
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
602 @defun get-charset-property charset propname
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
603 This function returns the value of @var{charset}s property
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
604 @var{propname}.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
605 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
606
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
607 @deffn Command list-charset-chars charset
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
608 This command displays a list of characters in the character set
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
609 @var{charset}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
610 @end deffn
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
611
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
612 Emacs can convert between its internal representation of a character
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
613 and the character's codepoint in a specific charset. The following
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
614 two functions support these conversions.
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
615
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
616 @c FIXME: decode-char and encode-char accept and ignore an additional
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
617 @c argument @var{restriction}. When that argument actually makes a
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
618 @c difference, it should be documented here.
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
619 @defun decode-char charset code-point
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
620 This function decodes a character that is assigned a @var{code-point}
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
621 in @var{charset}, to the corresponding Emacs character, and returns
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
622 it. If @var{charset} doesn't contain a character of that code point,
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
623 the value is @code{nil}. If @var{code-point} doesn't fit in a Lisp
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
624 integer (@pxref{Integer Basics, most-positive-fixnum}), it can be
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
625 specified as a cons cell @code{(@var{high} . @var{low})}, where
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
626 @var{low} are the lower 16 bits of the value and @var{high} are the
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
627 high 16 bits.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
628 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
629
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
630 @defun encode-char char charset
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
631 This function returns the code point assigned to the character
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
632 @var{char} in @var{charset}. If the result does not fit in a Lisp
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
633 integer, it is returned as a cons cell @code{(@var{high} . @var{low})}
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
634 that fits the second argument of @code{decode-char} above. If
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
635 @var{charset} doesn't have a codepoint for @var{char}, the value is
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
636 @code{nil}.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
637 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
638
100248
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
639 The following function comes in handy for applying a certain
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
640 function to all or part of the characters in a charset:
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
641
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
642 @defun map-charset-chars function charset &optional arg from to
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
643 Call @var{function} for characters in @var{charset}. @var{function}
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
644 is called with two arguments. The first one is a cons cell
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
645 @code{(@var{from} . @var{to})}, where @var{from} and @var{to}
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
646 indicate a range of characters contained in charset. The second
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
647 argument is the optional argument @var{arg}.
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
648
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
649 By default, the range of codepoints passed to @var{function} includes
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
650 all the characters in @var{charset}, but optional arguments @var{from}
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
651 and @var{to} limit that to the range of characters between these two
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
652 codepoints. If either of them is @code{nil}, it defaults to the first
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
653 or last codepoint of @var{charset}, respectively.
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
654 @end defun
3d8b80bc42ba (Character Sets): Document `map-charset-chars'.
Eli Zaretskii <eliz@gnu.org>
parents: 100246
diff changeset
655
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
656 @node Scanning Charsets
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
657 @section Scanning for Character Sets
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
658
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
659 Sometimes it is useful to find out, for characters that appear in a
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
660 certain part of a buffer or a string, to which character sets they
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
661 belong. One use for this is in determining which coding systems
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
662 (@pxref{Coding Systems}) are capable of representing all of the text
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
663 in question; another is to determine the font(s) for displaying that
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
664 text.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
665
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
666 @defun charset-after &optional pos
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
667 This function returns the charset of highest priority containing the
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
668 character in the current buffer at position @var{pos}. If @var{pos}
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
669 is omitted or @code{nil}, it defaults to the current value of point.
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
670 If @var{pos} is out of range, the value is @code{nil}.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
671 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
672
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
673 @defun find-charset-region beg end &optional translation
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
674 This function returns a list of the character sets of highest priority
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
675 that contain characters in the current buffer between positions
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
676 @var{beg} and @var{end}.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
677
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
678 The optional argument @var{translation} specifies a translation table to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
679 be used in scanning the text (@pxref{Translation of Characters}). If it
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
680 is non-@code{nil}, then each character in the region is translated
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
681 through this table, and the value returned describes the translated
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
682 characters instead of the characters actually in the buffer.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
683 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
684
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
685 @defun find-charset-string string &optional translation
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
686 This function returns a list of the character sets of highest priority
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
687 that contain characters in @var{string}. It is just like
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
688 @code{find-charset-region}, except that it applies to the contents of
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
689 @var{string} instead of part of the current buffer.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
690 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
691
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
692 @node Translation of Characters
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
693 @section Translation of Characters
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
694 @cindex character translation tables
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
695 @cindex translation tables
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
696
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
697 A @dfn{translation table} is a char-table (@pxref{Char-Tables}) that
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
698 specifies a mapping of characters into characters. These tables are
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
699 used in encoding and decoding, and for other purposes. Some coding
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
700 systems specify their own particular translation tables; there are
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
701 also default translation tables which apply to all other coding
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
702 systems.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
703
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
704 A translation table has two extra slots. The first is either
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
705 @code{nil} or a translation table that performs the reverse
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
706 translation; the second is the maximum number of characters to look up
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
707 for translating sequences of characters (see the description of
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
708 @code{make-translation-table-from-alist} below).
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
709
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
710 @defun make-translation-table &rest translations
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
711 This function returns a translation table based on the argument
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
712 @var{translations}. Each element of @var{translations} should be a
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
713 list of elements of the form @code{(@var{from} . @var{to})}; this says
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
714 to translate the character @var{from} into @var{to}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
715
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
716 The arguments and the forms in each argument are processed in order,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
717 and if a previous form already translates @var{to} to some other
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
718 character, say @var{to-alt}, @var{from} is also translated to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
719 @var{to-alt}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
720 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
721
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
722 During decoding, the translation table's translations are applied to
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
723 the characters that result from ordinary decoding. If a coding system
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
724 has property @code{:decode-translation-table}, that specifies the
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
725 translation table to use, or a list of translation tables to apply in
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
726 sequence. (This is a property of the coding system, as returned by
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
727 @code{coding-system-get}, not a property of the symbol that is the
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
728 coding system's name. @xref{Coding System Basics,, Basic Concepts of
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
729 Coding Systems}.) Finally, if
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
730 @code{standard-translation-table-for-decode} is non-@code{nil}, the
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
731 resulting characters are translated by that table.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
732
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
733 During encoding, the translation table's translations are applied to
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
734 the characters in the buffer, and the result of translation is
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
735 actually encoded. If a coding system has property
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
736 @code{:encode-translation-table}, that specifies the translation table
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
737 to use, or a list of translation tables to apply in sequence. In
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
738 addition, if the variable @code{standard-translation-table-for-encode}
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
739 is non-@code{nil}, it specifies the translation table to use for
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
740 translating the result.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
741
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
742 @defvar standard-translation-table-for-decode
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
743 This is the default translation table for decoding. If a coding
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
744 systems specifies its own translation tables, the table that is the
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
745 value of this variable, if non-@code{nil}, is applied after them.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
746 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
747
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
748 @defvar standard-translation-table-for-encode
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
749 This is the default translation table for encoding. If a coding
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
750 systems specifies its own translation tables, the table that is the
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
751 value of this variable, if non-@code{nil}, is applied after them.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
752 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
753
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
754 @defun make-translation-table-from-vector vec
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
755 This function returns a translation table made from @var{vec} that is
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
756 an array of 256 elements to map byte values 0 through 255 to
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
757 characters. Elements may be @code{nil} for untranslated bytes. The
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
758 returned table has a translation table for reverse mapping in the
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
759 first extra slot, and the value @code{1} in the second extra slot.
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
760
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
761 This function provides an easy way to make a private coding system
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
762 that maps each byte to a specific character. You can specify the
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
763 returned table and the reverse translation table using the properties
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
764 @code{:decode-translation-table} and @code{:encode-translation-table}
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
765 respectively in the @var{props} argument to
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
766 @code{define-coding-system}.
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
767 @end defun
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
768
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
769 @defun make-translation-table-from-alist alist
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
770 This function is similar to @code{make-translation-table} but returns
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
771 a complex translation table rather than a simple one-to-one mapping.
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
772 Each element of @var{alist} is of the form @code{(@var{from}
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
773 . @var{to})}, where @var{from} and @var{to} are either a character or
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
774 a vector specifying a sequence of characters. If @var{from} is a
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
775 character, that character is translated to @var{to} (i.e.@: to a
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
776 character or a character sequence). If @var{from} is a vector of
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
777 characters, that sequence is translated to @var{to}. The returned
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
778 table has a translation table for reverse mapping in the first extra
100006
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
779 slot, and the maximum length of all the @var{from} character sequences
527cfe29292e (Text Representations, Converting Representations, Character Sets,
Eli Zaretskii <eliz@gnu.org>
parents: 99802
diff changeset
780 in the second extra slot.
99802
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
781 @end defun
512ddf0d1748 (Character Codes, Character Sets)
Eli Zaretskii <eliz@gnu.org>
parents: 99313
diff changeset
782
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
783 @node Coding Systems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
784 @section Coding Systems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
785
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
786 @cindex coding system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
787 When Emacs reads or writes a file, and when Emacs sends text to a
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
788 subprocess or receives text from a subprocess, it normally performs
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
789 character code conversion and end-of-line conversion as specified
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
790 by a particular @dfn{coding system}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
791
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
792 How to define a coding system is an arcane matter, and is not
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
793 documented here.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
794
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
795 @menu
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
796 * Coding System Basics:: Basic concepts.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
797 * Encoding and I/O:: How file I/O functions handle coding systems.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
798 * Lisp and Coding Systems:: Functions to operate on coding system names.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
799 * User-Chosen Coding Systems:: Asking the user to choose a coding system.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
800 * Default Coding Systems:: Controlling the default choices.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
801 * Specifying Coding Systems:: Requesting a particular coding system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
802 for a single file operation.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
803 * Explicit Encoding:: Encoding or decoding text without doing I/O.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
804 * Terminal I/O Encoding:: Use of encoding for terminal I/O.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
805 * MS-DOS File Types:: How DOS "text" and "binary" files
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
806 relate to coding systems.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
807 @end menu
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
808
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
809 @node Coding System Basics
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
810 @subsection Basic Concepts of Coding Systems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
811
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
812 @cindex character code conversion
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
813 @dfn{Character code conversion} involves conversion between the
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
814 internal representation of characters used inside Emacs and some other
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
815 encoding. Emacs supports many different encodings, in that it can
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
816 convert to and from them. For example, it can convert text to or from
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
817 encodings such as Latin 1, Latin 2, Latin 3, Latin 4, Latin 5, and
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
818 several variants of ISO 2022. In some cases, Emacs supports several
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
819 alternative encodings for the same characters; for example, there are
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
820 three coding systems for the Cyrillic (Russian) alphabet: ISO,
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
821 Alternativnyj, and KOI8.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
822
100246
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
823 Every coding system specifies a particular set of character code
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
824 conversions, but the coding system @code{undecided} is special: it
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
825 leaves the choice unspecified, to be chosen heuristically for each
1357cec2ef73 (Coding System Basics): Rewrite @ignore'd paragraph to speak about `undecided'.
Eli Zaretskii <eliz@gnu.org>
parents: 100040
diff changeset
826 file, based on the file's data.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
827
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
828 In general, a coding system doesn't guarantee roundtrip identity:
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
829 decoding a byte sequence using coding system, then encoding the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
830 resulting text in the same coding system, can produce a different byte
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
831 sequence. But some coding systems do guarantee that the byte sequence
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
832 will be the same as what you originally decoded. Here are a few
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
833 examples:
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
834
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
835 @quotation
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
836 iso-8859-1, utf-8, big5, shift_jis, euc-jp
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
837 @end quotation
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
838
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
839 Encoding buffer text and then decoding the result can also fail to
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
840 reproduce the original text. For instance, if you encode a character
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
841 with a coding system which does not support that character, the result
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
842 is unpredictable, and thus decoding it using the same coding system
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
843 may produce a different text. Currently, Emacs can't report errors
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
844 that result from encoding unsupported characters.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
845
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
846 @cindex EOL conversion
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
847 @cindex end-of-line conversion
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
848 @cindex line end conversion
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
849 @dfn{End of line conversion} handles three different conventions
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
850 used on various systems for representing end of line in files. The
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
851 Unix convention, used on GNU and Unix systems, is to use the linefeed
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
852 character (also called newline). The DOS convention, used on
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
853 MS-Windows and MS-DOS systems, is to use a carriage-return and a
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
854 linefeed at the end of a line. The Mac convention is to use just
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
855 carriage-return.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
856
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
857 @cindex base coding system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
858 @cindex variant coding system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
859 @dfn{Base coding systems} such as @code{latin-1} leave the end-of-line
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
860 conversion unspecified, to be chosen based on the data. @dfn{Variant
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
861 coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
862 @code{latin-1-mac} specify the end-of-line conversion explicitly as
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
863 well. Most base coding systems have three corresponding variants whose
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
864 names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
865
101241
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
866 @vindex raw-text@r{ coding system}
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
867 The coding system @code{raw-text} is special in that it prevents
101241
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
868 character code conversion, and causes the buffer visited with this
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
869 coding system to be a unibyte buffer. For historical reasons, you can
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
870 save both unibyte and multibyte text with this coding system. When
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
871 you use @code{raw-text} to encode multibyte text, it does perform one
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
872 character code conversion: it converts eight-bit characters to their
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
873 single-byte external representation. @code{raw-text} does not specify
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
874 the end-of-line conversion, allowing that to be determined as usual by
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
875 the data, and has the usual three variants which specify the
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
876 end-of-line conversion.
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
877
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
878 @vindex no-conversion@r{ coding system}
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
879 @vindex binary@r{ coding system}
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
880 @code{no-conversion} (and its alias @code{binary}) is equivalent to
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
881 @code{raw-text-unix}: it specifies no conversion of either character
4fc8b2cfc2f1 (Coding System Basics): More accurate description of `raw-text'.
Eli Zaretskii <eliz@gnu.org>
parents: 101046
diff changeset
882 codes or end-of-line.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
883
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
884 @vindex emacs-internal@r{ coding system}
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
885 The coding system @code{emacs-internal} specifies that the data is
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
886 represented in the internal Emacs encoding. This is like
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
887 @code{raw-text} in that no code conversion happens, but different in
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
888 that the result is multibyte data.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
889
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
890 @defun coding-system-get coding-system property
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
891 This function returns the specified property of the coding system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
892 @var{coding-system}. Most coding system properties exist for internal
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
893 purposes, but one that you might find useful is @code{:mime-charset}.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
894 That property's value is the name used in MIME for the character coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
895 which this coding system can read and write. Examples:
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
896
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
897 @example
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
898 (coding-system-get 'iso-latin-1 :mime-charset)
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
899 @result{} iso-8859-1
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
900 (coding-system-get 'iso-2022-cn :mime-charset)
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
901 @result{} iso-2022-cn
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
902 (coding-system-get 'cyrillic-koi8 :mime-charset)
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
903 @result{} koi8-r
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
904 @end example
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
905
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
906 The value of the @code{:mime-charset} property is also defined
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
907 as an alias for the coding system.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
908 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
909
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
910 @defun coding-system-aliases coding-system
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
911 This function returns the list of aliases of @var{coding-system}.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
912 @end defun
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
913
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
914 @node Encoding and I/O
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
915 @subsection Encoding and I/O
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
916
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
917 The principal purpose of coding systems is for use in reading and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
918 writing files. The function @code{insert-file-contents} uses
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
919 a coding system for decoding the file data, and @code{write-region}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
920 uses one to encode the buffer contents.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
921
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
922 You can specify the coding system to use either explicitly
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
923 (@pxref{Specifying Coding Systems}), or implicitly using a default
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
924 mechanism (@pxref{Default Coding Systems}). But these methods may not
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
925 completely specify what to do. For example, they may choose a coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
926 system such as @code{undefined} which leaves the character code
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
927 conversion to be determined from the data. In these cases, the I/O
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
928 operation finishes the job of choosing a coding system. Very often
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
929 you will want to find out afterwards which coding system was chosen.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
930
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
931 @defvar buffer-file-coding-system
87276
c9e81d5cb2e7 (Encoding and I/O): Reword to avoid saying
Martin Rudalics <rudalics@gmx.at>
parents: 84116
diff changeset
932 This buffer-local variable records the coding system used for saving the
c9e81d5cb2e7 (Encoding and I/O): Reword to avoid saying
Martin Rudalics <rudalics@gmx.at>
parents: 84116
diff changeset
933 buffer and for writing part of the buffer with @code{write-region}. If
c9e81d5cb2e7 (Encoding and I/O): Reword to avoid saying
Martin Rudalics <rudalics@gmx.at>
parents: 84116
diff changeset
934 the text to be written cannot be safely encoded using the coding system
c9e81d5cb2e7 (Encoding and I/O): Reword to avoid saying
Martin Rudalics <rudalics@gmx.at>
parents: 84116
diff changeset
935 specified by this variable, these operations select an alternative
c9e81d5cb2e7 (Encoding and I/O): Reword to avoid saying
Martin Rudalics <rudalics@gmx.at>
parents: 84116
diff changeset
936 encoding by calling the function @code{select-safe-coding-system}
c9e81d5cb2e7 (Encoding and I/O): Reword to avoid saying
Martin Rudalics <rudalics@gmx.at>
parents: 84116
diff changeset
937 (@pxref{User-Chosen Coding Systems}). If selecting a different encoding
c9e81d5cb2e7 (Encoding and I/O): Reword to avoid saying
Martin Rudalics <rudalics@gmx.at>
parents: 84116
diff changeset
938 requires to ask the user to specify a coding system,
c9e81d5cb2e7 (Encoding and I/O): Reword to avoid saying
Martin Rudalics <rudalics@gmx.at>
parents: 84116
diff changeset
939 @code{buffer-file-coding-system} is updated to the newly selected coding
c9e81d5cb2e7 (Encoding and I/O): Reword to avoid saying
Martin Rudalics <rudalics@gmx.at>
parents: 84116
diff changeset
940 system.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
941
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
942 @code{buffer-file-coding-system} does @emph{not} affect sending text
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
943 to a subprocess.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
944 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
945
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
946 @defvar save-buffer-coding-system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
947 This variable specifies the coding system for saving the buffer (by
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
948 overriding @code{buffer-file-coding-system}). Note that it is not used
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
949 for @code{write-region}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
950
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
951 When a command to save the buffer starts out to use
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
952 @code{buffer-file-coding-system} (or @code{save-buffer-coding-system}),
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
953 and that coding system cannot handle
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
954 the actual text in the buffer, the command asks the user to choose
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
955 another coding system (by calling @code{select-safe-coding-system}).
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
956 After that happens, the command also updates
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
957 @code{buffer-file-coding-system} to represent the coding system that
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
958 the user specified.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
959 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
960
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
961 @defvar last-coding-system-used
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
962 I/O operations for files and subprocesses set this variable to the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
963 coding system name that was used. The explicit encoding and decoding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
964 functions (@pxref{Explicit Encoding}) set it too.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
965
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
966 @strong{Warning:} Since receiving subprocess output sets this variable,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
967 it can change whenever Emacs waits; therefore, you should copy the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
968 value shortly after the function call that stores the value you are
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
969 interested in.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
970 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
971
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
972 The variable @code{selection-coding-system} specifies how to encode
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
973 selections for the window system. @xref{Window System Selections}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
974
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
975 @defvar file-name-coding-system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
976 The variable @code{file-name-coding-system} specifies the coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
977 system to use for encoding file names. Emacs encodes file names using
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
978 that coding system for all file operations. If
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
979 @code{file-name-coding-system} is @code{nil}, Emacs uses a default
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
980 coding system determined by the selected language environment. In the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
981 default language environment, any non-@acronym{ASCII} characters in
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
982 file names are not encoded specially; they appear in the file system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
983 using the internal Emacs representation.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
984 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
985
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
986 @strong{Warning:} if you change @code{file-name-coding-system} (or
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
987 the language environment) in the middle of an Emacs session, problems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
988 can result if you have already visited files whose names were encoded
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
989 using the earlier coding system and are handled differently under the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
990 new coding system. If you try to save one of these buffers under the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
991 visited file name, saving may use the wrong file name, or it may get
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
992 an error. If such a problem happens, use @kbd{C-x C-w} to specify a
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
993 new file name for that buffer.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
994
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
995 @node Lisp and Coding Systems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
996 @subsection Coding Systems in Lisp
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
997
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
998 Here are the Lisp facilities for working with coding systems:
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
999
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1000 @defun coding-system-list &optional base-only
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1001 This function returns a list of all coding system names (symbols). If
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1002 @var{base-only} is non-@code{nil}, the value includes only the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1003 base coding systems. Otherwise, it includes alias and variant coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1004 systems as well.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1005 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1006
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1007 @defun coding-system-p object
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1008 This function returns @code{t} if @var{object} is a coding system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1009 name or @code{nil}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1010 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1011
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1012 @defun check-coding-system coding-system
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1013 This function checks the validity of @var{coding-system}. If that is
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1014 valid, it returns @var{coding-system}. If @var{coding-system} is
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1015 @code{nil}, the function return @code{nil}. For any other values, it
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1016 signals an error whose @code{error-symbol} is @code{coding-system-error}
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1017 (@pxref{Signaling Errors, signal}).
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1018 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1019
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1020 @defun coding-system-eol-type coding-system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1021 This function returns the type of end-of-line (a.k.a.@: @dfn{eol})
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1022 conversion used by @var{coding-system}. If @var{coding-system}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1023 specifies a certain eol conversion, the return value is an integer 0,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1024 1, or 2, standing for @code{unix}, @code{dos}, and @code{mac},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1025 respectively. If @var{coding-system} doesn't specify eol conversion
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1026 explicitly, the return value is a vector of coding systems, each one
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1027 with one of the possible eol conversion types, like this:
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1028
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1029 @lisp
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1030 (coding-system-eol-type 'latin-1)
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1031 @result{} [latin-1-unix latin-1-dos latin-1-mac]
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1032 @end lisp
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1033
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1034 @noindent
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1035 If this function returns a vector, Emacs will decide, as part of the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1036 text encoding or decoding process, what eol conversion to use. For
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1037 decoding, the end-of-line format of the text is auto-detected, and the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1038 eol conversion is set to match it (e.g., DOS-style CRLF format will
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1039 imply @code{dos} eol conversion). For encoding, the eol conversion is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1040 taken from the appropriate default coding system (e.g.,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1041 @code{default-buffer-file-coding-system} for
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1042 @code{buffer-file-coding-system}), or from the default eol conversion
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1043 appropriate for the underlying platform.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1044 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1045
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1046 @defun coding-system-change-eol-conversion coding-system eol-type
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1047 This function returns a coding system which is like @var{coding-system}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1048 except for its eol conversion, which is specified by @code{eol-type}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1049 @var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1050 @code{nil}. If it is @code{nil}, the returned coding system determines
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1051 the end-of-line conversion from the data.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1052
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1053 @var{eol-type} may also be 0, 1 or 2, standing for @code{unix},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1054 @code{dos} and @code{mac}, respectively.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1055 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1056
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1057 @defun coding-system-change-text-conversion eol-coding text-coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1058 This function returns a coding system which uses the end-of-line
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1059 conversion of @var{eol-coding}, and the text conversion of
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1060 @var{text-coding}. If @var{text-coding} is @code{nil}, it returns
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1061 @code{undecided}, or one of its variants according to @var{eol-coding}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1062 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1063
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1064 @defun find-coding-systems-region from to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1065 This function returns a list of coding systems that could be used to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1066 encode a text between @var{from} and @var{to}. All coding systems in
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1067 the list can safely encode any multibyte characters in that portion of
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1068 the text.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1069
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1070 If the text contains no multibyte characters, the function returns the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1071 list @code{(undecided)}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1072 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1073
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1074 @defun find-coding-systems-string string
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1075 This function returns a list of coding systems that could be used to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1076 encode the text of @var{string}. All coding systems in the list can
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1077 safely encode any multibyte characters in @var{string}. If the text
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1078 contains no multibyte characters, this returns the list
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1079 @code{(undecided)}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1080 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1081
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1082 @defun find-coding-systems-for-charsets charsets
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1083 This function returns a list of coding systems that could be used to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1084 encode all the character sets in the list @var{charsets}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1085 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1086
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1087 @defun check-coding-systems-region start end coding-system-list
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1088 This function checks whether coding systems in the list
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1089 @code{coding-system-list} can encode all the characters in the region
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1090 between @var{start} and @var{end}. If all of the coding systems in
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1091 the list can encode the specified text, the function returns
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1092 @code{nil}. If some coding systems cannot encode some of the
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1093 characters, the value is an alist, each element of which has the form
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1094 @code{(@var{coding-system1} @var{pos1} @var{pos2} @dots{})}, meaning
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1095 that @var{coding-system1} cannot encode characters at buffer positions
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1096 @var{pos1}, @var{pos2}, @enddots{}.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1097
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1098 @var{start} may be a string, in which case @var{end} is ignored and
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1099 the returned value references string indices instead of buffer
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1100 positions.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1101 @end defun
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1102
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1103 @defun detect-coding-region start end &optional highest
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1104 This function chooses a plausible coding system for decoding the text
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1105 from @var{start} to @var{end}. This text should be a byte sequence,
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1106 i.e.@: unibyte text or multibyte text with only @acronym{ASCII} and
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1107 eight-bit characters (@pxref{Explicit Encoding}).
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1108
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1109 Normally this function returns a list of coding systems that could
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1110 handle decoding the text that was scanned. They are listed in order of
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1111 decreasing priority. But if @var{highest} is non-@code{nil}, then the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1112 return value is just one coding system, the one that is highest in
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1113 priority.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1114
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1115 If the region contains only @acronym{ASCII} characters except for such
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1116 ISO-2022 control characters ISO-2022 as @code{ESC}, the value is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1117 @code{undecided} or @code{(undecided)}, or a variant specifying
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1118 end-of-line conversion, if that can be deduced from the text.
101044
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1119
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1120 If the region contains null bytes, the value is @code{no-conversion},
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1121 even if the region contains text encoded in some coding system.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1122 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1123
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1124 @defun detect-coding-string string &optional highest
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1125 This function is like @code{detect-coding-region} except that it
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1126 operates on the contents of @var{string} instead of bytes in the buffer.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1127 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1128
101044
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1129 @defvar inhibit-null-byte-detection
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1130 If this variable has a non-@code{nil} value, null bytes are ignored
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1131 when detecting the encoding of a region or a string. This allows to
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1132 correctly detect the encoding of text that contains null bytes, such
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1133 as Info files with Index nodes.
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1134 @end defvar
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1135
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1136 @defvar inhibit-iso-escape-detection
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1137 If this variable has a non-@code{nil} value, ISO-2022 escape sequences
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1138 are ignored when detecting the encoding of a region or a string. The
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1139 result is that no text is ever detected as encoded in some ISO-2022
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1140 encoding, and all escape sequences become visible in a buffer.
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1141 @strong{Warning:} @emph{Use this variable with extreme caution,
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1142 because many files in the Emacs distribution use ISO-2022 encoding.}
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1143 @end defvar
6f865c33fded (Lisp and Coding Systems): Document inhibit-null-byte-detection and
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
1144
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1145 @defun coding-system-charset-list coding-system
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1146 This function returns the list of character sets (@pxref{Character
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1147 Sets}) supported by @var{coding-system}. Some coding systems that
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1148 support too many character sets to list them all yield special values:
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1149 @itemize @bullet
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1150 @item
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1151 If @var{coding-system} supports all the ISO-2022 charsets, the value
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1152 is @code{iso-2022}.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1153 @item
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1154 If @var{coding-system} supports all Emacs characters, the value is
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1155 @code{(emacs)}.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1156 @item
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1157 If @var{coding-system} supports all emacs-mule characters, the value
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1158 is @code{emacs-mule}.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1159 @item
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1160 If @var{coding-system} supports all Unicode characters, the value is
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1161 @code{(unicode)}.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1162 @end itemize
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1163 @end defun
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1164
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1165 @xref{Coding systems for a subprocess,, Process Information}, in
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1166 particular the description of the functions
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1167 @code{process-coding-system} and @code{set-process-coding-system}, for
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1168 how to examine or set the coding systems used for I/O to a subprocess.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1169
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1170 @node User-Chosen Coding Systems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1171 @subsection User-Chosen Coding Systems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1172
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1173 @cindex select safe coding system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1174 @defun select-safe-coding-system from to &optional default-coding-system accept-default-p file
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1175 This function selects a coding system for encoding specified text,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1176 asking the user to choose if necessary. Normally the specified text
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1177 is the text in the current buffer between @var{from} and @var{to}. If
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1178 @var{from} is a string, the string specifies the text to encode, and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1179 @var{to} is ignored.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1180
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1181 If @var{default-coding-system} is non-@code{nil}, that is the first
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1182 coding system to try; if that can handle the text,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1183 @code{select-safe-coding-system} returns that coding system. It can
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1184 also be a list of coding systems; then the function tries each of them
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1185 one by one. After trying all of them, it next tries the current
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1186 buffer's value of @code{buffer-file-coding-system} (if it is not
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1187 @code{undecided}), then the value of
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1188 @code{default-buffer-file-coding-system} and finally the user's most
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1189 preferred coding system, which the user can set using the command
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1190 @code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1191 Coding Systems, emacs, The GNU Emacs Manual}).
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1192
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1193 If one of those coding systems can safely encode all the specified
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1194 text, @code{select-safe-coding-system} chooses it and returns it.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1195 Otherwise, it asks the user to choose from a list of coding systems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1196 which can encode all the text, and returns the user's choice.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1197
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1198 @var{default-coding-system} can also be a list whose first element is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1199 t and whose other elements are coding systems. Then, if no coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1200 system in the list can handle the text, @code{select-safe-coding-system}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1201 queries the user immediately, without trying any of the three
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1202 alternatives described above.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1203
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1204 The optional argument @var{accept-default-p}, if non-@code{nil},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1205 should be a function to determine whether a coding system selected
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1206 without user interaction is acceptable. @code{select-safe-coding-system}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1207 calls this function with one argument, the base coding system of the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1208 selected coding system. If @var{accept-default-p} returns @code{nil},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1209 @code{select-safe-coding-system} rejects the silently selected coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1210 system, and asks the user to select a coding system from a list of
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1211 possible candidates.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1212
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1213 @vindex select-safe-coding-system-accept-default-p
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1214 If the variable @code{select-safe-coding-system-accept-default-p} is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1215 non-@code{nil}, its value overrides the value of
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1216 @var{accept-default-p}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1217
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1218 As a final step, before returning the chosen coding system,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1219 @code{select-safe-coding-system} checks whether that coding system is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1220 consistent with what would be selected if the contents of the region
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1221 were read from a file. (If not, this could lead to data corruption in
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1222 a file subsequently re-visited and edited.) Normally,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1223 @code{select-safe-coding-system} uses @code{buffer-file-name} as the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1224 file for this purpose, but if @var{file} is non-@code{nil}, it uses
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1225 that file instead (this can be relevant for @code{write-region} and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1226 similar functions). If it detects an apparent inconsistency,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1227 @code{select-safe-coding-system} queries the user before selecting the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1228 coding system.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1229 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1230
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1231 Here are two functions you can use to let the user specify a coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1232 system, with completion. @xref{Completion}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1233
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1234 @defun read-coding-system prompt &optional default
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1235 This function reads a coding system using the minibuffer, prompting with
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1236 string @var{prompt}, and returns the coding system name as a symbol. If
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1237 the user enters null input, @var{default} specifies which coding system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1238 to return. It should be a symbol or a string.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1239 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1240
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1241 @defun read-non-nil-coding-system prompt
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1242 This function reads a coding system using the minibuffer, prompting with
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1243 string @var{prompt}, and returns the coding system name as a symbol. If
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1244 the user tries to enter null input, it asks the user to try again.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1245 @xref{Coding Systems}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1246 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1247
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1248 @node Default Coding Systems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1249 @subsection Default Coding Systems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1250
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1251 This section describes variables that specify the default coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1252 system for certain files or when running certain subprograms, and the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1253 function that I/O operations use to access them.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1254
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1255 The idea of these variables is that you set them once and for all to the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1256 defaults you want, and then do not change them again. To specify a
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1257 particular coding system for a particular operation in a Lisp program,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1258 don't change these variables; instead, override them using
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1259 @code{coding-system-for-read} and @code{coding-system-for-write}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1260 (@pxref{Specifying Coding Systems}).
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1261
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1262 @defvar auto-coding-regexp-alist
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1263 This variable is an alist of text patterns and corresponding coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1264 systems. Each element has the form @code{(@var{regexp}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1265 . @var{coding-system})}; a file whose first few kilobytes match
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1266 @var{regexp} is decoded with @var{coding-system} when its contents are
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1267 read into a buffer. The settings in this alist take priority over
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1268 @code{coding:} tags in the files and the contents of
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1269 @code{file-coding-system-alist} (see below). The default value is set
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1270 so that Emacs automatically recognizes mail files in Babyl format and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1271 reads them with no code conversions.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1272 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1273
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1274 @defvar file-coding-system-alist
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1275 This variable is an alist that specifies the coding systems to use for
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1276 reading and writing particular files. Each element has the form
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1277 @code{(@var{pattern} . @var{coding})}, where @var{pattern} is a regular
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1278 expression that matches certain file names. The element applies to file
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1279 names that match @var{pattern}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1280
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1281 The @sc{cdr} of the element, @var{coding}, should be either a coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1282 system, a cons cell containing two coding systems, or a function name (a
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1283 symbol with a function definition). If @var{coding} is a coding system,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1284 that coding system is used for both reading the file and writing it. If
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1285 @var{coding} is a cons cell containing two coding systems, its @sc{car}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1286 specifies the coding system for decoding, and its @sc{cdr} specifies the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1287 coding system for encoding.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1288
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1289 If @var{coding} is a function name, the function should take one
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1290 argument, a list of all arguments passed to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1291 @code{find-operation-coding-system}. It must return a coding system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1292 or a cons cell containing two coding systems. This value has the same
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1293 meaning as described above.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1294
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1295 If @var{coding} (or what returned by the above function) is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1296 @code{undecided}, the normal code-detection is performed.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1297 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1298
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1299 @defvar process-coding-system-alist
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1300 This variable is an alist specifying which coding systems to use for a
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1301 subprocess, depending on which program is running in the subprocess. It
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1302 works like @code{file-coding-system-alist}, except that @var{pattern} is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1303 matched against the program name used to start the subprocess. The coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1304 system or systems specified in this alist are used to initialize the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1305 coding systems used for I/O to the subprocess, but you can specify
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1306 other coding systems later using @code{set-process-coding-system}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1307 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1308
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1309 @strong{Warning:} Coding systems such as @code{undecided}, which
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1310 determine the coding system from the data, do not work entirely reliably
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1311 with asynchronous subprocess output. This is because Emacs handles
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1312 asynchronous subprocess output in batches, as it arrives. If the coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1313 system leaves the character code conversion unspecified, or leaves the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1314 end-of-line conversion unspecified, Emacs must try to detect the proper
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1315 conversion from one batch at a time, and this does not always work.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1316
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1317 Therefore, with an asynchronous subprocess, if at all possible, use a
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1318 coding system which determines both the character code conversion and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1319 the end of line conversion---that is, one like @code{latin-1-unix},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1320 rather than @code{undecided} or @code{latin-1}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1321
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1322 @defvar network-coding-system-alist
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1323 This variable is an alist that specifies the coding system to use for
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1324 network streams. It works much like @code{file-coding-system-alist},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1325 with the difference that the @var{pattern} in an element may be either a
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1326 port number or a regular expression. If it is a regular expression, it
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1327 is matched against the network service name used to open the network
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1328 stream.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1329 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1330
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1331 @defvar default-process-coding-system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1332 This variable specifies the coding systems to use for subprocess (and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1333 network stream) input and output, when nothing else specifies what to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1334 do.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1335
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1336 The value should be a cons cell of the form @code{(@var{input-coding}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1337 . @var{output-coding})}. Here @var{input-coding} applies to input from
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1338 the subprocess, and @var{output-coding} applies to output to it.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1339 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1340
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1341 @defvar auto-coding-functions
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1342 This variable holds a list of functions that try to determine a
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1343 coding system for a file based on its undecoded contents.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1344
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1345 Each function in this list should be written to look at text in the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1346 current buffer, but should not modify it in any way. The buffer will
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1347 contain undecoded text of parts of the file. Each function should
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1348 take one argument, @var{size}, which tells it how many characters to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1349 look at, starting from point. If the function succeeds in determining
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1350 a coding system for the file, it should return that coding system.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1351 Otherwise, it should return @code{nil}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1352
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1353 If a file has a @samp{coding:} tag, that takes precedence, so these
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1354 functions won't be called.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1355 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1356
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1357 @defun find-operation-coding-system operation &rest arguments
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1358 This function returns the coding system to use (by default) for
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1359 performing @var{operation} with @var{arguments}. The value has this
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1360 form:
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1361
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1362 @example
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1363 (@var{decoding-system} . @var{encoding-system})
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1364 @end example
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1365
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1366 The first element, @var{decoding-system}, is the coding system to use
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1367 for decoding (in case @var{operation} does decoding), and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1368 @var{encoding-system} is the coding system for encoding (in case
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1369 @var{operation} does encoding).
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1370
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1371 The argument @var{operation} is a symbol, one of @code{write-region},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1372 @code{start-process}, @code{call-process}, @code{call-process-region},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1373 @code{insert-file-contents}, or @code{open-network-stream}. These are
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1374 the names of the Emacs I/O primitives that can do character code and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1375 eol conversion.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1376
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1377 The remaining arguments should be the same arguments that might be given
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1378 to the corresponding I/O primitive. Depending on the primitive, one
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1379 of those arguments is selected as the @dfn{target}. For example, if
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1380 @var{operation} does file I/O, whichever argument specifies the file
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1381 name is the target. For subprocess primitives, the process name is the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1382 target. For @code{open-network-stream}, the target is the service name
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1383 or port number.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1384
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1385 Depending on @var{operation}, this function looks up the target in
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1386 @code{file-coding-system-alist}, @code{process-coding-system-alist},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1387 or @code{network-coding-system-alist}. If the target is found in the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1388 alist, @code{find-operation-coding-system} returns its association in
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1389 the alist; otherwise it returns @code{nil}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1390
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1391 If @var{operation} is @code{insert-file-contents}, the argument
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1392 corresponding to the target may be a cons cell of the form
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1393 @code{(@var{filename} . @var{buffer})}). In that case, @var{filename}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1394 is a file name to look up in @code{file-coding-system-alist}, and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1395 @var{buffer} is a buffer that contains the file's contents (not yet
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1396 decoded). If @code{file-coding-system-alist} specifies a function to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1397 call for this file, and that function needs to examine the file's
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1398 contents (as it usually does), it should examine the contents of
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1399 @var{buffer} instead of reading the file.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1400 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1401
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1402 @node Specifying Coding Systems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1403 @subsection Specifying a Coding System for One Operation
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1404
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1405 You can specify the coding system for a specific operation by binding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1406 the variables @code{coding-system-for-read} and/or
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1407 @code{coding-system-for-write}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1408
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1409 @defvar coding-system-for-read
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1410 If this variable is non-@code{nil}, it specifies the coding system to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1411 use for reading a file, or for input from a synchronous subprocess.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1412
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1413 It also applies to any asynchronous subprocess or network stream, but in
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1414 a different way: the value of @code{coding-system-for-read} when you
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1415 start the subprocess or open the network stream specifies the input
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1416 decoding method for that subprocess or network stream. It remains in
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1417 use for that subprocess or network stream unless and until overridden.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1418
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1419 The right way to use this variable is to bind it with @code{let} for a
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1420 specific I/O operation. Its global value is normally @code{nil}, and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1421 you should not globally set it to any other value. Here is an example
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1422 of the right way to use the variable:
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1423
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1424 @example
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1425 ;; @r{Read the file with no character code conversion.}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1426 ;; @r{Assume @acronym{crlf} represents end-of-line.}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1427 (let ((coding-system-for-read 'emacs-mule-dos))
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1428 (insert-file-contents filename))
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1429 @end example
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1430
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1431 When its value is non-@code{nil}, this variable takes precedence over
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1432 all other methods of specifying a coding system to use for input,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1433 including @code{file-coding-system-alist},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1434 @code{process-coding-system-alist} and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1435 @code{network-coding-system-alist}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1436 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1437
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1438 @defvar coding-system-for-write
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1439 This works much like @code{coding-system-for-read}, except that it
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1440 applies to output rather than input. It affects writing to files,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1441 as well as sending output to subprocesses and net connections.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1442
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1443 When a single operation does both input and output, as do
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1444 @code{call-process-region} and @code{start-process}, both
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1445 @code{coding-system-for-read} and @code{coding-system-for-write}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1446 affect it.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1447 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1448
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1449 @defvar inhibit-eol-conversion
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1450 When this variable is non-@code{nil}, no end-of-line conversion is done,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1451 no matter which coding system is specified. This applies to all the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1452 Emacs I/O and subprocess primitives, and to the explicit encoding and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1453 decoding functions (@pxref{Explicit Encoding}).
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1454 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1455
100040
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1456 @cindex priority order of coding systems
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1457 @cindex coding systems, priority
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1458 Sometimes, you need to prefer several coding systems for some
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1459 operation, rather than fix a single one. Emacs lets you specify a
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1460 priority order for using coding systems. This ordering affects the
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1461 sorting of lists of coding sysems returned by functions such as
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1462 @code{find-coding-systems-region} (@pxref{Lisp and Coding Systems}).
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1463
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1464 @defun coding-system-priority-list &optional highestp
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1465 This function returns the list of coding systems in the order of their
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1466 current priorities. Optional argument @var{highestp}, if
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1467 non-@code{nil}, means return only the highest priority coding system.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1468 @end defun
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1469
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1470 @defun set-coding-system-priority &rest coding-systems
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1471 This function puts @var{coding-systems} at the beginning of the
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1472 priority list for coding systems, thus making their priority higher
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1473 than all the rest.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1474 @end defun
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1475
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1476 @defmac with-coding-priority coding-systems &rest body@dots{}
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1477 This macro execute @var{body}, like @code{progn} does
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1478 (@pxref{Sequencing, progn}), with @var{coding-systems} at the front of
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1479 the priority list for coding systems. @var{coding-systems} should be
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1480 a list of coding systems to prefer during execution of @var{body}.
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1481 @end defmac
60d9e250ee84 (Character Properties): New Section.
Eli Zaretskii <eliz@gnu.org>
parents: 100025
diff changeset
1482
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1483 @node Explicit Encoding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1484 @subsection Explicit Encoding and Decoding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1485 @cindex encoding in coding systems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1486 @cindex decoding in coding systems
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1487
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1488 All the operations that transfer text in and out of Emacs have the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1489 ability to use a coding system to encode or decode the text.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1490 You can also explicitly encode and decode text using the functions
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1491 in this section.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1492
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1493 The result of encoding, and the input to decoding, are not ordinary
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1494 text. They logically consist of a series of byte values; that is, a
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1495 series of @acronym{ASCII} and eight-bit characters. In unibyte
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1496 buffers and strings, these characters have codes in the range 0
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1497 through 255. In a multibyte buffer or string, eight-bit characters
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1498 have character codes higher than 255 (@pxref{Text Representations}),
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1499 but Emacs transparently converts them to their single-byte values when
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1500 you encode or decode such text.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1501
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1502 The usual way to read a file into a buffer as a sequence of bytes, so
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1503 you can decode the contents explicitly, is with
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1504 @code{insert-file-contents-literally} (@pxref{Reading from Files});
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1505 alternatively, specify a non-@code{nil} @var{rawfile} argument when
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1506 visiting a file with @code{find-file-noselect}. These methods result in
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1507 a unibyte buffer.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1508
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1509 The usual way to use the byte sequence that results from explicitly
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1510 encoding text is to copy it to a file or process---for example, to write
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1511 it with @code{write-region} (@pxref{Writing to Files}), and suppress
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1512 encoding by binding @code{coding-system-for-write} to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1513 @code{no-conversion}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1514
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1515 Here are the functions to perform explicit encoding or decoding. The
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1516 encoding functions produce sequences of bytes; the decoding functions
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1517 are meant to operate on sequences of bytes. All of these functions
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1518 discard text properties. They also set @code{last-coding-system-used}
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1519 to the precise coding system they used.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1520
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1521 @deffn Command encode-coding-region start end coding-system &optional destination
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1522 This command encodes the text from @var{start} to @var{end} according
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1523 to coding system @var{coding-system}. Normally, the encoded text
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1524 replaces the original text in the buffer, but the optional argument
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1525 @var{destination} can change that. If @var{destination} is a buffer,
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1526 the encoded text is inserted in that buffer after point (point does
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1527 not move); if it is @code{t}, the command returns the encoded text as
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1528 a unibyte string without inserting it.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1529
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1530 If encoded text is inserted in some buffer, this command returns the
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1531 length of the encoded text.
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1532
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1533 The result of encoding is logically a sequence of bytes, but the
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1534 buffer remains multibyte if it was multibyte before, and any 8-bit
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1535 bytes are converted to their multibyte representation (@pxref{Text
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1536 Representations}).
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1537 @end deffn
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1538
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1539 @defun encode-coding-string string coding-system &optional nocopy buffer
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1540 This function encodes the text in @var{string} according to coding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1541 system @var{coding-system}. It returns a new string containing the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1542 encoded text, except when @var{nocopy} is non-@code{nil}, in which
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1543 case the function may return @var{string} itself if the encoding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1544 operation is trivial. The result of encoding is a unibyte string.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1545 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1546
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1547 @deffn Command decode-coding-region start end coding-system destination
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1548 This command decodes the text from @var{start} to @var{end} according
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1549 to coding system @var{coding-system}. To make explicit decoding
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1550 useful, the text before decoding ought to be a sequence of byte
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1551 values, but both multibyte and unibyte buffers are acceptable (in the
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1552 multibyte case, the raw byte values should be represented as eight-bit
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1553 characters). Normally, the decoded text replaces the original text in
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1554 the buffer, but the optional argument @var{destination} can change
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1555 that. If @var{destination} is a buffer, the decoded text is inserted
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1556 in that buffer after point (point does not move); if it is @code{t},
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1557 the command returns the decoded text as a multibyte string without
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1558 inserting it.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1559
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1560 If decoded text is inserted in some buffer, this command returns the
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1561 length of the decoded text.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1562 @end deffn
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1563
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1564 @defun decode-coding-string string coding-system &optional nocopy buffer
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1565 This function decodes the text in @var{string} according to
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1566 @var{coding-system}. It returns a new string containing the decoded
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1567 text, except when @var{nocopy} is non-@code{nil}, in which case the
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1568 function may return @var{string} itself if the decoding operation is
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1569 trivial. To make explicit decoding useful, the contents of
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1570 @var{string} ought to be a unibyte string with a sequence of byte
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1571 values, but a multibyte string is also acceptable (assuming it
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1572 contains 8-bit bytes in their multibyte form).
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1573
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1574 If optional argument @var{buffer} specifies a buffer, the decoded text
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1575 is inserted in that buffer after point (point does not move). In this
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1576 case, the return value is the length of the decoded text.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1577 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1578
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1579 @defun decode-coding-inserted-region from to filename &optional visit beg end replace
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1580 This function decodes the text from @var{from} to @var{to} as if
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1581 it were being read from file @var{filename} using @code{insert-file-contents}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1582 using the rest of the arguments provided.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1583
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1584 The normal way to use this function is after reading text from a file
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1585 without decoding, if you decide you would rather have decoded it.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1586 Instead of deleting the text and reading it again, this time with
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1587 decoding, you can call this function.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1588 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1589
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1590 @node Terminal I/O Encoding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1591 @subsection Terminal I/O Encoding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1592
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1593 Emacs can decode keyboard input using a coding system, and encode
100025
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1594 terminal output. This is useful for terminals that transmit or
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1595 display text using a particular encoding such as Latin-1. Emacs does
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1596 not set @code{last-coding-system-used} for encoding or decoding of
4015958e8d9d (Explicit Encoding): Update for Emacs 23.
Eli Zaretskii <eliz@gnu.org>
parents: 100006
diff changeset
1597 terminal I/O.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1598
101264
e053f08d03ae (Terminal I/O Encoding): `keyboard-coding-system' and
Eli Zaretskii <eliz@gnu.org>
parents: 101241
diff changeset
1599 @defun keyboard-coding-system &optional terminal
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1600 This function returns the coding system that is in use for decoding
101264
e053f08d03ae (Terminal I/O Encoding): `keyboard-coding-system' and
Eli Zaretskii <eliz@gnu.org>
parents: 101241
diff changeset
1601 keyboard input from @var{terminal}---or @code{nil} if no coding system
e053f08d03ae (Terminal I/O Encoding): `keyboard-coding-system' and
Eli Zaretskii <eliz@gnu.org>
parents: 101241
diff changeset
1602 is to be used for that terminal. If @var{terminal} is omitted or
e053f08d03ae (Terminal I/O Encoding): `keyboard-coding-system' and
Eli Zaretskii <eliz@gnu.org>
parents: 101241
diff changeset
1603 @code{nil}, it means the selected frame's terminal. @xref{Multiple
e053f08d03ae (Terminal I/O Encoding): `keyboard-coding-system' and
Eli Zaretskii <eliz@gnu.org>
parents: 101241
diff changeset
1604 Terminals}.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1605 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1606
101264
e053f08d03ae (Terminal I/O Encoding): `keyboard-coding-system' and
Eli Zaretskii <eliz@gnu.org>
parents: 101241
diff changeset
1607 @deffn Command set-keyboard-coding-system coding-system &optional terminal
e053f08d03ae (Terminal I/O Encoding): `keyboard-coding-system' and
Eli Zaretskii <eliz@gnu.org>
parents: 101241
diff changeset
1608 This command specifies @var{coding-system} as the coding system to use
e053f08d03ae (Terminal I/O Encoding): `keyboard-coding-system' and
Eli Zaretskii <eliz@gnu.org>
parents: 101241
diff changeset
1609 for decoding keyboard input from @var{terminal}. If
e053f08d03ae (Terminal I/O Encoding): `keyboard-coding-system' and
Eli Zaretskii <eliz@gnu.org>
parents: 101241
diff changeset
1610 @var{coding-system} is @code{nil}, that means do not decode keyboard
e053f08d03ae (Terminal I/O Encoding): `keyboard-coding-system' and
Eli Zaretskii <eliz@gnu.org>
parents: 101241
diff changeset
1611 input. If @var{terminal} is a frame, it means that frame's terminal;
e053f08d03ae (Terminal I/O Encoding): `keyboard-coding-system' and
Eli Zaretskii <eliz@gnu.org>
parents: 101241
diff changeset
1612 if it is @code{nil}, that means the currently selected frame's
e053f08d03ae (Terminal I/O Encoding): `keyboard-coding-system' and
Eli Zaretskii <eliz@gnu.org>
parents: 101241
diff changeset
1613 terminal. @xref{Multiple Terminals}.
84090
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1614 @end deffn
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1615
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1616 @defun terminal-coding-system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1617 This function returns the coding system that is in use for encoding
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1618 terminal output---or @code{nil} for no encoding.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1619 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1620
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1621 @deffn Command set-terminal-coding-system coding-system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1622 This command specifies @var{coding-system} as the coding system to use
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1623 for encoding terminal output. If @var{coding-system} is @code{nil},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1624 that means do not encode terminal output.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1625 @end deffn
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1626
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1627 @node MS-DOS File Types
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1628 @subsection MS-DOS File Types
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1629 @cindex DOS file types
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1630 @cindex MS-DOS file types
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1631 @cindex Windows file types
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1632 @cindex file types on MS-DOS and Windows
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1633 @cindex text files and binary files
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1634 @cindex binary files and text files
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1635
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1636 On MS-DOS and Microsoft Windows, Emacs guesses the appropriate
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1637 end-of-line conversion for a file by looking at the file's name. This
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1638 feature classifies files as @dfn{text files} and @dfn{binary files}. By
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1639 ``binary file'' we mean a file of literal byte values that are not
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1640 necessarily meant to be characters; Emacs does no end-of-line conversion
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1641 and no character code conversion for them. On the other hand, the bytes
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1642 in a text file are intended to represent characters; when you create a
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1643 new file whose name implies that it is a text file, Emacs uses DOS
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1644 end-of-line conversion.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1645
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1646 @defvar buffer-file-type
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1647 This variable, automatically buffer-local in each buffer, records the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1648 file type of the buffer's visited file. When a buffer does not specify
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1649 a coding system with @code{buffer-file-coding-system}, this variable is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1650 used to determine which coding system to use when writing the contents
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1651 of the buffer. It should be @code{nil} for text, @code{t} for binary.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1652 If it is @code{t}, the coding system is @code{no-conversion}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1653 Otherwise, @code{undecided-dos} is used.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1654
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1655 Normally this variable is set by visiting a file; it is set to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1656 @code{nil} if the file was visited without any actual conversion.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1657 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1658
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1659 @defopt file-name-buffer-file-type-alist
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1660 This variable holds an alist for recognizing text and binary files.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1661 Each element has the form (@var{regexp} . @var{type}), where
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1662 @var{regexp} is matched against the file name, and @var{type} may be
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1663 @code{nil} for text, @code{t} for binary, or a function to call to
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1664 compute which. If it is a function, then it is called with a single
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1665 argument (the file name) and should return @code{t} or @code{nil}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1666
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1667 When running on MS-DOS or MS-Windows, Emacs checks this alist to decide
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1668 which coding system to use when reading a file. For a text file,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1669 @code{undecided-dos} is used. For a binary file, @code{no-conversion}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1670 is used.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1671
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1672 If no element in this alist matches a given file name, then
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1673 @code{default-buffer-file-type} says how to treat the file.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1674 @end defopt
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1675
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1676 @defopt default-buffer-file-type
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1677 This variable says how to handle files for which
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1678 @code{file-name-buffer-file-type-alist} says nothing about the type.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1679
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1680 If this variable is non-@code{nil}, then these files are treated as
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1681 binary: the coding system @code{no-conversion} is used. Otherwise,
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1682 nothing special is done for them---the coding system is deduced solely
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1683 from the file contents, in the usual Emacs fashion.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1684 @end defopt
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1685
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1686 @node Input Methods
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1687 @section Input Methods
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1688 @cindex input methods
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1689
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1690 @dfn{Input methods} provide convenient ways of entering non-@acronym{ASCII}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1691 characters from the keyboard. Unlike coding systems, which translate
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1692 non-@acronym{ASCII} characters to and from encodings meant to be read by
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1693 programs, input methods provide human-friendly commands. (@xref{Input
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1694 Methods,,, emacs, The GNU Emacs Manual}, for information on how users
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1695 use input methods to enter text.) How to define input methods is not
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1696 yet documented in this manual, but here we describe how to use them.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1697
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1698 Each input method has a name, which is currently a string;
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1699 in the future, symbols may also be usable as input method names.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1700
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1701 @defvar current-input-method
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1702 This variable holds the name of the input method now active in the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1703 current buffer. (It automatically becomes local in each buffer when set
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1704 in any fashion.) It is @code{nil} if no input method is active in the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1705 buffer now.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1706 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1707
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1708 @defopt default-input-method
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1709 This variable holds the default input method for commands that choose an
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1710 input method. Unlike @code{current-input-method}, this variable is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1711 normally global.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1712 @end defopt
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1713
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1714 @deffn Command set-input-method input-method
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1715 This command activates input method @var{input-method} for the current
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1716 buffer. It also sets @code{default-input-method} to @var{input-method}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1717 If @var{input-method} is @code{nil}, this command deactivates any input
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1718 method for the current buffer.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1719 @end deffn
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1720
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1721 @defun read-input-method-name prompt &optional default inhibit-null
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1722 This function reads an input method name with the minibuffer, prompting
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1723 with @var{prompt}. If @var{default} is non-@code{nil}, that is returned
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1724 by default, if the user enters empty input. However, if
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1725 @var{inhibit-null} is non-@code{nil}, empty input signals an error.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1726
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1727 The returned value is a string.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1728 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1729
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1730 @defvar input-method-alist
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1731 This variable defines all the supported input methods.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1732 Each element defines one input method, and should have the form:
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1733
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1734 @example
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1735 (@var{input-method} @var{language-env} @var{activate-func}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1736 @var{title} @var{description} @var{args}...)
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1737 @end example
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1738
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1739 Here @var{input-method} is the input method name, a string;
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1740 @var{language-env} is another string, the name of the language
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1741 environment this input method is recommended for. (That serves only for
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1742 documentation purposes.)
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1743
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1744 @var{activate-func} is a function to call to activate this method. The
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1745 @var{args}, if any, are passed as arguments to @var{activate-func}. All
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1746 told, the arguments to @var{activate-func} are @var{input-method} and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1747 the @var{args}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1748
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1749 @var{title} is a string to display in the mode line while this method is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1750 active. @var{description} is a string describing this method and what
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1751 it is good for.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1752 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1753
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1754 The fundamental interface to input methods is through the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1755 variable @code{input-method-function}. @xref{Reading One Event},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1756 and @ref{Invoking the Input Method}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1757
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1758 @node Locales
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1759 @section Locales
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1760 @cindex locale
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1761
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1762 POSIX defines a concept of ``locales'' which control which language
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1763 to use in language-related features. These Emacs variables control
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1764 how Emacs interacts with these features.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1765
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1766 @defvar locale-coding-system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1767 @cindex keyboard input decoding on X
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1768 This variable specifies the coding system to use for decoding system
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1769 error messages and---on X Window system only---keyboard input, for
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1770 encoding the format argument to @code{format-time-string}, and for
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1771 decoding the return value of @code{format-time-string}.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1772 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1773
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1774 @defvar system-messages-locale
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1775 This variable specifies the locale to use for generating system error
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1776 messages. Changing the locale can cause messages to come out in a
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1777 different language or in a different orthography. If the variable is
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1778 @code{nil}, the locale is specified by environment variables in the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1779 usual POSIX fashion.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1780 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1781
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1782 @defvar system-time-locale
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1783 This variable specifies the locale to use for formatting time values.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1784 Changing the locale can cause messages to appear according to the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1785 conventions of a different language. If the variable is @code{nil}, the
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1786 locale is specified by environment variables in the usual POSIX fashion.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1787 @end defvar
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1788
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1789 @defun locale-info item
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1790 This function returns locale data @var{item} for the current POSIX
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1791 locale, if available. @var{item} should be one of these symbols:
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1792
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1793 @table @code
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1794 @item codeset
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1795 Return the character set as a string (locale item @code{CODESET}).
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1796
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1797 @item days
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1798 Return a 7-element vector of day names (locale items
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1799 @code{DAY_1} through @code{DAY_7});
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1800
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1801 @item months
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1802 Return a 12-element vector of month names (locale items @code{MON_1}
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1803 through @code{MON_12}).
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1804
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1805 @item paper
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1806 Return a list @code{(@var{width} @var{height})} for the default paper
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1807 size measured in millimeters (locale items @code{PAPER_WIDTH} and
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1808 @code{PAPER_HEIGHT}).
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1809 @end table
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1810
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1811 If the system can't provide the requested information, or if
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1812 @var{item} is not one of those symbols, the value is @code{nil}. All
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1813 strings in the return value are decoded using
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1814 @code{locale-coding-system}. @xref{Locales,,, libc, The GNU Libc Manual},
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1815 for more information about locales and locale items.
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1816 @end defun
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1817
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1818 @ignore
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1819 arch-tag: be705bf8-941b-4c35-84fc-ad7d20ddb7cb
e7e0d9a379c7 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1820 @end ignore