6447
|
1 @c -*-texinfo-*-
|
|
2 @c This is part of the GNU Emacs Lisp Reference Manual.
|
64889
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
|
|
4 @c 2004, 2005 Free Software Foundation, Inc.
|
6447
|
5 @c See the file elisp.texi for copying conditions.
|
|
6 @setfilename ../info/objects
|
7118
|
7 @node Lisp Data Types, Numbers, Introduction, Top
|
6447
|
8 @chapter Lisp Data Types
|
|
9 @cindex object
|
|
10 @cindex Lisp object
|
|
11 @cindex type
|
|
12 @cindex data type
|
|
13
|
|
14 A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
|
|
15 programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of
|
|
16 possible objects.
|
|
17
|
|
18 Every object belongs to at least one type. Objects of the same type
|
|
19 have similar structures and may usually be used in the same contexts.
|
|
20 Types can overlap, and objects can belong to two or more types.
|
|
21 Consequently, we can ask whether an object belongs to a particular type,
|
|
22 but not for ``the'' type of an object.
|
|
23
|
|
24 @cindex primitive type
|
|
25 A few fundamental object types are built into Emacs. These, from
|
26188
|
26 which all other types are constructed, are called @dfn{primitive types}.
|
|
27 Each object belongs to one and only one primitive type. These types
|
|
28 include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
|
|
29 @dfn{string}, @dfn{vector}, @dfn{hash-table}, @dfn{subr}, and
|
|
30 @dfn{byte-code function}, plus several special types, such as
|
|
31 @dfn{buffer}, that are related to editing. (@xref{Editing Types}.)
|
6447
|
32
|
|
33 Each primitive type has a corresponding Lisp function that checks
|
|
34 whether an object is a member of that type.
|
|
35
|
|
36 Note that Lisp is unlike many other languages in that Lisp objects are
|
|
37 @dfn{self-typing}: the primitive type of the object is implicit in the
|
|
38 object itself. For example, if an object is a vector, nothing can treat
|
|
39 it as a number; Lisp knows it is a vector, not a number.
|
|
40
|
|
41 In most languages, the programmer must declare the data type of each
|
|
42 variable, and the type is known by the compiler but not represented in
|
|
43 the data. Such type declarations do not exist in Emacs Lisp. A Lisp
|
7118
|
44 variable can have any type of value, and it remembers whatever value
|
53294
850a63ebfead
(Lisp Data Types): Mention that certain variables can only take on a
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
45 you store in it, type and all. (Actually, a small number of Emacs
|
850a63ebfead
(Lisp Data Types): Mention that certain variables can only take on a
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
46 Lisp variables can only take on values of a certain type.
|
850a63ebfead
(Lisp Data Types): Mention that certain variables can only take on a
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
47 @xref{Variables with Restricted Values}.)
|
6447
|
48
|
|
49 This chapter describes the purpose, printed representation, and read
|
|
50 syntax of each of the standard types in GNU Emacs Lisp. Details on how
|
|
51 to use these types can be found in later chapters.
|
|
52
|
|
53 @menu
|
|
54 * Printed Representation:: How Lisp objects are represented as text.
|
|
55 * Comments:: Comments and their formatting conventions.
|
|
56 * Programming Types:: Types found in all Lisp systems.
|
|
57 * Editing Types:: Types specific to Emacs.
|
25751
|
58 * Circular Objects:: Read syntax for circular structure.
|
6447
|
59 * Type Predicates:: Tests related to types.
|
|
60 * Equality Predicates:: Tests of equality between any two objects.
|
|
61 @end menu
|
|
62
|
|
63 @node Printed Representation
|
|
64 @comment node-name, next, previous, up
|
|
65 @section Printed Representation and Read Syntax
|
|
66 @cindex printed representation
|
|
67 @cindex read syntax
|
|
68
|
|
69 The @dfn{printed representation} of an object is the format of the
|
|
70 output generated by the Lisp printer (the function @code{prin1}) for
|
60044
|
71 that object. Every data type has a unique printed representation.
|
|
72 The @dfn{read syntax} of an object is the format of the input accepted
|
|
73 by the Lisp reader (the function @code{read}) for that object. This
|
|
74 is not necessarily unique; many kinds of object have more than one
|
|
75 syntax. @xref{Read and Print}.
|
21007
|
76
|
60044
|
77 @cindex hash notation
|
|
78 In most cases, an object's printed representation is also a read
|
|
79 syntax for the object. However, some types have no read syntax, since
|
|
80 it does not make sense to enter objects of these types as constants in
|
|
81 a Lisp program. These objects are printed in @dfn{hash notation}: the
|
|
82 characters @samp{#<} followed by a descriptive string (typically the
|
|
83 type name followed by the name of the object), and closed with a
|
|
84 matching @samp{>}. For example:
|
|
85
|
|
86 @example
|
|
87 (current-buffer)
|
|
88 @result{} #<buffer objects.texi>
|
|
89 @end example
|
|
90
|
|
91 @noindent
|
|
92 Hash notation cannot be read at all, so the Lisp reader signals the
|
|
93 error @code{invalid-read-syntax} whenever it encounters @samp{#<}.
|
|
94 @kindex invalid-read-syntax
|
6447
|
95
|
|
96 In other languages, an expression is text; it has no other form. In
|
|
97 Lisp, an expression is primarily a Lisp object and only secondarily the
|
|
98 text that is the object's read syntax. Often there is no need to
|
|
99 emphasize this distinction, but you must keep it in the back of your
|
|
100 mind, or you will occasionally be very confused.
|
|
101
|
|
102 When you evaluate an expression interactively, the Lisp interpreter
|
|
103 first reads the textual representation of it, producing a Lisp object,
|
|
104 and then evaluates that object (@pxref{Evaluation}). However,
|
|
105 evaluation and reading are separate activities. Reading returns the
|
|
106 Lisp object represented by the text that is read; the object may or may
|
|
107 not be evaluated later. @xref{Input Functions}, for a description of
|
|
108 @code{read}, the basic function for reading objects.
|
|
109
|
|
110 @node Comments
|
|
111 @comment node-name, next, previous, up
|
|
112 @section Comments
|
|
113 @cindex comments
|
|
114 @cindex @samp{;} in comment
|
|
115
|
|
116 A @dfn{comment} is text that is written in a program only for the sake
|
|
117 of humans that read the program, and that has no effect on the meaning
|
|
118 of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
|
|
119 is not within a string or character constant. The comment continues to
|
|
120 the end of line. The Lisp reader discards comments; they do not become
|
|
121 part of the Lisp objects which represent the program within the Lisp
|
|
122 system.
|
|
123
|
12098
|
124 The @samp{#@@@var{count}} construct, which skips the next @var{count}
|
|
125 characters, is useful for program-generated comments containing binary
|
|
126 data. The Emacs Lisp byte compiler uses this in its output files
|
|
127 (@pxref{Byte Compilation}). It isn't meant for source files, however.
|
|
128
|
6447
|
129 @xref{Comment Tips}, for conventions for formatting comments.
|
|
130
|
|
131 @node Programming Types
|
|
132 @section Programming Types
|
|
133 @cindex programming types
|
|
134
|
|
135 There are two general categories of types in Emacs Lisp: those having
|
|
136 to do with Lisp programming, and those having to do with editing. The
|
|
137 former exist in many Lisp implementations, in one form or another. The
|
|
138 latter are unique to Emacs Lisp.
|
|
139
|
|
140 @menu
|
|
141 * Integer Type:: Numbers without fractional parts.
|
|
142 * Floating Point Type:: Numbers with fractional parts and with a large range.
|
|
143 * Character Type:: The representation of letters, numbers and
|
|
144 control characters.
|
7337
|
145 * Symbol Type:: A multi-use object that refers to a function,
|
|
146 variable, or property list, and has a unique identity.
|
6447
|
147 * Sequence Type:: Both lists and arrays are classified as sequences.
|
7118
|
148 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
|
6447
|
149 * Array Type:: Arrays include strings and vectors.
|
|
150 * String Type:: An (efficient) array of characters.
|
|
151 * Vector Type:: One-dimensional arrays.
|
21007
|
152 * Char-Table Type:: One-dimensional sparse arrays indexed by characters.
|
|
153 * Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}.
|
25751
|
154 * Hash Table Type:: Super-fast lookup tables.
|
7337
|
155 * Function Type:: A piece of executable code you can call from elsewhere.
|
|
156 * Macro Type:: A method of expanding an expression into another
|
6447
|
157 expression, more fundamental but less pretty.
|
|
158 * Primitive Function Type:: A function written in C, callable from Lisp.
|
|
159 * Byte-Code Type:: A function written in Lisp, then compiled.
|
|
160 * Autoload Type:: A type used for automatically loading seldom-used
|
|
161 functions.
|
|
162 @end menu
|
|
163
|
|
164 @node Integer Type
|
|
165 @subsection Integer Type
|
|
166
|
52909
|
167 The range of values for integers in Emacs Lisp is @minus{}268435456 to
|
|
168 268435455 (29 bits; i.e.,
|
27193
|
169 @ifnottex
|
52909
|
170 -2**28
|
27193
|
171 @end ifnottex
|
6447
|
172 @tex
|
52909
|
173 @math{-2^{28}}
|
6447
|
174 @end tex
|
|
175 to
|
27193
|
176 @ifnottex
|
52909
|
177 2**28 - 1)
|
27193
|
178 @end ifnottex
|
6447
|
179 @tex
|
25751
|
180 @math{2^{28}-1})
|
6447
|
181 @end tex
|
10559
|
182 on most machines. (Some machines may provide a wider range.) It is
|
|
183 important to note that the Emacs Lisp arithmetic functions do not check
|
52909
|
184 for overflow. Thus @code{(1+ 268435455)} is @minus{}268435456 on most
|
10559
|
185 machines.
|
6447
|
186
|
7118
|
187 The read syntax for integers is a sequence of (base ten) digits with an
|
6447
|
188 optional sign at the beginning and an optional period at the end. The
|
|
189 printed representation produced by the Lisp interpreter never has a
|
|
190 leading @samp{+} or a final @samp{.}.
|
|
191
|
|
192 @example
|
|
193 @group
|
|
194 -1 ; @r{The integer -1.}
|
|
195 1 ; @r{The integer 1.}
|
25751
|
196 1. ; @r{Also the integer 1.}
|
6447
|
197 +1 ; @r{Also the integer 1.}
|
52909
|
198 536870913 ; @r{Also the integer 1 on a 29-bit implementation.}
|
6447
|
199 @end group
|
|
200 @end example
|
|
201
|
|
202 @xref{Numbers}, for more information.
|
|
203
|
|
204 @node Floating Point Type
|
|
205 @subsection Floating Point Type
|
|
206
|
36987
3a9bdf46b7db
Floating point is always available; say a little about what it is.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
207 Floating point numbers are the computer equivalent of scientific
|
60044
|
208 notation; you can think of a floating point number as a fraction
|
|
209 together with a power of ten. The precise number of significant
|
|
210 figures and the range of possible exponents is machine-specific; Emacs
|
|
211 uses the C data type @code{double} to store the value, and internally
|
|
212 this records a power of 2 rather than a power of 10.
|
6447
|
213
|
|
214 The printed representation for floating point numbers requires either
|
|
215 a decimal point (with at least one digit following), an exponent, or
|
|
216 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
|
|
217 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
|
|
218 number whose value is 1500. They are all equivalent.
|
|
219
|
|
220 @xref{Numbers}, for more information.
|
|
221
|
|
222 @node Character Type
|
|
223 @subsection Character Type
|
52978
|
224 @cindex @acronym{ASCII} character codes
|
6447
|
225
|
|
226 A @dfn{character} in Emacs Lisp is nothing more than an integer. In
|
|
227 other words, characters are represented by their character codes. For
|
|
228 example, the character @kbd{A} is represented as the @w{integer 65}.
|
|
229
|
|
230 Individual characters are not often used in programs. It is far more
|
|
231 common to work with @emph{strings}, which are sequences composed of
|
|
232 characters. @xref{String Type}.
|
|
233
|
53217
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
234 Characters in strings, buffers, and files are currently limited to
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
235 the range of 0 to 524287---nineteen bits. But not all values in that
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
236 range are valid character codes. Codes 0 through 127 are
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
237 @acronym{ASCII} codes; the rest are non-@acronym{ASCII}
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
238 (@pxref{Non-ASCII Characters}). Characters that represent keyboard
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
239 input have a much wider range, to encode modifier keys such as
|
21682
|
240 Control, Meta and Shift.
|
6447
|
241
|
|
242 @cindex read syntax for characters
|
|
243 @cindex printed representation for characters
|
|
244 @cindex syntax for characters
|
24951
|
245 @cindex @samp{?} in character constant
|
|
246 @cindex question mark in character constant
|
6447
|
247 Since characters are really integers, the printed representation of a
|
|
248 character is a decimal number. This is also a possible read syntax for
|
|
249 a character, but writing characters that way in Lisp programs is a very
|
|
250 bad idea. You should @emph{always} use the special read syntax formats
|
|
251 that Emacs Lisp provides for characters. These syntax formats start
|
|
252 with a question mark.
|
|
253
|
|
254 The usual read syntax for alphanumeric characters is a question mark
|
|
255 followed by the character; thus, @samp{?A} for the character
|
|
256 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
|
49600
|
257 character @kbd{a}.
|
6447
|
258
|
|
259 For example:
|
|
260
|
|
261 @example
|
|
262 ?Q @result{} 81 ?q @result{} 113
|
|
263 @end example
|
|
264
|
|
265 You can use the same syntax for punctuation characters, but it is
|
7118
|
266 often a good idea to add a @samp{\} so that the Emacs commands for
|
51991
|
267 editing Lisp code don't get confused. For example, @samp{?\(} is the
|
|
268 way to write the open-paren character. If the character is @samp{\},
|
|
269 you @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
|
6447
|
270
|
|
271 @cindex whitespace
|
|
272 @cindex bell character
|
|
273 @cindex @samp{\a}
|
|
274 @cindex backspace
|
|
275 @cindex @samp{\b}
|
|
276 @cindex tab
|
|
277 @cindex @samp{\t}
|
|
278 @cindex vertical tab
|
|
279 @cindex @samp{\v}
|
|
280 @cindex formfeed
|
|
281 @cindex @samp{\f}
|
|
282 @cindex newline
|
|
283 @cindex @samp{\n}
|
|
284 @cindex return
|
|
285 @cindex @samp{\r}
|
|
286 @cindex escape
|
|
287 @cindex @samp{\e}
|
49767
|
288 @cindex space
|
|
289 @cindex @samp{\s}
|
51991
|
290 You can express the characters control-g, backspace, tab, newline,
|
49767
|
291 vertical tab, formfeed, space, return, del, and escape as @samp{?\a},
|
37418
|
292 @samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f},
|
51991
|
293 @samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively.
|
|
294 Thus,
|
6447
|
295
|
|
296 @example
|
51991
|
297 ?\a @result{} 7 ; @r{control-g, @kbd{C-g}}
|
6447
|
298 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
|
|
299 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
|
21682
|
300 ?\n @result{} 10 ; @r{newline, @kbd{C-j}}
|
6447
|
301 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
|
|
302 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
|
|
303 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
|
|
304 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
|
49767
|
305 ?\s @result{} 32 ; @r{space character, @key{SPC}}
|
6447
|
306 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
|
25751
|
307 ?\d @result{} 127 ; @r{delete character, @key{DEL}}
|
6447
|
308 @end example
|
|
309
|
|
310 @cindex escape sequence
|
|
311 These sequences which start with backslash are also known as
|
51991
|
312 @dfn{escape sequences}, because backslash plays the role of an
|
|
313 ``escape character''; this terminology has nothing to do with the
|
|
314 character @key{ESC}. @samp{\s} is meant for use only in character
|
|
315 constants; in string constants, just write the space.
|
6447
|
316
|
|
317 @cindex control characters
|
|
318 Control characters may be represented using yet another read syntax.
|
|
319 This consists of a question mark followed by a backslash, caret, and the
|
|
320 corresponding non-control character, in either upper or lower case. For
|
|
321 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
|
|
322 character @kbd{C-i}, the character whose value is 9.
|
|
323
|
|
324 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
|
|
325 equivalent to @samp{?\^I} and to @samp{?\^i}:
|
|
326
|
|
327 @example
|
|
328 ?\^I @result{} 9 ?\C-I @result{} 9
|
|
329 @end example
|
|
330
|
21007
|
331 In strings and buffers, the only control characters allowed are those
|
52978
|
332 that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn
|
21007
|
333 any character into a control character with @samp{C-}. The character
|
52978
|
334 codes for these non-@acronym{ASCII} control characters include the
|
21682
|
335 @tex
|
25751
|
336 @math{2^{26}}
|
21682
|
337 @end tex
|
27193
|
338 @ifnottex
|
12098
|
339 2**26
|
27193
|
340 @end ifnottex
|
12098
|
341 bit as well as the code for the corresponding non-control
|
52978
|
342 character. Ordinary terminals have no way of generating non-@acronym{ASCII}
|
22267
|
343 control characters, but you can generate them straightforwardly using X
|
|
344 and other window systems.
|
6447
|
345
|
12098
|
346 For historical reasons, Emacs treats the @key{DEL} character as
|
|
347 the control equivalent of @kbd{?}:
|
6447
|
348
|
|
349 @example
|
|
350 ?\^? @result{} 127 ?\C-? @result{} 127
|
|
351 @end example
|
|
352
|
12098
|
353 @noindent
|
|
354 As a result, it is currently not possible to represent the character
|
21682
|
355 @kbd{Control-?}, which is a meaningful input character under X, using
|
|
356 @samp{\C-}. It is not easy to change this, as various Lisp files refer
|
|
357 to @key{DEL} in this way.
|
12098
|
358
|
6447
|
359 For representing control characters to be found in files or strings,
|
|
360 we recommend the @samp{^} syntax; for control characters in keyboard
|
21682
|
361 input, we prefer the @samp{C-} syntax. Which one you use does not
|
|
362 affect the meaning of the program, but may guide the understanding of
|
|
363 people who read it.
|
6447
|
364
|
|
365 @cindex meta characters
|
|
366 A @dfn{meta character} is a character typed with the @key{META}
|
|
367 modifier key. The integer that represents such a character has the
|
21682
|
368 @tex
|
25751
|
369 @math{2^{27}}
|
21682
|
370 @end tex
|
27193
|
371 @ifnottex
|
12098
|
372 2**27
|
27193
|
373 @end ifnottex
|
52909
|
374 bit set. We use high bits for this and other modifiers to make
|
|
375 possible a wide range of basic character codes.
|
6447
|
376
|
12098
|
377 In a string, the
|
21682
|
378 @tex
|
25751
|
379 @math{2^{7}}
|
21682
|
380 @end tex
|
27193
|
381 @ifnottex
|
12098
|
382 2**7
|
27193
|
383 @end ifnottex
|
53217
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
384 bit attached to an @acronym{ASCII} character indicates a meta
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
385 character; thus, the meta characters that can fit in a string have
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
386 codes in the range from 128 to 255, and are the meta versions of the
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
387 ordinary @acronym{ASCII} characters. (In Emacs versions 18 and older,
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
388 this convention was used for characters outside of strings as well.)
|
6447
|
389
|
|
390 The read syntax for meta characters uses @samp{\M-}. For example,
|
|
391 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
|
7118
|
392 octal character codes (see below), with @samp{\C-}, or with any other
|
|
393 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
|
|
394 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
|
|
395 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
|
6447
|
396
|
21007
|
397 The case of a graphic character is indicated by its character code;
|
52978
|
398 for example, @acronym{ASCII} distinguishes between the characters @samp{a}
|
|
399 and @samp{A}. But @acronym{ASCII} has no way to represent whether a control
|
21007
|
400 character is upper case or lower case. Emacs uses the
|
21682
|
401 @tex
|
25751
|
402 @math{2^{25}}
|
21682
|
403 @end tex
|
27193
|
404 @ifnottex
|
12098
|
405 2**25
|
27193
|
406 @end ifnottex
|
21682
|
407 bit to indicate that the shift key was used in typing a control
|
12098
|
408 character. This distinction is possible only when you use X terminals
|
21682
|
409 or other special terminals; ordinary terminals do not report the
|
24951
|
410 distinction to the computer in any way. The Lisp syntax for
|
49600
|
411 the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O}
|
24951
|
412 represents the shifted-control-o character.
|
6447
|
413
|
|
414 @cindex hyper characters
|
|
415 @cindex super characters
|
|
416 @cindex alt characters
|
56632
ae78f1a0047f
(Character Type): Reposition `@anchor' to prevent double space inside
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
417 The X Window System defines three other
|
ae78f1a0047f
(Character Type): Reposition `@anchor' to prevent double space inside
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
418 @anchor{modifier bits}modifier bits that can be set
|
6447
|
419 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
|
22138
|
420 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is
|
|
421 significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents
|
51991
|
422 @kbd{Alt-Hyper-Meta-x}. (Note that @samp{\s} with no following @samp{-}
|
|
423 represents the space character.)
|
21682
|
424 @tex
|
53217
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
425 Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}}
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
426 for super and @math{2^{24}} for hyper.
|
21682
|
427 @end tex
|
27193
|
428 @ifnottex
|
12098
|
429 Numerically, the
|
|
430 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
|
27193
|
431 @end ifnottex
|
6447
|
432
|
|
433 @cindex @samp{\} in character constant
|
|
434 @cindex backslash in character constant
|
|
435 @cindex octal character code
|
21007
|
436 Finally, the most general read syntax for a character represents the
|
|
437 character code in either octal or hex. To use octal, write a question
|
|
438 mark followed by a backslash and the octal character code (up to three
|
6447
|
439 octal digits); thus, @samp{?\101} for the character @kbd{A},
|
|
440 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
|
52978
|
441 character @kbd{C-b}. Although this syntax can represent any @acronym{ASCII}
|
6447
|
442 character, it is preferred only when the precise octal value is more
|
52978
|
443 important than the @acronym{ASCII} representation.
|
6447
|
444
|
|
445 @example
|
|
446 @group
|
|
447 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
|
|
448 ?\101 @result{} 65 ?A @result{} 65
|
|
449 @end group
|
|
450 @end example
|
|
451
|
21007
|
452 To use hex, write a question mark followed by a backslash, @samp{x},
|
|
453 and the hexadecimal character code. You can use any number of hex
|
|
454 digits, so you can represent any character code in this way.
|
|
455 Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
|
35477
|
456 character @kbd{C-a}, and @code{?\x8e0} for the Latin-1 character
|
21007
|
457 @iftex
|
21682
|
458 @samp{@`a}.
|
21007
|
459 @end iftex
|
27193
|
460 @ifnottex
|
21007
|
461 @samp{a} with grave accent.
|
27193
|
462 @end ifnottex
|
21007
|
463
|
6447
|
464 A backslash is allowed, and harmless, preceding any character without
|
|
465 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
|
|
466 There is no reason to add a backslash before most characters. However,
|
|
467 you should add a backslash before any of the characters
|
|
468 @samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
|
51991
|
469 Lisp code. You can also add a backslash before whitespace characters such as
|
6447
|
470 space, tab, newline and formfeed. However, it is cleaner to use one of
|
49767
|
471 the easily readable escape sequences, such as @samp{\t} or @samp{\s},
|
|
472 instead of an actual whitespace character such as a tab or a space.
|
51991
|
473 (If you do write backslash followed by a space, you should write
|
|
474 an extra space after the character constant to separate it from the
|
|
475 following text.)
|
6447
|
476
|
7118
|
477 @node Symbol Type
|
|
478 @subsection Symbol Type
|
|
479
|
60044
|
480 A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The
|
|
481 symbol name serves as the printed representation of the symbol. In
|
|
482 ordinary Lisp use, with one single obarray (@pxref{Creating Symbols},
|
|
483 a symbol's name is unique---no two symbols have the same name.
|
7118
|
484
|
|
485 A symbol can serve as a variable, as a function name, or to hold a
|
|
486 property list. Or it may serve only to be distinct from all other Lisp
|
|
487 objects, so that its presence in a data structure may be recognized
|
|
488 reliably. In a given context, usually only one of these uses is
|
|
489 intended. But you can use one symbol in all of these ways,
|
|
490 independently.
|
|
491
|
26188
|
492 A symbol whose name starts with a colon (@samp{:}) is called a
|
|
493 @dfn{keyword symbol}. These symbols automatically act as constants, and
|
|
494 are normally used only by comparing an unknown symbol with a few
|
|
495 specific alternatives.
|
|
496
|
7118
|
497 @cindex @samp{\} in symbols
|
|
498 @cindex backslash in symbols
|
|
499 A symbol name can contain any characters whatever. Most symbol names
|
|
500 are written with letters, digits, and the punctuation characters
|
|
501 @samp{-+=*/}. Such names require no special punctuation; the characters
|
|
502 of the name suffice as long as the name does not look like a number.
|
|
503 (If it does, write a @samp{\} at the beginning of the name to force
|
31561
|
504 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}?} are
|
7118
|
505 less often used but also require no special punctuation. Any other
|
|
506 characters may be included in a symbol's name by escaping them with a
|
|
507 backslash. In contrast to its use in strings, however, a backslash in
|
|
508 the name of a symbol simply quotes the single character that follows the
|
|
509 backslash. For example, in a string, @samp{\t} represents a tab
|
|
510 character; in the name of a symbol, however, @samp{\t} merely quotes the
|
21682
|
511 letter @samp{t}. To have a symbol with a tab character in its name, you
|
7118
|
512 must actually use a tab (preceded with a backslash). But it's rare to
|
|
513 do such a thing.
|
|
514
|
|
515 @cindex CL note---case of letters
|
|
516 @quotation
|
7734
|
517 @b{Common Lisp note:} In Common Lisp, lower case letters are always
|
12098
|
518 ``folded'' to upper case, unless they are explicitly escaped. In Emacs
|
|
519 Lisp, upper case and lower case letters are distinct.
|
7118
|
520 @end quotation
|
|
521
|
|
522 Here are several examples of symbol names. Note that the @samp{+} in
|
|
523 the fifth example is escaped to prevent it from being read as a number.
|
60008
|
524 This is not necessary in the fourth example because the rest of the name
|
7118
|
525 makes it invalid as a number.
|
|
526
|
|
527 @example
|
|
528 @group
|
|
529 foo ; @r{A symbol named @samp{foo}.}
|
|
530 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
|
|
531 char-to-string ; @r{A symbol named @samp{char-to-string}.}
|
|
532 @end group
|
|
533 @group
|
|
534 1+ ; @r{A symbol named @samp{1+}}
|
|
535 ; @r{(not @samp{+1}, which is an integer).}
|
|
536 @end group
|
|
537 @group
|
|
538 \+1 ; @r{A symbol named @samp{+1}}
|
|
539 ; @r{(not a very readable name).}
|
|
540 @end group
|
|
541 @group
|
|
542 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
|
|
543 @c the @'s in this next line use up three characters, hence the
|
|
544 @c apparent misalignment of the comment.
|
|
545 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
|
|
546 ; @r{These characters need not be escaped.}
|
|
547 @end group
|
|
548 @end example
|
|
549
|
44089
a8d9fd32a154
(Symbol Type): Use `colon' in index entries instead of `:' only in Info.
Eli Zaretskii <eliz@gnu.org>
diff
changeset
|
550 @ifinfo
|
43888
|
551 @c This uses ``colon'' instead of a literal `:' because Info cannot
|
|
552 @c cope with a `:' in a menu
|
|
553 @cindex @samp{#@var{colon}} read syntax
|
44089
a8d9fd32a154
(Symbol Type): Use `colon' in index entries instead of `:' only in Info.
Eli Zaretskii <eliz@gnu.org>
diff
changeset
|
554 @end ifinfo
|
a8d9fd32a154
(Symbol Type): Use `colon' in index entries instead of `:' only in Info.
Eli Zaretskii <eliz@gnu.org>
diff
changeset
|
555 @ifnotinfo
|
a8d9fd32a154
(Symbol Type): Use `colon' in index entries instead of `:' only in Info.
Eli Zaretskii <eliz@gnu.org>
diff
changeset
|
556 @cindex @samp{#:} read syntax
|
a8d9fd32a154
(Symbol Type): Use `colon' in index entries instead of `:' only in Info.
Eli Zaretskii <eliz@gnu.org>
diff
changeset
|
557 @end ifnotinfo
|
25751
|
558 Normally the Lisp reader interns all symbols (@pxref{Creating
|
|
559 Symbols}). To prevent interning, you can write @samp{#:} before the
|
|
560 name of the symbol.
|
|
561
|
6447
|
562 @node Sequence Type
|
|
563 @subsection Sequence Types
|
|
564
|
|
565 A @dfn{sequence} is a Lisp object that represents an ordered set of
|
|
566 elements. There are two kinds of sequence in Emacs Lisp, lists and
|
|
567 arrays. Thus, an object of type list or of type array is also
|
|
568 considered a sequence.
|
|
569
|
21682
|
570 Arrays are further subdivided into strings, vectors, char-tables and
|
|
571 bool-vectors. Vectors can hold elements of any type, but string
|
|
572 elements must be characters, and bool-vector elements must be @code{t}
|
35111
b1adf7e27ea8
Minor fix because a bool-vector's elements can't be characters.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
573 or @code{nil}. Char-tables are like vectors except that they are
|
b1adf7e27ea8
Minor fix because a bool-vector's elements can't be characters.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
574 indexed by any valid character code. The characters in a string can
|
b1adf7e27ea8
Minor fix because a bool-vector's elements can't be characters.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
575 have text properties like characters in a buffer (@pxref{Text
|
b1adf7e27ea8
Minor fix because a bool-vector's elements can't be characters.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
576 Properties}), but vectors do not support text properties, even when
|
b1adf7e27ea8
Minor fix because a bool-vector's elements can't be characters.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
577 their elements happen to be characters.
|
6447
|
578
|
21682
|
579 Lists, strings and the other array types are different, but they have
|
|
580 important similarities. For example, all have a length @var{l}, and all
|
|
581 have elements which can be indexed from zero to @var{l} minus one.
|
|
582 Several functions, called sequence functions, accept any kind of
|
6447
|
583 sequence. For example, the function @code{elt} can be used to extract
|
|
584 an element of a sequence, given its index. @xref{Sequences Arrays
|
|
585 Vectors}.
|
|
586
|
21682
|
587 It is generally impossible to read the same sequence twice, since
|
|
588 sequences are always created anew upon reading. If you read the read
|
|
589 syntax for a sequence twice, you get two sequences with equal contents.
|
|
590 There is one exception: the empty list @code{()} always stands for the
|
|
591 same object, @code{nil}.
|
6447
|
592
|
7118
|
593 @node Cons Cell Type
|
|
594 @subsection Cons Cell and List Types
|
6447
|
595 @cindex address field of register
|
|
596 @cindex decrement field of register
|
22267
|
597 @cindex pointers
|
6447
|
598
|
24951
|
599 A @dfn{cons cell} is an object that consists of two slots, called the
|
|
600 @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or
|
25751
|
601 @dfn{refer to} any Lisp object. We also say that ``the @sc{car} of
|
24951
|
602 this cons cell is'' whatever object its @sc{car} slot currently holds,
|
|
603 and likewise for the @sc{cdr}.
|
|
604
|
|
605 @quotation
|
|
606 A note to C programmers: in Lisp, we do not distinguish between
|
|
607 ``holding'' a value and ``pointing to'' the value, because pointers in
|
|
608 Lisp are implicit.
|
|
609 @end quotation
|
7118
|
610
|
|
611 A @dfn{list} is a series of cons cells, linked together so that the
|
22267
|
612 @sc{cdr} slot of each cons cell holds either the next cons cell or the
|
60044
|
613 empty list. The empty list is actually the symbol @code{nil}.
|
|
614 @xref{Lists}, for functions that work on lists. Because most cons
|
|
615 cells are used as part of lists, the phrase @dfn{list structure} has
|
|
616 come to refer to any structure made out of cons cells.
|
|
617
|
|
618 @cindex atom
|
|
619 Because cons cells are so central to Lisp, we also have a word for
|
|
620 ``an object which is not a cons cell''. These objects are called
|
|
621 @dfn{atoms}.
|
|
622
|
|
623 @cindex parenthesis
|
|
624 The read syntax and printed representation for lists are identical, and
|
|
625 consist of a left parenthesis, an arbitrary number of elements, and a
|
|
626 right parenthesis. Here are examples of lists:
|
|
627
|
|
628 @example
|
|
629 (A 2 "A") ; @r{A list of three elements.}
|
|
630 () ; @r{A list of no elements (the empty list).}
|
|
631 nil ; @r{A list of no elements (the empty list).}
|
|
632 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
|
|
633 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
|
|
634 (A nil) ; @r{Equivalent to the previous.}
|
|
635 ((A B C)) ; @r{A list of one element}
|
|
636 ; @r{(which is a list of three elements).}
|
|
637 @end example
|
|
638
|
|
639 Upon reading, each object inside the parentheses becomes an element
|
|
640 of the list. That is, a cons cell is made for each element. The
|
|
641 @sc{car} slot of the cons cell holds the element, and its @sc{cdr}
|
|
642 slot refers to the next cons cell of the list, which holds the next
|
|
643 element in the list. The @sc{cdr} slot of the last cons cell is set to
|
|
644 hold @code{nil}.
|
6447
|
645
|
22267
|
646 The names @sc{car} and @sc{cdr} derive from the history of Lisp. The
|
6447
|
647 original Lisp implementation ran on an @w{IBM 704} computer which
|
|
648 divided words into two parts, called the ``address'' part and the
|
|
649 ``decrement''; @sc{car} was an instruction to extract the contents of
|
|
650 the address part of a register, and @sc{cdr} an instruction to extract
|
|
651 the contents of the decrement. By contrast, ``cons cells'' are named
|
24951
|
652 for the function @code{cons} that creates them, which in turn was named
|
6447
|
653 for its purpose, the construction of cells.
|
|
654
|
60044
|
655 @menu
|
|
656 * Box Diagrams:: Drawing pictures of lists.
|
|
657 * Dotted Pair Notation:: A general syntax for cons cells.
|
|
658 * Association List Type:: A specially constructed list.
|
|
659 @end menu
|
6447
|
660
|
60044
|
661 @node Box Diagrams
|
|
662 @subsubsection Drawing Lists as Box Diagrams
|
6447
|
663 @cindex box diagrams, for lists
|
|
664 @cindex diagrams, boxed, for lists
|
60044
|
665
|
6447
|
666 A list can be illustrated by a diagram in which the cons cells are
|
22267
|
667 shown as pairs of boxes, like dominoes. (The Lisp reader cannot read
|
|
668 such an illustration; unlike the textual notation, which can be
|
|
669 understood by both humans and computers, the box illustrations can be
|
|
670 understood only by humans.) This picture represents the three-element
|
|
671 list @code{(rose violet buttercup)}:
|
6447
|
672
|
|
673 @example
|
|
674 @group
|
21682
|
675 --- --- --- --- --- ---
|
|
676 | | |--> | | |--> | | |--> nil
|
|
677 --- --- --- --- --- ---
|
6447
|
678 | | |
|
|
679 | | |
|
|
680 --> rose --> violet --> buttercup
|
|
681 @end group
|
|
682 @end example
|
|
683
|
24951
|
684 In this diagram, each box represents a slot that can hold or refer to
|
|
685 any Lisp object. Each pair of boxes represents a cons cell. Each arrow
|
|
686 represents a reference to a Lisp object, either an atom or another cons
|
|
687 cell.
|
6447
|
688
|
22267
|
689 In this example, the first box, which holds the @sc{car} of the first
|
24951
|
690 cons cell, refers to or ``holds'' @code{rose} (a symbol). The second
|
|
691 box, holding the @sc{cdr} of the first cons cell, refers to the next
|
22267
|
692 pair of boxes, the second cons cell. The @sc{car} of the second cons
|
|
693 cell is @code{violet}, and its @sc{cdr} is the third cons cell. The
|
|
694 @sc{cdr} of the third (and last) cons cell is @code{nil}.
|
6447
|
695
|
22267
|
696 Here is another diagram of the same list, @code{(rose violet
|
6447
|
697 buttercup)}, sketched in a different manner:
|
|
698
|
|
699 @smallexample
|
|
700 @group
|
|
701 --------------- ---------------- -------------------
|
|
702 | car | cdr | | car | cdr | | car | cdr |
|
|
703 | rose | o-------->| violet | o-------->| buttercup | nil |
|
|
704 | | | | | | | | |
|
|
705 --------------- ---------------- -------------------
|
|
706 @end group
|
|
707 @end smallexample
|
|
708
|
|
709 @cindex @samp{(@dots{})} in lists
|
|
710 @cindex @code{nil} in lists
|
|
711 @cindex empty list
|
|
712 A list with no elements in it is the @dfn{empty list}; it is identical
|
|
713 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
|
|
714 and a list.
|
|
715
|
|
716 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
|
|
717 depicted with boxes and arrows:
|
|
718
|
|
719 @example
|
|
720 @group
|
21682
|
721 --- --- --- ---
|
|
722 | | |--> | | |--> nil
|
|
723 --- --- --- ---
|
6447
|
724 | |
|
|
725 | |
|
|
726 --> A --> nil
|
|
727 @end group
|
|
728 @end example
|
|
729
|
60044
|
730 Here is a more complex illustration, showing the three-element list,
|
|
731 @code{((pine needles) oak maple)}, the first element of which is a
|
|
732 two-element list:
|
|
733
|
|
734 @example
|
|
735 @group
|
|
736 --- --- --- --- --- ---
|
|
737 | | |--> | | |--> | | |--> nil
|
|
738 --- --- --- --- --- ---
|
|
739 | | |
|
|
740 | | |
|
|
741 | --> oak --> maple
|
|
742 |
|
|
743 | --- --- --- ---
|
|
744 --> | | |--> | | |--> nil
|
|
745 --- --- --- ---
|
|
746 | |
|
|
747 | |
|
|
748 --> pine --> needles
|
|
749 @end group
|
|
750 @end example
|
|
751
|
|
752 The same list represented in the first box notation looks like this:
|
|
753
|
|
754 @example
|
|
755 @group
|
|
756 -------------- -------------- --------------
|
|
757 | car | cdr | | car | cdr | | car | cdr |
|
|
758 | o | o------->| oak | o------->| maple | nil |
|
|
759 | | | | | | | | | |
|
|
760 -- | --------- -------------- --------------
|
|
761 |
|
|
762 |
|
|
763 | -------------- ----------------
|
|
764 | | car | cdr | | car | cdr |
|
|
765 ------>| pine | o------->| needles | nil |
|
|
766 | | | | | |
|
|
767 -------------- ----------------
|
|
768 @end group
|
|
769 @end example
|
6447
|
770
|
|
771 @node Dotted Pair Notation
|
|
772 @subsubsection Dotted Pair Notation
|
|
773 @cindex dotted pair notation
|
|
774 @cindex @samp{.} in lists
|
|
775
|
60044
|
776 @dfn{Dotted pair notation} is a general syntax for cons cells that
|
|
777 represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
|
6447
|
778 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
|
|
779 the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted
|
60044
|
780 pair notation is more general than list syntax because the @sc{cdr}
|
|
781 does not have to be a list. However, it is more cumbersome in cases
|
|
782 where list syntax would work. In dotted pair notation, the list
|
|
783 @samp{(1 2 3)} is written as @samp{(1 . (2 . (3 . nil)))}. For
|
|
784 @code{nil}-terminated lists, you can use either notation, but list
|
|
785 notation is usually clearer and more convenient. When printing a
|
|
786 list, the dotted pair notation is only used if the @sc{cdr} of a cons
|
|
787 cell is not a list.
|
6447
|
788
|
22267
|
789 Here's an example using boxes to illustrate dotted pair notation.
|
|
790 This example shows the pair @code{(rose . violet)}:
|
6447
|
791
|
|
792 @example
|
|
793 @group
|
21682
|
794 --- ---
|
|
795 | | |--> violet
|
|
796 --- ---
|
6447
|
797 |
|
|
798 |
|
|
799 --> rose
|
|
800 @end group
|
|
801 @end example
|
|
802
|
22267
|
803 You can combine dotted pair notation with list notation to represent
|
|
804 conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}.
|
|
805 You write a dot after the last element of the list, followed by the
|
|
806 @sc{cdr} of the final cons cell. For example, @code{(rose violet
|
|
807 . buttercup)} is equivalent to @code{(rose . (violet . buttercup))}.
|
|
808 The object looks like this:
|
6447
|
809
|
|
810 @example
|
|
811 @group
|
21682
|
812 --- --- --- ---
|
|
813 | | |--> | | |--> buttercup
|
|
814 --- --- --- ---
|
6447
|
815 | |
|
|
816 | |
|
|
817 --> rose --> violet
|
|
818 @end group
|
|
819 @end example
|
|
820
|
22267
|
821 The syntax @code{(rose .@: violet .@: buttercup)} is invalid because
|
|
822 there is nothing that it could mean. If anything, it would say to put
|
|
823 @code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already
|
|
824 used for @code{violet}.
|
6447
|
825
|
22267
|
826 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))},
|
6447
|
827 and looks like this:
|
|
828
|
|
829 @example
|
|
830 @group
|
21682
|
831 --- --- --- ---
|
|
832 | | |--> | | |--> nil
|
|
833 --- --- --- ---
|
6447
|
834 | |
|
|
835 | |
|
|
836 --> rose --> violet
|
|
837 @end group
|
|
838 @end example
|
|
839
|
|
840 Similarly, the three-element list @code{(rose violet buttercup)}
|
|
841 is equivalent to @code{(rose . (violet . (buttercup)))}.
|
27193
|
842 @ifnottex
|
6447
|
843 It looks like this:
|
|
844
|
|
845 @example
|
|
846 @group
|
21682
|
847 --- --- --- --- --- ---
|
|
848 | | |--> | | |--> | | |--> nil
|
|
849 --- --- --- --- --- ---
|
6447
|
850 | | |
|
|
851 | | |
|
|
852 --> rose --> violet --> buttercup
|
|
853 @end group
|
|
854 @end example
|
27193
|
855 @end ifnottex
|
6447
|
856
|
|
857 @node Association List Type
|
|
858 @comment node-name, next, previous, up
|
|
859 @subsubsection Association List Type
|
|
860
|
|
861 An @dfn{association list} or @dfn{alist} is a specially-constructed
|
|
862 list whose elements are cons cells. In each element, the @sc{car} is
|
|
863 considered a @dfn{key}, and the @sc{cdr} is considered an
|
|
864 @dfn{associated value}. (In some cases, the associated value is stored
|
|
865 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
|
|
866 stacks, since it is easy to add or remove associations at the front of
|
|
867 the list.
|
|
868
|
|
869 For example,
|
|
870
|
|
871 @example
|
|
872 (setq alist-of-colors
|
38940
|
873 '((rose . red) (lily . white) (buttercup . yellow)))
|
6447
|
874 @end example
|
|
875
|
|
876 @noindent
|
|
877 sets the variable @code{alist-of-colors} to an alist of three elements. In the
|
|
878 first element, @code{rose} is the key and @code{red} is the value.
|
|
879
|
|
880 @xref{Association Lists}, for a further explanation of alists and for
|
25751
|
881 functions that work on alists. @xref{Hash Tables}, for another kind of
|
|
882 lookup table, which is much faster for handling a large number of keys.
|
6447
|
883
|
|
884 @node Array Type
|
|
885 @subsection Array Type
|
|
886
|
|
887 An @dfn{array} is composed of an arbitrary number of slots for
|
24951
|
888 holding or referring to other Lisp objects, arranged in a contiguous block of
|
21682
|
889 memory. Accessing any element of an array takes approximately the same
|
|
890 amount of time. In contrast, accessing an element of a list requires
|
|
891 time proportional to the position of the element in the list. (Elements
|
|
892 at the end of a list take longer to access than elements at the
|
|
893 beginning of a list.)
|
|
894
|
|
895 Emacs defines four types of array: strings, vectors, bool-vectors, and
|
|
896 char-tables.
|
|
897
|
|
898 A string is an array of characters and a vector is an array of
|
|
899 arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}.
|
|
900 These kinds of array may have any length up to the largest integer.
|
|
901 Char-tables are sparse arrays indexed by any valid character code; they
|
|
902 can hold arbitrary objects.
|
6447
|
903
|
21682
|
904 The first element of an array has index zero, the second element has
|
|
905 index 1, and so on. This is called @dfn{zero-origin} indexing. For
|
|
906 example, an array of four elements has indices 0, 1, 2, @w{and 3}. The
|
|
907 largest possible index value is one less than the length of the array.
|
|
908 Once an array is created, its length is fixed.
|
6447
|
909
|
21682
|
910 All Emacs Lisp arrays are one-dimensional. (Most other programming
|
|
911 languages support multidimensional arrays, but they are not essential;
|
60044
|
912 you can get the same effect with nested one-dimensional arrays.) Each
|
|
913 type of array has its own read syntax; see the following sections for
|
|
914 details.
|
6447
|
915
|
21682
|
916 The array type is contained in the sequence type and
|
|
917 contains the string type, the vector type, the bool-vector type, and the
|
|
918 char-table type.
|
6447
|
919
|
|
920 @node String Type
|
|
921 @subsection String Type
|
|
922
|
|
923 A @dfn{string} is an array of characters. Strings are used for many
|
|
924 purposes in Emacs, as can be expected in a text editor; for example, as
|
|
925 the names of Lisp symbols, as messages for the user, and to represent
|
|
926 text extracted from buffers. Strings in Lisp are constants: evaluation
|
|
927 of a string returns the same string.
|
|
928
|
21007
|
929 @xref{Strings and Characters}, for functions that operate on strings.
|
|
930
|
|
931 @menu
|
|
932 * Syntax for Strings::
|
|
933 * Non-ASCII in Strings::
|
|
934 * Nonprinting Characters::
|
|
935 * Text Props and Strings::
|
|
936 @end menu
|
|
937
|
|
938 @node Syntax for Strings
|
|
939 @subsubsection Syntax for Strings
|
|
940
|
6447
|
941 @cindex @samp{"} in strings
|
|
942 @cindex double-quote in strings
|
|
943 @cindex @samp{\} in strings
|
|
944 @cindex backslash in strings
|
|
945 The read syntax for strings is a double-quote, an arbitrary number of
|
21007
|
946 characters, and another double-quote, @code{"like this"}. To include a
|
|
947 double-quote in a string, precede it with a backslash; thus, @code{"\""}
|
|
948 is a string containing just a single double-quote character. Likewise,
|
|
949 you can include a backslash by preceding it with another backslash, like
|
|
950 this: @code{"this \\ is a single embedded backslash"}.
|
6447
|
951
|
21007
|
952 @cindex newline in strings
|
7118
|
953 The newline character is not special in the read syntax for strings;
|
|
954 if you write a new line between the double-quotes, it becomes a
|
|
955 character in the string. But an escaped newline---one that is preceded
|
|
956 by @samp{\}---does not become part of the string; i.e., the Lisp reader
|
21007
|
957 ignores an escaped newline while reading a string. An escaped space
|
|
958 @w{@samp{\ }} is likewise ignored.
|
6447
|
959
|
|
960 @example
|
|
961 "It is useful to include newlines
|
|
962 in documentation strings,
|
|
963 but the newline is \
|
|
964 ignored if escaped."
|
49600
|
965 @result{} "It is useful to include newlines
|
|
966 in documentation strings,
|
6447
|
967 but the newline is ignored if escaped."
|
|
968 @end example
|
|
969
|
21007
|
970 @node Non-ASCII in Strings
|
52978
|
971 @subsubsection Non-@acronym{ASCII} Characters in Strings
|
21007
|
972
|
52978
|
973 You can include a non-@acronym{ASCII} international character in a string
|
21007
|
974 constant by writing it literally. There are two text representations
|
52978
|
975 for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte
|
21007
|
976 and multibyte. If the string constant is read from a multibyte source,
|
21682
|
977 such as a multibyte buffer or string, or a file that would be visited as
|
|
978 multibyte, then the character is read as a multibyte character, and that
|
|
979 makes the string multibyte. If the string constant is read from a
|
|
980 unibyte source, then the character is read as unibyte and that makes the
|
|
981 string unibyte.
|
21007
|
982
|
52978
|
983 You can also represent a multibyte non-@acronym{ASCII} character with its
|
25751
|
984 character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
|
52978
|
985 digits as necessary. (Multibyte non-@acronym{ASCII} character codes are all
|
21007
|
986 greater than 256.) Any character which is not a valid hex digit
|
24951
|
987 terminates this construct. If the next character in the string could be
|
|
988 interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
|
|
989 terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents
|
|
990 one character, @samp{a} with grave accent. @w{@samp{\ }} in a string
|
|
991 constant is just like backslash-newline; it does not contribute any
|
|
992 character to the string, but it does terminate the preceding hex escape.
|
21007
|
993
|
53217
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
994 You can represent a unibyte non-@acronym{ASCII} character with its
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
995 character code, which must be in the range from 128 (0200 octal) to
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
996 255 (0377 octal). If you write all such character codes in octal and
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
997 the string contains no other characters forcing it to be multibyte,
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
998 this produces a unibyte string. However, using any hex escape in a
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
999 string (even for an @acronym{ASCII} character) forces the string to be
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1000 multibyte.
|
49600
|
1001
|
21007
|
1002 @xref{Text Representations}, for more information about the two
|
|
1003 text representations.
|
|
1004
|
|
1005 @node Nonprinting Characters
|
|
1006 @subsubsection Nonprinting Characters in Strings
|
|
1007
|
|
1008 You can use the same backslash escape-sequences in a string constant
|
|
1009 as in character literals (but do not use the question mark that begins a
|
|
1010 character constant). For example, you can write a string containing the
|
22138
|
1011 nonprinting characters tab and @kbd{C-a}, with commas and spaces between
|
|
1012 them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a
|
|
1013 description of the read syntax for characters.
|
21007
|
1014
|
22138
|
1015 However, not all of the characters you can write with backslash
|
|
1016 escape-sequences are valid in strings. The only control characters that
|
52978
|
1017 a string can hold are the @acronym{ASCII} control characters. Strings do not
|
|
1018 distinguish case in @acronym{ASCII} control characters.
|
22138
|
1019
|
|
1020 Properly speaking, strings cannot hold meta characters; but when a
|
|
1021 string is to be used as a key sequence, there is a special convention
|
53217
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1022 that provides a way to represent meta versions of @acronym{ASCII}
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1023 characters in a string. If you use the @samp{\M-} syntax to indicate
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1024 a meta character in a string constant, this sets the
|
21682
|
1025 @tex
|
25751
|
1026 @math{2^{7}}
|
21682
|
1027 @end tex
|
27193
|
1028 @ifnottex
|
21007
|
1029 2**7
|
27193
|
1030 @end ifnottex
|
22138
|
1031 bit of the character in the string. If the string is used in
|
|
1032 @code{define-key} or @code{lookup-key}, this numeric code is translated
|
|
1033 into the equivalent meta character. @xref{Character Type}.
|
|
1034
|
|
1035 Strings cannot hold characters that have the hyper, super, or alt
|
|
1036 modifiers.
|
21007
|
1037
|
|
1038 @node Text Props and Strings
|
|
1039 @subsubsection Text Properties in Strings
|
|
1040
|
|
1041 A string can hold properties for the characters it contains, in
|
|
1042 addition to the characters themselves. This enables programs that copy
|
|
1043 text between strings and buffers to copy the text's properties with no
|
|
1044 special effort. @xref{Text Properties}, for an explanation of what text
|
|
1045 properties mean. Strings with text properties use a special read and
|
|
1046 print syntax:
|
6447
|
1047
|
|
1048 @example
|
|
1049 #("@var{characters}" @var{property-data}...)
|
|
1050 @end example
|
|
1051
|
|
1052 @noindent
|
|
1053 where @var{property-data} consists of zero or more elements, in groups
|
|
1054 of three as follows:
|
|
1055
|
|
1056 @example
|
|
1057 @var{beg} @var{end} @var{plist}
|
|
1058 @end example
|
|
1059
|
|
1060 @noindent
|
|
1061 The elements @var{beg} and @var{end} are integers, and together specify
|
|
1062 a range of indices in the string; @var{plist} is the property list for
|
21007
|
1063 that range. For example,
|
|
1064
|
|
1065 @example
|
|
1066 #("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
|
|
1067 @end example
|
6447
|
1068
|
21007
|
1069 @noindent
|
|
1070 represents a string whose textual contents are @samp{foo bar}, in which
|
|
1071 the first three characters have a @code{face} property with value
|
|
1072 @code{bold}, and the last three have a @code{face} property with value
|
22267
|
1073 @code{italic}. (The fourth character has no text properties, so its
|
22138
|
1074 property list is @code{nil}. It is not actually necessary to mention
|
|
1075 ranges with @code{nil} as the property list, since any characters not
|
|
1076 mentioned in any range will default to having no properties.)
|
6447
|
1077
|
|
1078 @node Vector Type
|
|
1079 @subsection Vector Type
|
|
1080
|
|
1081 A @dfn{vector} is a one-dimensional array of elements of any type. It
|
|
1082 takes a constant amount of time to access any element of a vector. (In
|
|
1083 a list, the access time of an element is proportional to the distance of
|
|
1084 the element from the beginning of the list.)
|
|
1085
|
|
1086 The printed representation of a vector consists of a left square
|
|
1087 bracket, the elements, and a right square bracket. This is also the
|
|
1088 read syntax. Like numbers and strings, vectors are considered constants
|
|
1089 for evaluation.
|
|
1090
|
|
1091 @example
|
|
1092 [1 "two" (three)] ; @r{A vector of three elements.}
|
|
1093 @result{} [1 "two" (three)]
|
|
1094 @end example
|
|
1095
|
|
1096 @xref{Vectors}, for functions that work with vectors.
|
|
1097
|
21007
|
1098 @node Char-Table Type
|
|
1099 @subsection Char-Table Type
|
|
1100
|
|
1101 A @dfn{char-table} is a one-dimensional array of elements of any type,
|
|
1102 indexed by character codes. Char-tables have certain extra features to
|
|
1103 make them more useful for many jobs that involve assigning information
|
|
1104 to character codes---for example, a char-table can have a parent to
|
|
1105 inherit from, a default value, and a small number of extra slots to use for
|
|
1106 special purposes. A char-table can also specify a single value for
|
|
1107 a whole character set.
|
|
1108
|
|
1109 The printed representation of a char-table is like a vector
|
21682
|
1110 except that there is an extra @samp{#^} at the beginning.
|
21007
|
1111
|
|
1112 @xref{Char-Tables}, for special functions to operate on char-tables.
|
21682
|
1113 Uses of char-tables include:
|
|
1114
|
|
1115 @itemize @bullet
|
|
1116 @item
|
|
1117 Case tables (@pxref{Case Tables}).
|
|
1118
|
|
1119 @item
|
|
1120 Character category tables (@pxref{Categories}).
|
|
1121
|
|
1122 @item
|
38788
|
1123 Display tables (@pxref{Display Tables}).
|
21682
|
1124
|
|
1125 @item
|
|
1126 Syntax tables (@pxref{Syntax Tables}).
|
|
1127 @end itemize
|
21007
|
1128
|
|
1129 @node Bool-Vector Type
|
|
1130 @subsection Bool-Vector Type
|
|
1131
|
|
1132 A @dfn{bool-vector} is a one-dimensional array of elements that
|
|
1133 must be @code{t} or @code{nil}.
|
|
1134
|
25751
|
1135 The printed representation of a bool-vector is like a string, except
|
21007
|
1136 that it begins with @samp{#&} followed by the length. The string
|
|
1137 constant that follows actually specifies the contents of the bool-vector
|
|
1138 as a bitmap---each ``character'' in the string contains 8 bits, which
|
|
1139 specify the next 8 elements of the bool-vector (1 stands for @code{t},
|
49600
|
1140 and 0 for @code{nil}). The least significant bits of the character
|
53217
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1141 correspond to the lowest indices in the bool-vector.
|
21007
|
1142
|
|
1143 @example
|
|
1144 (make-bool-vector 3 t)
|
53217
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1145 @result{} #&3"^G"
|
21007
|
1146 (make-bool-vector 3 nil)
|
53217
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1147 @result{} #&3"^@@"
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1148 @end example
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1149
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1150 @noindent
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1151 These results make sense, because the binary code for @samp{C-g} is
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1152 111 and @samp{C-@@} is the character with code 0.
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1153
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1154 If the length is not a multiple of 8, the printed representation
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1155 shows extra elements, but these extras really make no difference. For
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1156 instance, in the next example, the two bool-vectors are equal, because
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1157 only the first 3 bits are used:
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1158
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1159 @example
|
22138
|
1160 (equal #&3"\377" #&3"\007")
|
21682
|
1161 @result{} t
|
21007
|
1162 @end example
|
|
1163
|
25751
|
1164 @node Hash Table Type
|
|
1165 @subsection Hash Table Type
|
|
1166
|
|
1167 A hash table is a very fast kind of lookup table, somewhat like an
|
|
1168 alist in that it maps keys to corresponding values, but much faster.
|
60451
|
1169 Hash tables have no read syntax, and
|
25751
|
1170 print using hash notation. @xref{Hash Tables}.
|
|
1171
|
|
1172 @example
|
|
1173 (make-hash-table)
|
|
1174 @result{} #<hash-table 'eql nil 0/65 0x83af980>
|
|
1175 @end example
|
|
1176
|
7118
|
1177 @node Function Type
|
|
1178 @subsection Function Type
|
6447
|
1179
|
|
1180 Just as functions in other programming languages are executable,
|
|
1181 @dfn{Lisp function} objects are pieces of executable code. However,
|
|
1182 functions in Lisp are primarily Lisp objects, and only secondarily the
|
|
1183 text which represents them. These Lisp objects are lambda expressions:
|
|
1184 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
|
|
1185 Expressions}).
|
|
1186
|
|
1187 In most programming languages, it is impossible to have a function
|
|
1188 without a name. In Lisp, a function has no intrinsic name. A lambda
|
|
1189 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
|
|
1190 Functions}). A named function in Lisp is actually a symbol with a valid
|
|
1191 function in its function cell (@pxref{Defining Functions}).
|
|
1192
|
|
1193 Most of the time, functions are called when their names are written in
|
|
1194 Lisp expressions in Lisp programs. However, you can construct or obtain
|
|
1195 a function object at run time and then call it with the primitive
|
|
1196 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
|
|
1197
|
7118
|
1198 @node Macro Type
|
|
1199 @subsection Macro Type
|
6447
|
1200
|
|
1201 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
|
|
1202 language. It is represented as an object much like a function, but with
|
21682
|
1203 different argument-passing semantics. A Lisp macro has the form of a
|
6447
|
1204 list whose first element is the symbol @code{macro} and whose @sc{cdr}
|
|
1205 is a Lisp function object, including the @code{lambda} symbol.
|
|
1206
|
|
1207 Lisp macro objects are usually defined with the built-in
|
|
1208 @code{defmacro} function, but any list that begins with @code{macro} is
|
|
1209 a macro as far as Emacs is concerned. @xref{Macros}, for an explanation
|
|
1210 of how to write a macro.
|
|
1211
|
21007
|
1212 @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard
|
|
1213 Macros}) are entirely different things. When we use the word ``macro''
|
|
1214 without qualification, we mean a Lisp macro, not a keyboard macro.
|
|
1215
|
6447
|
1216 @node Primitive Function Type
|
|
1217 @subsection Primitive Function Type
|
|
1218 @cindex special forms
|
|
1219
|
|
1220 A @dfn{primitive function} is a function callable from Lisp but
|
|
1221 written in the C programming language. Primitive functions are also
|
|
1222 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
|
|
1223 derived from ``subroutine''.) Most primitive functions evaluate all
|
|
1224 their arguments when they are called. A primitive function that does
|
|
1225 not evaluate all its arguments is called a @dfn{special form}
|
|
1226 (@pxref{Special Forms}).@refill
|
|
1227
|
|
1228 It does not matter to the caller of a function whether the function is
|
21682
|
1229 primitive. However, this does matter if you try to redefine a primitive
|
|
1230 with a function written in Lisp. The reason is that the primitive
|
|
1231 function may be called directly from C code. Calls to the redefined
|
|
1232 function from Lisp will use the new definition, but calls from C code
|
|
1233 may still use the built-in definition. Therefore, @strong{we discourage
|
|
1234 redefinition of primitive functions}.
|
6447
|
1235
|
|
1236 The term @dfn{function} refers to all Emacs functions, whether written
|
7118
|
1237 in Lisp or C. @xref{Function Type}, for information about the
|
|
1238 functions written in Lisp.
|
6447
|
1239
|
|
1240 Primitive functions have no read syntax and print in hash notation
|
|
1241 with the name of the subroutine.
|
|
1242
|
|
1243 @example
|
|
1244 @group
|
|
1245 (symbol-function 'car) ; @r{Access the function cell}
|
|
1246 ; @r{of the symbol.}
|
|
1247 @result{} #<subr car>
|
|
1248 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
|
|
1249 @result{} t ; @r{Yes.}
|
|
1250 @end group
|
|
1251 @end example
|
|
1252
|
|
1253 @node Byte-Code Type
|
|
1254 @subsection Byte-Code Function Type
|
|
1255
|
|
1256 The byte compiler produces @dfn{byte-code function objects}.
|
|
1257 Internally, a byte-code function object is much like a vector; however,
|
|
1258 the evaluator handles this data type specially when it appears as a
|
|
1259 function to be called. @xref{Byte Compilation}, for information about
|
|
1260 the byte compiler.
|
|
1261
|
12098
|
1262 The printed representation and read syntax for a byte-code function
|
|
1263 object is like that for a vector, with an additional @samp{#} before the
|
|
1264 opening @samp{[}.
|
6447
|
1265
|
|
1266 @node Autoload Type
|
|
1267 @subsection Autoload Type
|
|
1268
|
|
1269 An @dfn{autoload object} is a list whose first element is the symbol
|
25751
|
1270 @code{autoload}. It is stored as the function definition of a symbol,
|
|
1271 where it serves as a placeholder for the real definition. The autoload
|
|
1272 object says that the real definition is found in a file of Lisp code
|
|
1273 that should be loaded when necessary. It contains the name of the file,
|
|
1274 plus some other information about the real definition.
|
6447
|
1275
|
|
1276 After the file has been loaded, the symbol should have a new function
|
|
1277 definition that is not an autoload object. The new definition is then
|
|
1278 called as if it had been there to begin with. From the user's point of
|
|
1279 view, the function call works as expected, using the function definition
|
|
1280 in the loaded file.
|
|
1281
|
|
1282 An autoload object is usually created with the function
|
|
1283 @code{autoload}, which stores the object in the function cell of a
|
|
1284 symbol. @xref{Autoload}, for more details.
|
|
1285
|
|
1286 @node Editing Types
|
|
1287 @section Editing Types
|
|
1288 @cindex editing types
|
|
1289
|
22138
|
1290 The types in the previous section are used for general programming
|
21682
|
1291 purposes, and most of them are common to most Lisp dialects. Emacs Lisp
|
|
1292 provides several additional data types for purposes connected with
|
|
1293 editing.
|
6447
|
1294
|
|
1295 @menu
|
|
1296 * Buffer Type:: The basic object of editing.
|
|
1297 * Marker Type:: A position in a buffer.
|
|
1298 * Window Type:: Buffers are displayed in windows.
|
|
1299 * Frame Type:: Windows subdivide frames.
|
|
1300 * Window Configuration Type:: Recording the way a frame is subdivided.
|
21682
|
1301 * Frame Configuration Type:: Recording the status of all frames.
|
6447
|
1302 * Process Type:: A process running on the underlying OS.
|
|
1303 * Stream Type:: Receive or send characters.
|
|
1304 * Keymap Type:: What function a keystroke invokes.
|
|
1305 * Overlay Type:: How an overlay is represented.
|
|
1306 @end menu
|
|
1307
|
|
1308 @node Buffer Type
|
|
1309 @subsection Buffer Type
|
|
1310
|
|
1311 A @dfn{buffer} is an object that holds text that can be edited
|
|
1312 (@pxref{Buffers}). Most buffers hold the contents of a disk file
|
|
1313 (@pxref{Files}) so they can be edited, but some are used for other
|
|
1314 purposes. Most buffers are also meant to be seen by the user, and
|
|
1315 therefore displayed, at some time, in a window (@pxref{Windows}). But a
|
|
1316 buffer need not be displayed in any window.
|
|
1317
|
|
1318 The contents of a buffer are much like a string, but buffers are not
|
|
1319 used like strings in Emacs Lisp, and the available operations are
|
21682
|
1320 different. For example, you can insert text efficiently into an
|
25751
|
1321 existing buffer, altering the buffer's contents, whereas ``inserting''
|
|
1322 text into a string requires concatenating substrings, and the result is
|
|
1323 an entirely new string object.
|
6447
|
1324
|
|
1325 Each buffer has a designated position called @dfn{point}
|
|
1326 (@pxref{Positions}). At any time, one buffer is the @dfn{current
|
|
1327 buffer}. Most editing commands act on the contents of the current
|
7118
|
1328 buffer in the neighborhood of point. Many of the standard Emacs
|
|
1329 functions manipulate or test the characters in the current buffer; a
|
|
1330 whole chapter in this manual is devoted to describing these functions
|
|
1331 (@pxref{Text}).
|
6447
|
1332
|
|
1333 Several other data structures are associated with each buffer:
|
|
1334
|
|
1335 @itemize @bullet
|
|
1336 @item
|
|
1337 a local syntax table (@pxref{Syntax Tables});
|
|
1338
|
|
1339 @item
|
|
1340 a local keymap (@pxref{Keymaps}); and,
|
|
1341
|
|
1342 @item
|
21682
|
1343 a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
|
12098
|
1344
|
|
1345 @item
|
21682
|
1346 overlays (@pxref{Overlays}).
|
12098
|
1347
|
|
1348 @item
|
|
1349 text properties for the text in the buffer (@pxref{Text Properties}).
|
6447
|
1350 @end itemize
|
|
1351
|
|
1352 @noindent
|
7118
|
1353 The local keymap and variable list contain entries that individually
|
6447
|
1354 override global bindings or values. These are used to customize the
|
|
1355 behavior of programs in different buffers, without actually changing the
|
|
1356 programs.
|
|
1357
|
12098
|
1358 A buffer may be @dfn{indirect}, which means it shares the text
|
21682
|
1359 of another buffer, but presents it differently. @xref{Indirect Buffers}.
|
12098
|
1360
|
|
1361 Buffers have no read syntax. They print in hash notation, showing the
|
6447
|
1362 buffer name.
|
|
1363
|
|
1364 @example
|
|
1365 @group
|
|
1366 (current-buffer)
|
|
1367 @result{} #<buffer objects.texi>
|
|
1368 @end group
|
|
1369 @end example
|
|
1370
|
|
1371 @node Marker Type
|
|
1372 @subsection Marker Type
|
|
1373
|
|
1374 A @dfn{marker} denotes a position in a specific buffer. Markers
|
|
1375 therefore have two components: one for the buffer, and one for the
|
|
1376 position. Changes in the buffer's text automatically relocate the
|
|
1377 position value as necessary to ensure that the marker always points
|
|
1378 between the same two characters in the buffer.
|
|
1379
|
|
1380 Markers have no read syntax. They print in hash notation, giving the
|
|
1381 current character position and the name of the buffer.
|
|
1382
|
|
1383 @example
|
|
1384 @group
|
|
1385 (point-marker)
|
|
1386 @result{} #<marker at 10779 in objects.texi>
|
|
1387 @end group
|
|
1388 @end example
|
|
1389
|
|
1390 @xref{Markers}, for information on how to test, create, copy, and move
|
|
1391 markers.
|
|
1392
|
|
1393 @node Window Type
|
|
1394 @subsection Window Type
|
|
1395
|
|
1396 A @dfn{window} describes the portion of the terminal screen that Emacs
|
|
1397 uses to display a buffer. Every window has one associated buffer, whose
|
|
1398 contents appear in the window. By contrast, a given buffer may appear
|
|
1399 in one window, no window, or several windows.
|
|
1400
|
|
1401 Though many windows may exist simultaneously, at any time one window
|
|
1402 is designated the @dfn{selected window}. This is the window where the
|
|
1403 cursor is (usually) displayed when Emacs is ready for a command. The
|
|
1404 selected window usually displays the current buffer, but this is not
|
|
1405 necessarily the case.
|
|
1406
|
|
1407 Windows are grouped on the screen into frames; each window belongs to
|
|
1408 one and only one frame. @xref{Frame Type}.
|
|
1409
|
|
1410 Windows have no read syntax. They print in hash notation, giving the
|
|
1411 window number and the name of the buffer being displayed. The window
|
|
1412 numbers exist to identify windows uniquely, since the buffer displayed
|
|
1413 in any given window can change frequently.
|
|
1414
|
|
1415 @example
|
|
1416 @group
|
|
1417 (selected-window)
|
|
1418 @result{} #<window 1 on objects.texi>
|
|
1419 @end group
|
|
1420 @end example
|
|
1421
|
|
1422 @xref{Windows}, for a description of the functions that work on windows.
|
|
1423
|
|
1424 @node Frame Type
|
|
1425 @subsection Frame Type
|
|
1426
|
22138
|
1427 A @dfn{frame} is a rectangle on the screen that contains one or more
|
6447
|
1428 Emacs windows. A frame initially contains a single main window (plus
|
|
1429 perhaps a minibuffer window) which you can subdivide vertically or
|
|
1430 horizontally into smaller windows.
|
|
1431
|
|
1432 Frames have no read syntax. They print in hash notation, giving the
|
|
1433 frame's title, plus its address in core (useful to identify the frame
|
|
1434 uniquely).
|
|
1435
|
|
1436 @example
|
|
1437 @group
|
|
1438 (selected-frame)
|
22138
|
1439 @result{} #<frame emacs@@psilocin.gnu.org 0xdac80>
|
6447
|
1440 @end group
|
|
1441 @end example
|
|
1442
|
|
1443 @xref{Frames}, for a description of the functions that work on frames.
|
|
1444
|
|
1445 @node Window Configuration Type
|
|
1446 @subsection Window Configuration Type
|
|
1447 @cindex screen layout
|
|
1448
|
|
1449 A @dfn{window configuration} stores information about the positions,
|
|
1450 sizes, and contents of the windows in a frame, so you can recreate the
|
|
1451 same arrangement of windows later.
|
|
1452
|
16736
|
1453 Window configurations do not have a read syntax; their print syntax
|
|
1454 looks like @samp{#<window-configuration>}. @xref{Window
|
|
1455 Configurations}, for a description of several functions related to
|
|
1456 window configurations.
|
6447
|
1457
|
21682
|
1458 @node Frame Configuration Type
|
|
1459 @subsection Frame Configuration Type
|
|
1460 @cindex screen layout
|
|
1461
|
|
1462 A @dfn{frame configuration} stores information about the positions,
|
|
1463 sizes, and contents of the windows in all frames. It is actually
|
|
1464 a list whose @sc{car} is @code{frame-configuration} and whose
|
|
1465 @sc{cdr} is an alist. Each alist element describes one frame,
|
|
1466 which appears as the @sc{car} of that element.
|
|
1467
|
|
1468 @xref{Frame Configurations}, for a description of several functions
|
|
1469 related to frame configurations.
|
|
1470
|
6447
|
1471 @node Process Type
|
|
1472 @subsection Process Type
|
|
1473
|
|
1474 The word @dfn{process} usually means a running program. Emacs itself
|
|
1475 runs in a process of this sort. However, in Emacs Lisp, a process is a
|
|
1476 Lisp object that designates a subprocess created by the Emacs process.
|
|
1477 Programs such as shells, GDB, ftp, and compilers, running in
|
|
1478 subprocesses of Emacs, extend the capabilities of Emacs.
|
|
1479
|
|
1480 An Emacs subprocess takes textual input from Emacs and returns textual
|
|
1481 output to Emacs for further manipulation. Emacs can also send signals
|
|
1482 to the subprocess.
|
|
1483
|
|
1484 Process objects have no read syntax. They print in hash notation,
|
|
1485 giving the name of the process:
|
|
1486
|
|
1487 @example
|
|
1488 @group
|
|
1489 (process-list)
|
|
1490 @result{} (#<process shell>)
|
|
1491 @end group
|
|
1492 @end example
|
|
1493
|
|
1494 @xref{Processes}, for information about functions that create, delete,
|
|
1495 return information about, send input or signals to, and receive output
|
|
1496 from processes.
|
|
1497
|
|
1498 @node Stream Type
|
|
1499 @subsection Stream Type
|
|
1500
|
|
1501 A @dfn{stream} is an object that can be used as a source or sink for
|
|
1502 characters---either to supply characters for input or to accept them as
|
|
1503 output. Many different types can be used this way: markers, buffers,
|
|
1504 strings, and functions. Most often, input streams (character sources)
|
|
1505 obtain characters from the keyboard, a buffer, or a file, and output
|
|
1506 streams (character sinks) send characters to a buffer, such as a
|
|
1507 @file{*Help*} buffer, or to the echo area.
|
|
1508
|
|
1509 The object @code{nil}, in addition to its other meanings, may be used
|
|
1510 as a stream. It stands for the value of the variable
|
|
1511 @code{standard-input} or @code{standard-output}. Also, the object
|
|
1512 @code{t} as a stream specifies input using the minibuffer
|
|
1513 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
|
|
1514 Area}).
|
|
1515
|
|
1516 Streams have no special printed representation or read syntax, and
|
|
1517 print as whatever primitive type they are.
|
|
1518
|
7337
|
1519 @xref{Read and Print}, for a description of functions
|
7118
|
1520 related to streams, including parsing and printing functions.
|
6447
|
1521
|
|
1522 @node Keymap Type
|
|
1523 @subsection Keymap Type
|
|
1524
|
|
1525 A @dfn{keymap} maps keys typed by the user to commands. This mapping
|
|
1526 controls how the user's command input is executed. A keymap is actually
|
|
1527 a list whose @sc{car} is the symbol @code{keymap}.
|
|
1528
|
|
1529 @xref{Keymaps}, for information about creating keymaps, handling prefix
|
|
1530 keys, local as well as global keymaps, and changing key bindings.
|
|
1531
|
|
1532 @node Overlay Type
|
|
1533 @subsection Overlay Type
|
|
1534
|
21007
|
1535 An @dfn{overlay} specifies properties that apply to a part of a
|
|
1536 buffer. Each overlay applies to a specified range of the buffer, and
|
|
1537 contains a property list (a list whose elements are alternating property
|
|
1538 names and values). Overlay properties are used to present parts of the
|
|
1539 buffer temporarily in a different display style. Overlays have no read
|
|
1540 syntax, and print in hash notation, giving the buffer name and range of
|
|
1541 positions.
|
6447
|
1542
|
12098
|
1543 @xref{Overlays}, for how to create and use overlays.
|
6447
|
1544
|
25751
|
1545 @node Circular Objects
|
|
1546 @section Read Syntax for Circular Objects
|
|
1547 @cindex circular structure, read syntax
|
|
1548 @cindex shared structure, read syntax
|
|
1549 @cindex @samp{#@var{n}=} read syntax
|
|
1550 @cindex @samp{#@var{n}#} read syntax
|
|
1551
|
60451
|
1552 To represent shared or circular structures within a complex of Lisp
|
|
1553 objects, you can use the reader constructs @samp{#@var{n}=} and
|
|
1554 @samp{#@var{n}#}.
|
25751
|
1555
|
|
1556 Use @code{#@var{n}=} before an object to label it for later reference;
|
|
1557 subsequently, you can use @code{#@var{n}#} to refer the same object in
|
|
1558 another place. Here, @var{n} is some integer. For example, here is how
|
|
1559 to make a list in which the first element recurs as the third element:
|
|
1560
|
|
1561 @example
|
|
1562 (#1=(a) b #1#)
|
|
1563 @end example
|
|
1564
|
|
1565 @noindent
|
|
1566 This differs from ordinary syntax such as this
|
|
1567
|
|
1568 @example
|
|
1569 ((a) b (a))
|
|
1570 @end example
|
|
1571
|
|
1572 @noindent
|
|
1573 which would result in a list whose first and third elements
|
|
1574 look alike but are not the same Lisp object. This shows the difference:
|
|
1575
|
|
1576 @example
|
|
1577 (prog1 nil
|
|
1578 (setq x '(#1=(a) b #1#)))
|
|
1579 (eq (nth 0 x) (nth 2 x))
|
|
1580 @result{} t
|
|
1581 (setq x '((a) b (a)))
|
|
1582 (eq (nth 0 x) (nth 2 x))
|
|
1583 @result{} nil
|
|
1584 @end example
|
|
1585
|
|
1586 You can also use the same syntax to make a circular structure, which
|
|
1587 appears as an ``element'' within itself. Here is an example:
|
|
1588
|
|
1589 @example
|
|
1590 #1=(a #1#)
|
|
1591 @end example
|
|
1592
|
|
1593 @noindent
|
|
1594 This makes a list whose second element is the list itself.
|
|
1595 Here's how you can see that it really works:
|
|
1596
|
|
1597 @example
|
|
1598 (prog1 nil
|
|
1599 (setq x '#1=(a #1#)))
|
|
1600 (eq x (cadr x))
|
|
1601 @result{} t
|
|
1602 @end example
|
|
1603
|
|
1604 The Lisp printer can produce this syntax to record circular and shared
|
|
1605 structure in a Lisp object, if you bind the variable @code{print-circle}
|
|
1606 to a non-@code{nil} value. @xref{Output Variables}.
|
|
1607
|
6447
|
1608 @node Type Predicates
|
|
1609 @section Type Predicates
|
|
1610 @cindex predicates
|
|
1611 @cindex type checking
|
|
1612 @kindex wrong-type-argument
|
|
1613
|
|
1614 The Emacs Lisp interpreter itself does not perform type checking on
|
|
1615 the actual arguments passed to functions when they are called. It could
|
|
1616 not do so, since function arguments in Lisp do not have declared data
|
|
1617 types, as they do in other programming languages. It is therefore up to
|
|
1618 the individual function to test whether each actual argument belongs to
|
|
1619 a type that the function can use.
|
|
1620
|
|
1621 All built-in functions do check the types of their actual arguments
|
|
1622 when appropriate, and signal a @code{wrong-type-argument} error if an
|
|
1623 argument is of the wrong type. For example, here is what happens if you
|
7118
|
1624 pass an argument to @code{+} that it cannot handle:
|
6447
|
1625
|
|
1626 @example
|
|
1627 @group
|
|
1628 (+ 2 'a)
|
21007
|
1629 @error{} Wrong type argument: number-or-marker-p, a
|
6447
|
1630 @end group
|
|
1631 @end example
|
|
1632
|
|
1633 @cindex type predicates
|
|
1634 @cindex testing types
|
12067
|
1635 If you want your program to handle different types differently, you
|
|
1636 must do explicit type checking. The most common way to check the type
|
|
1637 of an object is to call a @dfn{type predicate} function. Emacs has a
|
|
1638 type predicate for each type, as well as some predicates for
|
|
1639 combinations of types.
|
|
1640
|
|
1641 A type predicate function takes one argument; it returns @code{t} if
|
|
1642 the argument belongs to the appropriate type, and @code{nil} otherwise.
|
|
1643 Following a general Lisp convention for predicate functions, most type
|
|
1644 predicates' names end with @samp{p}.
|
|
1645
|
|
1646 Here is an example which uses the predicates @code{listp} to check for
|
|
1647 a list and @code{symbolp} to check for a symbol.
|
6447
|
1648
|
12067
|
1649 @example
|
|
1650 (defun add-on (x)
|
|
1651 (cond ((symbolp x)
|
|
1652 ;; If X is a symbol, put it on LIST.
|
|
1653 (setq list (cons x list)))
|
|
1654 ((listp x)
|
|
1655 ;; If X is a list, add its elements to LIST.
|
|
1656 (setq list (append x list)))
|
|
1657 (t
|
21682
|
1658 ;; We handle only symbols and lists.
|
12067
|
1659 (error "Invalid argument %s in add-on" x))))
|
|
1660 @end example
|
|
1661
|
|
1662 Here is a table of predefined type predicates, in alphabetical order,
|
6447
|
1663 with references to further information.
|
|
1664
|
|
1665 @table @code
|
|
1666 @item atom
|
|
1667 @xref{List-related Predicates, atom}.
|
|
1668
|
|
1669 @item arrayp
|
|
1670 @xref{Array Functions, arrayp}.
|
|
1671
|
21682
|
1672 @item bool-vector-p
|
|
1673 @xref{Bool-Vectors, bool-vector-p}.
|
|
1674
|
6447
|
1675 @item bufferp
|
|
1676 @xref{Buffer Basics, bufferp}.
|
|
1677
|
|
1678 @item byte-code-function-p
|
|
1679 @xref{Byte-Code Type, byte-code-function-p}.
|
|
1680
|
|
1681 @item case-table-p
|
21682
|
1682 @xref{Case Tables, case-table-p}.
|
6447
|
1683
|
|
1684 @item char-or-string-p
|
|
1685 @xref{Predicates for Strings, char-or-string-p}.
|
|
1686
|
21682
|
1687 @item char-table-p
|
|
1688 @xref{Char-Tables, char-table-p}.
|
|
1689
|
6447
|
1690 @item commandp
|
|
1691 @xref{Interactive Call, commandp}.
|
|
1692
|
|
1693 @item consp
|
|
1694 @xref{List-related Predicates, consp}.
|
|
1695
|
21682
|
1696 @item display-table-p
|
|
1697 @xref{Display Tables, display-table-p}.
|
|
1698
|
6447
|
1699 @item floatp
|
|
1700 @xref{Predicates on Numbers, floatp}.
|
|
1701
|
21682
|
1702 @item frame-configuration-p
|
|
1703 @xref{Frame Configurations, frame-configuration-p}.
|
|
1704
|
6447
|
1705 @item frame-live-p
|
|
1706 @xref{Deleting Frames, frame-live-p}.
|
|
1707
|
|
1708 @item framep
|
|
1709 @xref{Frames, framep}.
|
|
1710
|
21007
|
1711 @item functionp
|
|
1712 @xref{Functions, functionp}.
|
|
1713
|
60044
|
1714 @item hash-table-p
|
|
1715 @xref{Other Hash, hash-table-p}.
|
|
1716
|
6447
|
1717 @item integer-or-marker-p
|
|
1718 @xref{Predicates on Markers, integer-or-marker-p}.
|
|
1719
|
|
1720 @item integerp
|
|
1721 @xref{Predicates on Numbers, integerp}.
|
|
1722
|
|
1723 @item keymapp
|
|
1724 @xref{Creating Keymaps, keymapp}.
|
|
1725
|
27528
|
1726 @item keywordp
|
|
1727 @xref{Constant Variables}.
|
|
1728
|
6447
|
1729 @item listp
|
|
1730 @xref{List-related Predicates, listp}.
|
|
1731
|
|
1732 @item markerp
|
|
1733 @xref{Predicates on Markers, markerp}.
|
|
1734
|
7118
|
1735 @item wholenump
|
|
1736 @xref{Predicates on Numbers, wholenump}.
|
6447
|
1737
|
|
1738 @item nlistp
|
|
1739 @xref{List-related Predicates, nlistp}.
|
|
1740
|
|
1741 @item numberp
|
|
1742 @xref{Predicates on Numbers, numberp}.
|
|
1743
|
|
1744 @item number-or-marker-p
|
|
1745 @xref{Predicates on Markers, number-or-marker-p}.
|
|
1746
|
|
1747 @item overlayp
|
|
1748 @xref{Overlays, overlayp}.
|
|
1749
|
|
1750 @item processp
|
|
1751 @xref{Processes, processp}.
|
|
1752
|
|
1753 @item sequencep
|
|
1754 @xref{Sequence Functions, sequencep}.
|
|
1755
|
|
1756 @item stringp
|
|
1757 @xref{Predicates for Strings, stringp}.
|
|
1758
|
|
1759 @item subrp
|
|
1760 @xref{Function Cells, subrp}.
|
|
1761
|
|
1762 @item symbolp
|
|
1763 @xref{Symbols, symbolp}.
|
|
1764
|
|
1765 @item syntax-table-p
|
|
1766 @xref{Syntax Tables, syntax-table-p}.
|
|
1767
|
|
1768 @item user-variable-p
|
|
1769 @xref{Defining Variables, user-variable-p}.
|
|
1770
|
|
1771 @item vectorp
|
|
1772 @xref{Vectors, vectorp}.
|
|
1773
|
|
1774 @item window-configuration-p
|
|
1775 @xref{Window Configurations, window-configuration-p}.
|
|
1776
|
|
1777 @item window-live-p
|
|
1778 @xref{Deleting Windows, window-live-p}.
|
|
1779
|
|
1780 @item windowp
|
|
1781 @xref{Basic Windows, windowp}.
|
|
1782 @end table
|
|
1783
|
12067
|
1784 The most general way to check the type of an object is to call the
|
|
1785 function @code{type-of}. Recall that each object belongs to one and
|
|
1786 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
|
|
1787 Data Types}). But @code{type-of} knows nothing about non-primitive
|
|
1788 types. In most cases, it is more convenient to use type predicates than
|
|
1789 @code{type-of}.
|
|
1790
|
|
1791 @defun type-of object
|
|
1792 This function returns a symbol naming the primitive type of
|
16736
|
1793 @var{object}. The value is one of the symbols @code{symbol},
|
|
1794 @code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector},
|
26188
|
1795 @code{char-table}, @code{bool-vector}, @code{hash-table}, @code{subr},
|
21682
|
1796 @code{compiled-function}, @code{marker}, @code{overlay}, @code{window},
|
|
1797 @code{buffer}, @code{frame}, @code{process}, or
|
16736
|
1798 @code{window-configuration}.
|
12067
|
1799
|
|
1800 @example
|
|
1801 (type-of 1)
|
|
1802 @result{} integer
|
|
1803 (type-of 'nil)
|
|
1804 @result{} symbol
|
|
1805 (type-of '()) ; @r{@code{()} is @code{nil}.}
|
|
1806 @result{} symbol
|
|
1807 (type-of '(x))
|
|
1808 @result{} cons
|
|
1809 @end example
|
|
1810 @end defun
|
|
1811
|
6447
|
1812 @node Equality Predicates
|
|
1813 @section Equality Predicates
|
|
1814 @cindex equality
|
|
1815
|
|
1816 Here we describe two functions that test for equality between any two
|
|
1817 objects. Other functions test equality between objects of specific
|
7118
|
1818 types, e.g., strings. For these predicates, see the appropriate chapter
|
|
1819 describing the data type.
|
6447
|
1820
|
|
1821 @defun eq object1 object2
|
|
1822 This function returns @code{t} if @var{object1} and @var{object2} are
|
63763
|
1823 the same object, @code{nil} otherwise.
|
6447
|
1824
|
|
1825 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
|
|
1826 integers with the same value. Also, since symbol names are normally
|
|
1827 unique, if the arguments are symbols with the same name, they are
|
|
1828 @code{eq}. For other types (e.g., lists, vectors, strings), two
|
|
1829 arguments with the same contents or elements are not necessarily
|
|
1830 @code{eq} to each other: they are @code{eq} only if they are the same
|
63763
|
1831 object, meaning that a change in the contents of one will be reflected
|
|
1832 by the same change in the contents of the other.
|
6447
|
1833
|
|
1834 @example
|
|
1835 @group
|
|
1836 (eq 'foo 'foo)
|
|
1837 @result{} t
|
|
1838 @end group
|
|
1839
|
|
1840 @group
|
|
1841 (eq 456 456)
|
|
1842 @result{} t
|
|
1843 @end group
|
|
1844
|
|
1845 @group
|
|
1846 (eq "asdf" "asdf")
|
|
1847 @result{} nil
|
|
1848 @end group
|
|
1849
|
|
1850 @group
|
|
1851 (eq '(1 (2 (3))) '(1 (2 (3))))
|
|
1852 @result{} nil
|
|
1853 @end group
|
|
1854
|
|
1855 @group
|
|
1856 (setq foo '(1 (2 (3))))
|
|
1857 @result{} (1 (2 (3)))
|
|
1858 (eq foo foo)
|
|
1859 @result{} t
|
|
1860 (eq foo '(1 (2 (3))))
|
|
1861 @result{} nil
|
|
1862 @end group
|
|
1863
|
|
1864 @group
|
|
1865 (eq [(1 2) 3] [(1 2) 3])
|
|
1866 @result{} nil
|
|
1867 @end group
|
|
1868
|
|
1869 @group
|
|
1870 (eq (point-marker) (point-marker))
|
|
1871 @result{} nil
|
|
1872 @end group
|
|
1873 @end example
|
|
1874
|
22138
|
1875 The @code{make-symbol} function returns an uninterned symbol, distinct
|
|
1876 from the symbol that is used if you write the name in a Lisp expression.
|
|
1877 Distinct symbols with the same name are not @code{eq}. @xref{Creating
|
|
1878 Symbols}.
|
21682
|
1879
|
|
1880 @example
|
|
1881 @group
|
|
1882 (eq (make-symbol "foo") 'foo)
|
|
1883 @result{} nil
|
|
1884 @end group
|
|
1885 @end example
|
6447
|
1886 @end defun
|
|
1887
|
|
1888 @defun equal object1 object2
|
|
1889 This function returns @code{t} if @var{object1} and @var{object2} have
|
|
1890 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
|
|
1891 arguments are the same object, @code{equal} looks inside nonidentical
|
26188
|
1892 arguments to see if their elements or contents are the same. So, if two
|
|
1893 objects are @code{eq}, they are @code{equal}, but the converse is not
|
|
1894 always true.
|
6447
|
1895
|
|
1896 @example
|
|
1897 @group
|
|
1898 (equal 'foo 'foo)
|
|
1899 @result{} t
|
|
1900 @end group
|
|
1901
|
|
1902 @group
|
|
1903 (equal 456 456)
|
|
1904 @result{} t
|
|
1905 @end group
|
|
1906
|
|
1907 @group
|
|
1908 (equal "asdf" "asdf")
|
|
1909 @result{} t
|
|
1910 @end group
|
|
1911 @group
|
|
1912 (eq "asdf" "asdf")
|
|
1913 @result{} nil
|
|
1914 @end group
|
|
1915
|
|
1916 @group
|
|
1917 (equal '(1 (2 (3))) '(1 (2 (3))))
|
|
1918 @result{} t
|
|
1919 @end group
|
|
1920 @group
|
|
1921 (eq '(1 (2 (3))) '(1 (2 (3))))
|
|
1922 @result{} nil
|
|
1923 @end group
|
|
1924
|
|
1925 @group
|
|
1926 (equal [(1 2) 3] [(1 2) 3])
|
|
1927 @result{} t
|
|
1928 @end group
|
|
1929 @group
|
|
1930 (eq [(1 2) 3] [(1 2) 3])
|
|
1931 @result{} nil
|
|
1932 @end group
|
|
1933
|
|
1934 @group
|
|
1935 (equal (point-marker) (point-marker))
|
|
1936 @result{} t
|
|
1937 @end group
|
|
1938
|
|
1939 @group
|
|
1940 (eq (point-marker) (point-marker))
|
|
1941 @result{} nil
|
|
1942 @end group
|
|
1943 @end example
|
|
1944
|
21007
|
1945 Comparison of strings is case-sensitive, but does not take account of
|
53217
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1946 text properties---it compares only the characters in the strings. For
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1947 technical reasons, a unibyte string and a multibyte string are
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1948 @code{equal} if and only if they contain the same sequence of
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1949 character codes and all these codes are either in the range 0 through
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1950 127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
|
80af4875c661
(Non-ASCII in Strings): Clarify description of when a string is
Luc Teirlinck <teirllm@auburn.edu>
diff
changeset
|
1951 (@pxref{Text Representations}).
|
6447
|
1952
|
|
1953 @example
|
|
1954 @group
|
|
1955 (equal "asdf" "ASDF")
|
|
1956 @result{} nil
|
|
1957 @end group
|
|
1958 @end example
|
12098
|
1959
|
26188
|
1960 However, two distinct buffers are never considered @code{equal}, even if
|
|
1961 their textual contents are the same.
|
6447
|
1962 @end defun
|
|
1963
|
26188
|
1964 The test for equality is implemented recursively; for example, given
|
|
1965 two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})}
|
|
1966 returns @code{t} if and only if both the expressions below return
|
|
1967 @code{t}:
|
|
1968
|
|
1969 @example
|
|
1970 (equal (car @var{x}) (car @var{y}))
|
|
1971 (equal (cdr @var{x}) (cdr @var{y}))
|
|
1972 @end example
|
|
1973
|
|
1974 Because of this recursive method, circular lists may therefore cause
|
|
1975 infinite recursion (leading to an error).
|
52401
|
1976
|
|
1977 @ignore
|
|
1978 arch-tag: 9711a66e-4749-4265-9e8c-972d55b67096
|
|
1979 @end ignore
|