6447
|
1 @c -*-texinfo-*-
|
|
2 @c This is part of the GNU Emacs Lisp Reference Manual.
|
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
|
|
4 @c See the file elisp.texi for copying conditions.
|
|
5 @setfilename ../info/objects
|
7118
|
6 @node Lisp Data Types, Numbers, Introduction, Top
|
6447
|
7 @chapter Lisp Data Types
|
|
8 @cindex object
|
|
9 @cindex Lisp object
|
|
10 @cindex type
|
|
11 @cindex data type
|
|
12
|
|
13 A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
|
|
14 programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of
|
|
15 possible objects.
|
|
16
|
|
17 Every object belongs to at least one type. Objects of the same type
|
|
18 have similar structures and may usually be used in the same contexts.
|
|
19 Types can overlap, and objects can belong to two or more types.
|
|
20 Consequently, we can ask whether an object belongs to a particular type,
|
|
21 but not for ``the'' type of an object.
|
|
22
|
|
23 @cindex primitive type
|
|
24 A few fundamental object types are built into Emacs. These, from
|
|
25 which all other types are constructed, are called @dfn{primitive
|
|
26 types}. Each object belongs to one and only one primitive type. These
|
|
27 types include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
|
|
28 @dfn{string}, @dfn{vector}, @dfn{subr}, @dfn{byte-code function}, and
|
|
29 several special types, such as @dfn{buffer}, that are related to
|
|
30 editing. (@xref{Editing Types}.)
|
|
31
|
|
32 Each primitive type has a corresponding Lisp function that checks
|
|
33 whether an object is a member of that type.
|
|
34
|
|
35 Note that Lisp is unlike many other languages in that Lisp objects are
|
|
36 @dfn{self-typing}: the primitive type of the object is implicit in the
|
|
37 object itself. For example, if an object is a vector, nothing can treat
|
|
38 it as a number; Lisp knows it is a vector, not a number.
|
|
39
|
|
40 In most languages, the programmer must declare the data type of each
|
|
41 variable, and the type is known by the compiler but not represented in
|
|
42 the data. Such type declarations do not exist in Emacs Lisp. A Lisp
|
7118
|
43 variable can have any type of value, and it remembers whatever value
|
|
44 you store in it, type and all.
|
6447
|
45
|
|
46 This chapter describes the purpose, printed representation, and read
|
|
47 syntax of each of the standard types in GNU Emacs Lisp. Details on how
|
|
48 to use these types can be found in later chapters.
|
|
49
|
|
50 @menu
|
|
51 * Printed Representation:: How Lisp objects are represented as text.
|
|
52 * Comments:: Comments and their formatting conventions.
|
|
53 * Programming Types:: Types found in all Lisp systems.
|
|
54 * Editing Types:: Types specific to Emacs.
|
|
55 * Type Predicates:: Tests related to types.
|
|
56 * Equality Predicates:: Tests of equality between any two objects.
|
|
57 @end menu
|
|
58
|
|
59 @node Printed Representation
|
|
60 @comment node-name, next, previous, up
|
|
61 @section Printed Representation and Read Syntax
|
|
62 @cindex printed representation
|
|
63 @cindex read syntax
|
|
64
|
|
65 The @dfn{printed representation} of an object is the format of the
|
|
66 output generated by the Lisp printer (the function @code{prin1}) for
|
|
67 that object. The @dfn{read syntax} of an object is the format of the
|
|
68 input accepted by the Lisp reader (the function @code{read}) for that
|
|
69 object. Most objects have more than one possible read syntax. Some
|
|
70 types of object have no read syntax; except for these cases, the printed
|
|
71 representation of an object is also a read syntax for it.
|
|
72
|
|
73 In other languages, an expression is text; it has no other form. In
|
|
74 Lisp, an expression is primarily a Lisp object and only secondarily the
|
|
75 text that is the object's read syntax. Often there is no need to
|
|
76 emphasize this distinction, but you must keep it in the back of your
|
|
77 mind, or you will occasionally be very confused.
|
|
78
|
|
79 @cindex hash notation
|
|
80 Every type has a printed representation. Some types have no read
|
|
81 syntax, since it may not make sense to enter objects of these types
|
|
82 directly in a Lisp program. For example, the buffer type does not have
|
|
83 a read syntax. Objects of these types are printed in @dfn{hash
|
|
84 notation}: the characters @samp{#<} followed by a descriptive string
|
|
85 (typically the type name followed by the name of the object), and closed
|
|
86 with a matching @samp{>}. Hash notation cannot be read at all, so the
|
|
87 Lisp reader signals the error @code{invalid-read-syntax} whenever it
|
|
88 encounters @samp{#<}.
|
|
89 @kindex invalid-read-syntax
|
|
90
|
|
91 @example
|
|
92 (current-buffer)
|
|
93 @result{} #<buffer objects.texi>
|
|
94 @end example
|
|
95
|
|
96 When you evaluate an expression interactively, the Lisp interpreter
|
|
97 first reads the textual representation of it, producing a Lisp object,
|
|
98 and then evaluates that object (@pxref{Evaluation}). However,
|
|
99 evaluation and reading are separate activities. Reading returns the
|
|
100 Lisp object represented by the text that is read; the object may or may
|
|
101 not be evaluated later. @xref{Input Functions}, for a description of
|
|
102 @code{read}, the basic function for reading objects.
|
|
103
|
|
104 @node Comments
|
|
105 @comment node-name, next, previous, up
|
|
106 @section Comments
|
|
107 @cindex comments
|
|
108 @cindex @samp{;} in comment
|
|
109
|
|
110 A @dfn{comment} is text that is written in a program only for the sake
|
|
111 of humans that read the program, and that has no effect on the meaning
|
|
112 of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
|
|
113 is not within a string or character constant. The comment continues to
|
|
114 the end of line. The Lisp reader discards comments; they do not become
|
|
115 part of the Lisp objects which represent the program within the Lisp
|
|
116 system.
|
|
117
|
12098
|
118 The @samp{#@@@var{count}} construct, which skips the next @var{count}
|
|
119 characters, is useful for program-generated comments containing binary
|
|
120 data. The Emacs Lisp byte compiler uses this in its output files
|
|
121 (@pxref{Byte Compilation}). It isn't meant for source files, however.
|
|
122
|
6447
|
123 @xref{Comment Tips}, for conventions for formatting comments.
|
|
124
|
|
125 @node Programming Types
|
|
126 @section Programming Types
|
|
127 @cindex programming types
|
|
128
|
|
129 There are two general categories of types in Emacs Lisp: those having
|
|
130 to do with Lisp programming, and those having to do with editing. The
|
|
131 former exist in many Lisp implementations, in one form or another. The
|
|
132 latter are unique to Emacs Lisp.
|
|
133
|
|
134 @menu
|
|
135 * Integer Type:: Numbers without fractional parts.
|
|
136 * Floating Point Type:: Numbers with fractional parts and with a large range.
|
|
137 * Character Type:: The representation of letters, numbers and
|
|
138 control characters.
|
7337
|
139 * Symbol Type:: A multi-use object that refers to a function,
|
|
140 variable, or property list, and has a unique identity.
|
6447
|
141 * Sequence Type:: Both lists and arrays are classified as sequences.
|
7118
|
142 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
|
6447
|
143 * Array Type:: Arrays include strings and vectors.
|
|
144 * String Type:: An (efficient) array of characters.
|
|
145 * Vector Type:: One-dimensional arrays.
|
7337
|
146 * Function Type:: A piece of executable code you can call from elsewhere.
|
|
147 * Macro Type:: A method of expanding an expression into another
|
6447
|
148 expression, more fundamental but less pretty.
|
|
149 * Primitive Function Type:: A function written in C, callable from Lisp.
|
|
150 * Byte-Code Type:: A function written in Lisp, then compiled.
|
|
151 * Autoload Type:: A type used for automatically loading seldom-used
|
|
152 functions.
|
|
153 @end menu
|
|
154
|
|
155 @node Integer Type
|
|
156 @subsection Integer Type
|
|
157
|
10559
|
158 The range of values for integers in Emacs Lisp is @minus{}134217728 to
|
|
159 134217727 (28 bits; i.e.,
|
6447
|
160 @ifinfo
|
10559
|
161 -2**27
|
6447
|
162 @end ifinfo
|
|
163 @tex
|
10559
|
164 $-2^{27}$
|
6447
|
165 @end tex
|
|
166 to
|
|
167 @ifinfo
|
10559
|
168 2**27 - 1)
|
6447
|
169 @end ifinfo
|
|
170 @tex
|
10559
|
171 $2^{28}-1$)
|
6447
|
172 @end tex
|
10559
|
173 on most machines. (Some machines may provide a wider range.) It is
|
|
174 important to note that the Emacs Lisp arithmetic functions do not check
|
|
175 for overflow. Thus @code{(1+ 134217727)} is @minus{}134217728 on most
|
|
176 machines.
|
6447
|
177
|
7118
|
178 The read syntax for integers is a sequence of (base ten) digits with an
|
6447
|
179 optional sign at the beginning and an optional period at the end. The
|
|
180 printed representation produced by the Lisp interpreter never has a
|
|
181 leading @samp{+} or a final @samp{.}.
|
|
182
|
|
183 @example
|
|
184 @group
|
|
185 -1 ; @r{The integer -1.}
|
|
186 1 ; @r{The integer 1.}
|
|
187 1. ; @r{Also The integer 1.}
|
|
188 +1 ; @r{Also the integer 1.}
|
10559
|
189 268435457 ; @r{Also the integer 1!}
|
|
190 ; @r{ (on a 28-bit implementation)}
|
6447
|
191 @end group
|
|
192 @end example
|
|
193
|
|
194 @xref{Numbers}, for more information.
|
|
195
|
|
196 @node Floating Point Type
|
|
197 @subsection Floating Point Type
|
|
198
|
|
199 Emacs version 19 supports floating point numbers (though there is a
|
|
200 compilation option to disable them). The precise range of floating
|
|
201 point numbers is machine-specific.
|
|
202
|
|
203 The printed representation for floating point numbers requires either
|
|
204 a decimal point (with at least one digit following), an exponent, or
|
|
205 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
|
|
206 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
|
|
207 number whose value is 1500. They are all equivalent.
|
|
208
|
|
209 @xref{Numbers}, for more information.
|
|
210
|
|
211 @node Character Type
|
|
212 @subsection Character Type
|
|
213 @cindex @sc{ASCII} character codes
|
|
214
|
|
215 A @dfn{character} in Emacs Lisp is nothing more than an integer. In
|
|
216 other words, characters are represented by their character codes. For
|
|
217 example, the character @kbd{A} is represented as the @w{integer 65}.
|
|
218
|
|
219 Individual characters are not often used in programs. It is far more
|
|
220 common to work with @emph{strings}, which are sequences composed of
|
|
221 characters. @xref{String Type}.
|
|
222
|
|
223 Characters in strings, buffers, and files are currently limited to the
|
|
224 range of 0 to 255---eight bits. If you store a larger integer into a
|
|
225 string, buffer or file, it is truncated to that range. Characters that
|
|
226 represent keyboard input have a much wider range.
|
|
227
|
|
228 @cindex read syntax for characters
|
|
229 @cindex printed representation for characters
|
|
230 @cindex syntax for characters
|
|
231 Since characters are really integers, the printed representation of a
|
|
232 character is a decimal number. This is also a possible read syntax for
|
|
233 a character, but writing characters that way in Lisp programs is a very
|
|
234 bad idea. You should @emph{always} use the special read syntax formats
|
|
235 that Emacs Lisp provides for characters. These syntax formats start
|
|
236 with a question mark.
|
|
237
|
|
238 The usual read syntax for alphanumeric characters is a question mark
|
|
239 followed by the character; thus, @samp{?A} for the character
|
|
240 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
|
|
241 character @kbd{a}.
|
|
242
|
|
243 For example:
|
|
244
|
|
245 @example
|
|
246 ?Q @result{} 81 ?q @result{} 113
|
|
247 @end example
|
|
248
|
|
249 You can use the same syntax for punctuation characters, but it is
|
7118
|
250 often a good idea to add a @samp{\} so that the Emacs commands for
|
|
251 editing Lisp code don't get confused. For example, @samp{?\ } is the
|
|
252 way to write the space character. If the character is @samp{\}, you
|
|
253 @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
|
6447
|
254
|
|
255 @cindex whitespace
|
|
256 @cindex bell character
|
|
257 @cindex @samp{\a}
|
|
258 @cindex backspace
|
|
259 @cindex @samp{\b}
|
|
260 @cindex tab
|
|
261 @cindex @samp{\t}
|
|
262 @cindex vertical tab
|
|
263 @cindex @samp{\v}
|
|
264 @cindex formfeed
|
|
265 @cindex @samp{\f}
|
|
266 @cindex newline
|
|
267 @cindex @samp{\n}
|
|
268 @cindex return
|
|
269 @cindex @samp{\r}
|
|
270 @cindex escape
|
|
271 @cindex @samp{\e}
|
|
272 You can express the characters Control-g, backspace, tab, newline,
|
|
273 vertical tab, formfeed, return, and escape as @samp{?\a}, @samp{?\b},
|
|
274 @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e},
|
|
275 respectively. Those values are 7, 8, 9, 10, 11, 12, 13, and 27 in
|
|
276 decimal. Thus,
|
|
277
|
|
278 @example
|
|
279 ?\a @result{} 7 ; @r{@kbd{C-g}}
|
|
280 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
|
|
281 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
|
|
282 ?\n @result{} 10 ; @r{newline, @key{LFD}, @kbd{C-j}}
|
|
283 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
|
|
284 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
|
|
285 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
|
|
286 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
|
|
287 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
|
|
288 @end example
|
|
289
|
|
290 @cindex escape sequence
|
|
291 These sequences which start with backslash are also known as
|
|
292 @dfn{escape sequences}, because backslash plays the role of an escape
|
|
293 character; this usage has nothing to do with the character @key{ESC}.
|
|
294
|
|
295 @cindex control characters
|
|
296 Control characters may be represented using yet another read syntax.
|
|
297 This consists of a question mark followed by a backslash, caret, and the
|
|
298 corresponding non-control character, in either upper or lower case. For
|
|
299 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
|
|
300 character @kbd{C-i}, the character whose value is 9.
|
|
301
|
|
302 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
|
|
303 equivalent to @samp{?\^I} and to @samp{?\^i}:
|
|
304
|
|
305 @example
|
|
306 ?\^I @result{} 9 ?\C-I @result{} 9
|
|
307 @end example
|
|
308
|
|
309 For use in strings and buffers, you are limited to the control
|
|
310 characters that exist in @sc{ASCII}, but for keyboard input purposes,
|
|
311 you can turn any character into a control character with @samp{C-}. The
|
|
312 character codes for these non-@sc{ASCII} control characters include the
|
12098
|
313 @iftex
|
|
314 $2^{26}$
|
|
315 @end iftex
|
|
316 @ifinfo
|
|
317 2**26
|
|
318 @end ifinfo
|
|
319 bit as well as the code for the corresponding non-control
|
6447
|
320 character. Ordinary terminals have no way of generating non-@sc{ASCII}
|
|
321 control characters, but you can generate them straightforwardly using an
|
|
322 X terminal.
|
|
323
|
12098
|
324 For historical reasons, Emacs treats the @key{DEL} character as
|
|
325 the control equivalent of @kbd{?}:
|
6447
|
326
|
|
327 @example
|
|
328 ?\^? @result{} 127 ?\C-? @result{} 127
|
|
329 @end example
|
|
330
|
12098
|
331 @noindent
|
|
332 As a result, it is currently not possible to represent the character
|
|
333 @kbd{Control-?}, which is a meaningful input character under X. It is
|
|
334 not easy to change this as various Lisp files refer to @key{DEL} in this
|
|
335 way.
|
|
336
|
6447
|
337 For representing control characters to be found in files or strings,
|
|
338 we recommend the @samp{^} syntax; for control characters in keyboard
|
|
339 input, we prefer the @samp{C-} syntax. This does not affect the meaning
|
|
340 of the program, but may guide the understanding of people who read it.
|
|
341
|
|
342 @cindex meta characters
|
|
343 A @dfn{meta character} is a character typed with the @key{META}
|
|
344 modifier key. The integer that represents such a character has the
|
12098
|
345 @iftex
|
|
346 $2^{27}$
|
|
347 @end iftex
|
|
348 @ifinfo
|
|
349 2**27
|
|
350 @end ifinfo
|
|
351 bit set (which on most machines makes it a negative number). We
|
6447
|
352 use high bits for this and other modifiers to make possible a wide range
|
|
353 of basic character codes.
|
|
354
|
12098
|
355 In a string, the
|
|
356 @iftex
|
|
357 $2^{7}$
|
|
358 @end iftex
|
|
359 @ifinfo
|
|
360 2**7
|
|
361 @end ifinfo
|
|
362 bit indicates a meta character, so the meta
|
6447
|
363 characters that can fit in a string have codes in the range from 128 to
|
|
364 255, and are the meta versions of the ordinary @sc{ASCII} characters.
|
|
365 (In Emacs versions 18 and older, this convention was used for characters
|
|
366 outside of strings as well.)
|
|
367
|
|
368 The read syntax for meta characters uses @samp{\M-}. For example,
|
|
369 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
|
7118
|
370 octal character codes (see below), with @samp{\C-}, or with any other
|
|
371 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
|
|
372 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
|
|
373 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
|
6447
|
374
|
|
375 The case of an ordinary letter is indicated by its character code as
|
|
376 part of @sc{ASCII}, but @sc{ASCII} has no way to represent whether a
|
12098
|
377 control character is upper case or lower case. Emacs uses the
|
|
378 @iftex
|
|
379 $2^{25}$
|
|
380 @end iftex
|
|
381 @ifinfo
|
|
382 2**25
|
|
383 @end ifinfo
|
|
384 bit to indicate that the shift key was used for typing a control
|
|
385 character. This distinction is possible only when you use X terminals
|
|
386 or other special terminals; ordinary terminals do not indicate the
|
|
387 distinction to the computer in any way.
|
6447
|
388
|
|
389 @cindex hyper characters
|
|
390 @cindex super characters
|
|
391 @cindex alt characters
|
|
392 The X Window System defines three other modifier bits that can be set
|
|
393 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
|
|
394 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus,
|
12098
|
395 @samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
|
|
396 @iftex
|
|
397 Numerically, the
|
|
398 bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
|
|
399 @end iftex
|
|
400 @ifinfo
|
|
401 Numerically, the
|
|
402 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
|
|
403 @end ifinfo
|
6447
|
404
|
|
405 @cindex @samp{?} in character constant
|
|
406 @cindex question mark in character constant
|
|
407 @cindex @samp{\} in character constant
|
|
408 @cindex backslash in character constant
|
|
409 @cindex octal character code
|
|
410 Finally, the most general read syntax consists of a question mark
|
|
411 followed by a backslash and the character code in octal (up to three
|
|
412 octal digits); thus, @samp{?\101} for the character @kbd{A},
|
|
413 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
|
|
414 character @kbd{C-b}. Although this syntax can represent any @sc{ASCII}
|
|
415 character, it is preferred only when the precise octal value is more
|
|
416 important than the @sc{ASCII} representation.
|
|
417
|
|
418 @example
|
|
419 @group
|
|
420 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
|
|
421 ?\101 @result{} 65 ?A @result{} 65
|
|
422 @end group
|
|
423 @end example
|
|
424
|
|
425 A backslash is allowed, and harmless, preceding any character without
|
|
426 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
|
|
427 There is no reason to add a backslash before most characters. However,
|
|
428 you should add a backslash before any of the characters
|
|
429 @samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
|
|
430 Lisp code. Also add a backslash before whitespace characters such as
|
|
431 space, tab, newline and formfeed. However, it is cleaner to use one of
|
|
432 the easily readable escape sequences, such as @samp{\t}, instead of an
|
|
433 actual whitespace character such as a tab.
|
|
434
|
7118
|
435 @node Symbol Type
|
|
436 @subsection Symbol Type
|
|
437
|
|
438 A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The symbol
|
|
439 name serves as the printed representation of the symbol. In ordinary
|
|
440 use, the name is unique---no two symbols have the same name.
|
|
441
|
|
442 A symbol can serve as a variable, as a function name, or to hold a
|
|
443 property list. Or it may serve only to be distinct from all other Lisp
|
|
444 objects, so that its presence in a data structure may be recognized
|
|
445 reliably. In a given context, usually only one of these uses is
|
|
446 intended. But you can use one symbol in all of these ways,
|
|
447 independently.
|
|
448
|
|
449 @cindex @samp{\} in symbols
|
|
450 @cindex backslash in symbols
|
|
451 A symbol name can contain any characters whatever. Most symbol names
|
|
452 are written with letters, digits, and the punctuation characters
|
|
453 @samp{-+=*/}. Such names require no special punctuation; the characters
|
|
454 of the name suffice as long as the name does not look like a number.
|
|
455 (If it does, write a @samp{\} at the beginning of the name to force
|
|
456 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}} are
|
|
457 less often used but also require no special punctuation. Any other
|
|
458 characters may be included in a symbol's name by escaping them with a
|
|
459 backslash. In contrast to its use in strings, however, a backslash in
|
|
460 the name of a symbol simply quotes the single character that follows the
|
|
461 backslash. For example, in a string, @samp{\t} represents a tab
|
|
462 character; in the name of a symbol, however, @samp{\t} merely quotes the
|
|
463 letter @kbd{t}. To have a symbol with a tab character in its name, you
|
|
464 must actually use a tab (preceded with a backslash). But it's rare to
|
|
465 do such a thing.
|
|
466
|
|
467 @cindex CL note---case of letters
|
|
468 @quotation
|
7734
|
469 @b{Common Lisp note:} In Common Lisp, lower case letters are always
|
12098
|
470 ``folded'' to upper case, unless they are explicitly escaped. In Emacs
|
|
471 Lisp, upper case and lower case letters are distinct.
|
7118
|
472 @end quotation
|
|
473
|
|
474 Here are several examples of symbol names. Note that the @samp{+} in
|
|
475 the fifth example is escaped to prevent it from being read as a number.
|
12098
|
476 This is not necessary in the sixth example because the rest of the name
|
7118
|
477 makes it invalid as a number.
|
|
478
|
|
479 @example
|
|
480 @group
|
|
481 foo ; @r{A symbol named @samp{foo}.}
|
|
482 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
|
|
483 char-to-string ; @r{A symbol named @samp{char-to-string}.}
|
|
484 @end group
|
|
485 @group
|
|
486 1+ ; @r{A symbol named @samp{1+}}
|
|
487 ; @r{(not @samp{+1}, which is an integer).}
|
|
488 @end group
|
|
489 @group
|
|
490 \+1 ; @r{A symbol named @samp{+1}}
|
|
491 ; @r{(not a very readable name).}
|
|
492 @end group
|
|
493 @group
|
|
494 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
|
|
495 @c the @'s in this next line use up three characters, hence the
|
|
496 @c apparent misalignment of the comment.
|
|
497 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
|
|
498 ; @r{These characters need not be escaped.}
|
|
499 @end group
|
|
500 @end example
|
|
501
|
6447
|
502 @node Sequence Type
|
|
503 @subsection Sequence Types
|
|
504
|
|
505 A @dfn{sequence} is a Lisp object that represents an ordered set of
|
|
506 elements. There are two kinds of sequence in Emacs Lisp, lists and
|
|
507 arrays. Thus, an object of type list or of type array is also
|
|
508 considered a sequence.
|
|
509
|
|
510 Arrays are further subdivided into strings and vectors. Vectors can
|
|
511 hold elements of any type, but string elements must be characters in the
|
|
512 range from 0 to 255. However, the characters in a string can have text
|
7118
|
513 properties like characters in a buffer (@pxref{Text Properties});
|
|
514 vectors do not support text properties even when their elements happen
|
|
515 to be characters.
|
6447
|
516
|
|
517 Lists, strings and vectors are different, but they have important
|
|
518 similarities. For example, all have a length @var{l}, and all have
|
|
519 elements which can be indexed from zero to @var{l} minus one. Also,
|
|
520 several functions, called sequence functions, accept any kind of
|
|
521 sequence. For example, the function @code{elt} can be used to extract
|
|
522 an element of a sequence, given its index. @xref{Sequences Arrays
|
|
523 Vectors}.
|
|
524
|
|
525 It is impossible to read the same sequence twice, since sequences are
|
|
526 always created anew upon reading. If you read the read syntax for a
|
|
527 sequence twice, you get two sequences with equal contents. There is one
|
|
528 exception: the empty list @code{()} always stands for the same object,
|
|
529 @code{nil}.
|
|
530
|
7118
|
531 @node Cons Cell Type
|
|
532 @subsection Cons Cell and List Types
|
6447
|
533 @cindex address field of register
|
|
534 @cindex decrement field of register
|
|
535
|
7118
|
536 A @dfn{cons cell} is an object comprising two pointers named the
|
|
537 @sc{car} and the @sc{cdr}. Each of them can point to any Lisp object.
|
|
538
|
|
539 A @dfn{list} is a series of cons cells, linked together so that the
|
|
540 @sc{cdr} of each cons cell points either to another cons cell or to the
|
|
541 empty list. @xref{Lists}, for functions that work on lists. Because
|
|
542 most cons cells are used as part of lists, the phrase @dfn{list
|
|
543 structure} has come to refer to any structure made out of cons cells.
|
6447
|
544
|
|
545 The names @sc{car} and @sc{cdr} have only historical meaning now. The
|
|
546 original Lisp implementation ran on an @w{IBM 704} computer which
|
|
547 divided words into two parts, called the ``address'' part and the
|
|
548 ``decrement''; @sc{car} was an instruction to extract the contents of
|
|
549 the address part of a register, and @sc{cdr} an instruction to extract
|
|
550 the contents of the decrement. By contrast, ``cons cells'' are named
|
|
551 for the function @code{cons} that creates them, which in turn is named
|
|
552 for its purpose, the construction of cells.
|
|
553
|
|
554 @cindex atom
|
|
555 Because cons cells are so central to Lisp, we also have a word for
|
|
556 ``an object which is not a cons cell''. These objects are called
|
|
557 @dfn{atoms}.
|
|
558
|
|
559 @cindex parenthesis
|
|
560 The read syntax and printed representation for lists are identical, and
|
|
561 consist of a left parenthesis, an arbitrary number of elements, and a
|
|
562 right parenthesis.
|
|
563
|
|
564 Upon reading, each object inside the parentheses becomes an element
|
|
565 of the list. That is, a cons cell is made for each element. The
|
|
566 @sc{car} of the cons cell points to the element, and its @sc{cdr} points
|
7118
|
567 to the next cons cell of the list, which holds the next element in the
|
|
568 list. The @sc{cdr} of the last cons cell is set to point to @code{nil}.
|
6447
|
569
|
|
570 @cindex box diagrams, for lists
|
|
571 @cindex diagrams, boxed, for lists
|
|
572 A list can be illustrated by a diagram in which the cons cells are
|
|
573 shown as pairs of boxes. (The Lisp reader cannot read such an
|
7118
|
574 illustration; unlike the textual notation, which can be understood by
|
|
575 both humans and computers, the box illustrations can be understood only
|
|
576 by humans.) The following represents the three-element list @code{(rose
|
6447
|
577 violet buttercup)}:
|
|
578
|
|
579 @example
|
|
580 @group
|
|
581 ___ ___ ___ ___ ___ ___
|
|
582 |___|___|--> |___|___|--> |___|___|--> nil
|
|
583 | | |
|
|
584 | | |
|
|
585 --> rose --> violet --> buttercup
|
|
586 @end group
|
|
587 @end example
|
|
588
|
|
589 In this diagram, each box represents a slot that can refer to any Lisp
|
|
590 object. Each pair of boxes represents a cons cell. Each arrow is a
|
|
591 reference to a Lisp object, either an atom or another cons cell.
|
|
592
|
|
593 In this example, the first box, the @sc{car} of the first cons cell,
|
|
594 refers to or ``contains'' @code{rose} (a symbol). The second box, the
|
|
595 @sc{cdr} of the first cons cell, refers to the next pair of boxes, the
|
|
596 second cons cell. The @sc{car} of the second cons cell refers to
|
|
597 @code{violet} and the @sc{cdr} refers to the third cons cell. The
|
|
598 @sc{cdr} of the third (and last) cons cell refers to @code{nil}.
|
|
599
|
|
600 Here is another diagram of the same list, @code{(rose violet
|
|
601 buttercup)}, sketched in a different manner:
|
|
602
|
|
603 @smallexample
|
|
604 @group
|
|
605 --------------- ---------------- -------------------
|
|
606 | car | cdr | | car | cdr | | car | cdr |
|
|
607 | rose | o-------->| violet | o-------->| buttercup | nil |
|
|
608 | | | | | | | | |
|
|
609 --------------- ---------------- -------------------
|
|
610 @end group
|
|
611 @end smallexample
|
|
612
|
|
613 @cindex @samp{(@dots{})} in lists
|
|
614 @cindex @code{nil} in lists
|
|
615 @cindex empty list
|
|
616 A list with no elements in it is the @dfn{empty list}; it is identical
|
|
617 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
|
|
618 and a list.
|
|
619
|
|
620 Here are examples of lists written in Lisp syntax:
|
|
621
|
|
622 @example
|
|
623 (A 2 "A") ; @r{A list of three elements.}
|
|
624 () ; @r{A list of no elements (the empty list).}
|
|
625 nil ; @r{A list of no elements (the empty list).}
|
|
626 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
|
|
627 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
|
|
628 (A nil) ; @r{Equivalent to the previous.}
|
|
629 ((A B C)) ; @r{A list of one element}
|
|
630 ; @r{(which is a list of three elements).}
|
|
631 @end example
|
|
632
|
|
633 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
|
|
634 depicted with boxes and arrows:
|
|
635
|
|
636 @example
|
|
637 @group
|
|
638 ___ ___ ___ ___
|
|
639 |___|___|--> |___|___|--> nil
|
|
640 | |
|
|
641 | |
|
|
642 --> A --> nil
|
|
643 @end group
|
|
644 @end example
|
|
645
|
|
646 @menu
|
|
647 * Dotted Pair Notation:: An alternative syntax for lists.
|
|
648 * Association List Type:: A specially constructed list.
|
|
649 @end menu
|
|
650
|
|
651 @node Dotted Pair Notation
|
|
652 @comment node-name, next, previous, up
|
|
653 @subsubsection Dotted Pair Notation
|
|
654 @cindex dotted pair notation
|
|
655 @cindex @samp{.} in lists
|
|
656
|
|
657 @dfn{Dotted pair notation} is an alternative syntax for cons cells
|
|
658 that represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
|
|
659 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
|
|
660 the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted
|
|
661 pair notation is therefore more general than list syntax. In the dotted
|
|
662 pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
|
|
663 . nil)))}. For @code{nil}-terminated lists, the two notations produce
|
|
664 the same result, but list notation is usually clearer and more
|
|
665 convenient when it is applicable. When printing a list, the dotted pair
|
|
666 notation is only used if the @sc{cdr} of a cell is not a list.
|
|
667
|
|
668 Here's how box notation can illustrate dotted pairs. This example
|
|
669 shows the pair @code{(rose . violet)}:
|
|
670
|
|
671 @example
|
|
672 @group
|
|
673 ___ ___
|
|
674 |___|___|--> violet
|
|
675 |
|
|
676 |
|
|
677 --> rose
|
|
678 @end group
|
|
679 @end example
|
|
680
|
|
681 Dotted pair notation can be combined with list notation to represent a
|
|
682 chain of cons cells with a non-@code{nil} final @sc{cdr}. For example,
|
|
683 @code{(rose violet . buttercup)} is equivalent to @code{(rose . (violet
|
|
684 . buttercup))}. The object looks like this:
|
|
685
|
|
686 @example
|
|
687 @group
|
|
688 ___ ___ ___ ___
|
|
689 |___|___|--> |___|___|--> buttercup
|
|
690 | |
|
|
691 | |
|
|
692 --> rose --> violet
|
|
693 @end group
|
|
694 @end example
|
|
695
|
|
696 These diagrams make it evident why @w{@code{(rose .@: violet .@:
|
|
697 buttercup)}} is invalid syntax; it would require a cons cell that has
|
|
698 three parts rather than two.
|
|
699
|
|
700 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}
|
|
701 and looks like this:
|
|
702
|
|
703 @example
|
|
704 @group
|
|
705 ___ ___ ___ ___
|
|
706 |___|___|--> |___|___|--> nil
|
|
707 | |
|
|
708 | |
|
|
709 --> rose --> violet
|
|
710 @end group
|
|
711 @end example
|
|
712
|
|
713 Similarly, the three-element list @code{(rose violet buttercup)}
|
|
714 is equivalent to @code{(rose . (violet . (buttercup)))}.
|
|
715 @ifinfo
|
|
716 It looks like this:
|
|
717
|
|
718 @example
|
|
719 @group
|
|
720 ___ ___ ___ ___ ___ ___
|
|
721 |___|___|--> |___|___|--> |___|___|--> nil
|
|
722 | | |
|
|
723 | | |
|
|
724 --> rose --> violet --> buttercup
|
|
725 @end group
|
|
726 @end example
|
|
727 @end ifinfo
|
|
728
|
|
729 @node Association List Type
|
|
730 @comment node-name, next, previous, up
|
|
731 @subsubsection Association List Type
|
|
732
|
|
733 An @dfn{association list} or @dfn{alist} is a specially-constructed
|
|
734 list whose elements are cons cells. In each element, the @sc{car} is
|
|
735 considered a @dfn{key}, and the @sc{cdr} is considered an
|
|
736 @dfn{associated value}. (In some cases, the associated value is stored
|
|
737 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
|
|
738 stacks, since it is easy to add or remove associations at the front of
|
|
739 the list.
|
|
740
|
|
741 For example,
|
|
742
|
|
743 @example
|
|
744 (setq alist-of-colors
|
|
745 '((rose . red) (lily . white) (buttercup . yellow)))
|
|
746 @end example
|
|
747
|
|
748 @noindent
|
|
749 sets the variable @code{alist-of-colors} to an alist of three elements. In the
|
|
750 first element, @code{rose} is the key and @code{red} is the value.
|
|
751
|
|
752 @xref{Association Lists}, for a further explanation of alists and for
|
|
753 functions that work on alists.
|
|
754
|
|
755 @node Array Type
|
|
756 @subsection Array Type
|
|
757
|
|
758 An @dfn{array} is composed of an arbitrary number of slots for
|
|
759 referring to other Lisp objects, arranged in a contiguous block of
|
7118
|
760 memory. Accessing any element of an array takes the same amount of
|
6447
|
761 time. In contrast, accessing an element of a list requires time
|
|
762 proportional to the position of the element in the list. (Elements at
|
|
763 the end of a list take longer to access than elements at the beginning
|
|
764 of a list.)
|
|
765
|
|
766 Emacs defines two types of array, strings and vectors. A string is an
|
|
767 array of characters and a vector is an array of arbitrary objects. Both
|
|
768 are one-dimensional. (Most other programming languages support
|
|
769 multidimensional arrays, but they are not essential; you can get the
|
|
770 same effect with an array of arrays.) Each type of array has its own
|
|
771 read syntax; see @ref{String Type}, and @ref{Vector Type}.
|
|
772
|
|
773 An array may have any length up to the largest integer; but once
|
|
774 created, it has a fixed size. The first element of an array has index
|
|
775 zero, the second element has index 1, and so on. This is called
|
|
776 @dfn{zero-origin} indexing. For example, an array of four elements has
|
|
777 indices 0, 1, 2, @w{and 3}.
|
|
778
|
|
779 The array type is contained in the sequence type and contains both the
|
|
780 string type and the vector type.
|
|
781
|
|
782 @node String Type
|
|
783 @subsection String Type
|
|
784
|
|
785 A @dfn{string} is an array of characters. Strings are used for many
|
|
786 purposes in Emacs, as can be expected in a text editor; for example, as
|
|
787 the names of Lisp symbols, as messages for the user, and to represent
|
|
788 text extracted from buffers. Strings in Lisp are constants: evaluation
|
|
789 of a string returns the same string.
|
|
790
|
|
791 @cindex @samp{"} in strings
|
|
792 @cindex double-quote in strings
|
|
793 @cindex @samp{\} in strings
|
|
794 @cindex backslash in strings
|
|
795 The read syntax for strings is a double-quote, an arbitrary number of
|
|
796 characters, and another double-quote, @code{"like this"}. The Lisp
|
|
797 reader accepts the same formats for reading the characters of a string
|
|
798 as it does for reading single characters (without the question mark that
|
|
799 begins a character literal). You can enter a nonprinting character such
|
|
800 as tab, @kbd{C-a} or @kbd{M-C-A} using the convenient escape sequences,
|
|
801 like this: @code{"\t, \C-a, \M-\C-a"}. You can include a double-quote
|
|
802 in a string by preceding it with a backslash; thus, @code{"\""} is a
|
|
803 string containing just a single double-quote character.
|
|
804 (@xref{Character Type}, for a description of the read syntax for
|
|
805 characters.)
|
|
806
|
|
807 If you use the @samp{\M-} syntax to indicate a meta character in a
|
12098
|
808 string constant, this sets the
|
|
809 @iftex
|
|
810 $2^{7}$
|
|
811 @end iftex
|
|
812 @ifinfo
|
|
813 2**7
|
|
814 @end ifinfo
|
|
815 bit of the character in the string.
|
6447
|
816 This is not the same representation that the meta modifier has in a
|
|
817 character on its own (not inside a string). @xref{Character Type}.
|
|
818
|
7118
|
819 Strings cannot hold characters that have the hyper, super, or alt
|
6447
|
820 modifiers; they can hold @sc{ASCII} control characters, but no others.
|
|
821 They do not distinguish case in @sc{ASCII} control characters.
|
|
822
|
7118
|
823 The printed representation of a string consists of a double-quote, the
|
|
824 characters it contains, and another double-quote. However, you must
|
|
825 escape any backslash or double-quote characters in the string with a
|
|
826 backslash, like this: @code{"this \" is an embedded quote"}.
|
|
827
|
|
828 The newline character is not special in the read syntax for strings;
|
|
829 if you write a new line between the double-quotes, it becomes a
|
|
830 character in the string. But an escaped newline---one that is preceded
|
|
831 by @samp{\}---does not become part of the string; i.e., the Lisp reader
|
|
832 ignores an escaped newline while reading a string.
|
6447
|
833 @cindex newline in strings
|
|
834
|
|
835 @example
|
|
836 "It is useful to include newlines
|
|
837 in documentation strings,
|
|
838 but the newline is \
|
|
839 ignored if escaped."
|
|
840 @result{} "It is useful to include newlines
|
|
841 in documentation strings,
|
|
842 but the newline is ignored if escaped."
|
|
843 @end example
|
|
844
|
|
845 A string can hold properties of the text it contains, in addition to
|
|
846 the characters themselves. This enables programs that copy text between
|
|
847 strings and buffers to preserve the properties with no special effort.
|
|
848 @xref{Text Properties}. Strings with text properties have a special
|
|
849 read and print syntax:
|
|
850
|
|
851 @example
|
|
852 #("@var{characters}" @var{property-data}...)
|
|
853 @end example
|
|
854
|
|
855 @noindent
|
|
856 where @var{property-data} consists of zero or more elements, in groups
|
|
857 of three as follows:
|
|
858
|
|
859 @example
|
|
860 @var{beg} @var{end} @var{plist}
|
|
861 @end example
|
|
862
|
|
863 @noindent
|
|
864 The elements @var{beg} and @var{end} are integers, and together specify
|
|
865 a range of indices in the string; @var{plist} is the property list for
|
|
866 that range.
|
|
867
|
|
868 @xref{Strings and Characters}, for functions that work on strings.
|
|
869
|
|
870 @node Vector Type
|
|
871 @subsection Vector Type
|
|
872
|
|
873 A @dfn{vector} is a one-dimensional array of elements of any type. It
|
|
874 takes a constant amount of time to access any element of a vector. (In
|
|
875 a list, the access time of an element is proportional to the distance of
|
|
876 the element from the beginning of the list.)
|
|
877
|
|
878 The printed representation of a vector consists of a left square
|
|
879 bracket, the elements, and a right square bracket. This is also the
|
|
880 read syntax. Like numbers and strings, vectors are considered constants
|
|
881 for evaluation.
|
|
882
|
|
883 @example
|
|
884 [1 "two" (three)] ; @r{A vector of three elements.}
|
|
885 @result{} [1 "two" (three)]
|
|
886 @end example
|
|
887
|
|
888 @xref{Vectors}, for functions that work with vectors.
|
|
889
|
7118
|
890 @node Function Type
|
|
891 @subsection Function Type
|
6447
|
892
|
|
893 Just as functions in other programming languages are executable,
|
|
894 @dfn{Lisp function} objects are pieces of executable code. However,
|
|
895 functions in Lisp are primarily Lisp objects, and only secondarily the
|
|
896 text which represents them. These Lisp objects are lambda expressions:
|
|
897 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
|
|
898 Expressions}).
|
|
899
|
|
900 In most programming languages, it is impossible to have a function
|
|
901 without a name. In Lisp, a function has no intrinsic name. A lambda
|
|
902 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
|
|
903 Functions}). A named function in Lisp is actually a symbol with a valid
|
|
904 function in its function cell (@pxref{Defining Functions}).
|
|
905
|
|
906 Most of the time, functions are called when their names are written in
|
|
907 Lisp expressions in Lisp programs. However, you can construct or obtain
|
|
908 a function object at run time and then call it with the primitive
|
|
909 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
|
|
910
|
7118
|
911 @node Macro Type
|
|
912 @subsection Macro Type
|
6447
|
913
|
|
914 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
|
|
915 language. It is represented as an object much like a function, but with
|
|
916 different parameter-passing semantics. A Lisp macro has the form of a
|
|
917 list whose first element is the symbol @code{macro} and whose @sc{cdr}
|
|
918 is a Lisp function object, including the @code{lambda} symbol.
|
|
919
|
|
920 Lisp macro objects are usually defined with the built-in
|
|
921 @code{defmacro} function, but any list that begins with @code{macro} is
|
|
922 a macro as far as Emacs is concerned. @xref{Macros}, for an explanation
|
|
923 of how to write a macro.
|
|
924
|
|
925 @node Primitive Function Type
|
|
926 @subsection Primitive Function Type
|
|
927 @cindex special forms
|
|
928
|
|
929 A @dfn{primitive function} is a function callable from Lisp but
|
|
930 written in the C programming language. Primitive functions are also
|
|
931 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
|
|
932 derived from ``subroutine''.) Most primitive functions evaluate all
|
|
933 their arguments when they are called. A primitive function that does
|
|
934 not evaluate all its arguments is called a @dfn{special form}
|
|
935 (@pxref{Special Forms}).@refill
|
|
936
|
|
937 It does not matter to the caller of a function whether the function is
|
|
938 primitive. However, this does matter if you try to substitute a
|
|
939 function written in Lisp for a primitive of the same name. The reason
|
|
940 is that the primitive function may be called directly from C code.
|
|
941 Calls to the redefined function from Lisp will use the new definition,
|
|
942 but calls from C code may still use the built-in definition.
|
|
943
|
|
944 The term @dfn{function} refers to all Emacs functions, whether written
|
7118
|
945 in Lisp or C. @xref{Function Type}, for information about the
|
|
946 functions written in Lisp.
|
6447
|
947
|
|
948 Primitive functions have no read syntax and print in hash notation
|
|
949 with the name of the subroutine.
|
|
950
|
|
951 @example
|
|
952 @group
|
|
953 (symbol-function 'car) ; @r{Access the function cell}
|
|
954 ; @r{of the symbol.}
|
|
955 @result{} #<subr car>
|
|
956 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
|
|
957 @result{} t ; @r{Yes.}
|
|
958 @end group
|
|
959 @end example
|
|
960
|
|
961 @node Byte-Code Type
|
|
962 @subsection Byte-Code Function Type
|
|
963
|
|
964 The byte compiler produces @dfn{byte-code function objects}.
|
|
965 Internally, a byte-code function object is much like a vector; however,
|
|
966 the evaluator handles this data type specially when it appears as a
|
|
967 function to be called. @xref{Byte Compilation}, for information about
|
|
968 the byte compiler.
|
|
969
|
12098
|
970 The printed representation and read syntax for a byte-code function
|
|
971 object is like that for a vector, with an additional @samp{#} before the
|
|
972 opening @samp{[}.
|
6447
|
973
|
|
974 @node Autoload Type
|
|
975 @subsection Autoload Type
|
|
976
|
|
977 An @dfn{autoload object} is a list whose first element is the symbol
|
|
978 @code{autoload}. It is stored as the function definition of a symbol as
|
|
979 a placeholder for the real definition; it says that the real definition
|
|
980 is found in a file of Lisp code that should be loaded when necessary.
|
|
981 The autoload object contains the name of the file, plus some other
|
|
982 information about the real definition.
|
|
983
|
|
984 After the file has been loaded, the symbol should have a new function
|
|
985 definition that is not an autoload object. The new definition is then
|
|
986 called as if it had been there to begin with. From the user's point of
|
|
987 view, the function call works as expected, using the function definition
|
|
988 in the loaded file.
|
|
989
|
|
990 An autoload object is usually created with the function
|
|
991 @code{autoload}, which stores the object in the function cell of a
|
|
992 symbol. @xref{Autoload}, for more details.
|
|
993
|
|
994 @node Editing Types
|
|
995 @section Editing Types
|
|
996 @cindex editing types
|
|
997
|
|
998 The types in the previous section are common to many Lisp dialects.
|
|
999 Emacs Lisp provides several additional data types for purposes connected
|
|
1000 with editing.
|
|
1001
|
|
1002 @menu
|
|
1003 * Buffer Type:: The basic object of editing.
|
|
1004 * Marker Type:: A position in a buffer.
|
|
1005 * Window Type:: Buffers are displayed in windows.
|
|
1006 * Frame Type:: Windows subdivide frames.
|
|
1007 * Window Configuration Type:: Recording the way a frame is subdivided.
|
|
1008 * Process Type:: A process running on the underlying OS.
|
|
1009 * Stream Type:: Receive or send characters.
|
|
1010 * Keymap Type:: What function a keystroke invokes.
|
|
1011 * Syntax Table Type:: What a character means.
|
|
1012 * Display Table Type:: How display tables are represented.
|
|
1013 * Overlay Type:: How an overlay is represented.
|
|
1014 @end menu
|
|
1015
|
|
1016 @node Buffer Type
|
|
1017 @subsection Buffer Type
|
|
1018
|
|
1019 A @dfn{buffer} is an object that holds text that can be edited
|
|
1020 (@pxref{Buffers}). Most buffers hold the contents of a disk file
|
|
1021 (@pxref{Files}) so they can be edited, but some are used for other
|
|
1022 purposes. Most buffers are also meant to be seen by the user, and
|
|
1023 therefore displayed, at some time, in a window (@pxref{Windows}). But a
|
|
1024 buffer need not be displayed in any window.
|
|
1025
|
|
1026 The contents of a buffer are much like a string, but buffers are not
|
|
1027 used like strings in Emacs Lisp, and the available operations are
|
|
1028 different. For example, insertion of text into a buffer is very
|
|
1029 efficient, whereas ``inserting'' text into a string requires
|
|
1030 concatenating substrings, and the result is an entirely new string
|
|
1031 object.
|
|
1032
|
|
1033 Each buffer has a designated position called @dfn{point}
|
|
1034 (@pxref{Positions}). At any time, one buffer is the @dfn{current
|
|
1035 buffer}. Most editing commands act on the contents of the current
|
7118
|
1036 buffer in the neighborhood of point. Many of the standard Emacs
|
|
1037 functions manipulate or test the characters in the current buffer; a
|
|
1038 whole chapter in this manual is devoted to describing these functions
|
|
1039 (@pxref{Text}).
|
6447
|
1040
|
|
1041 Several other data structures are associated with each buffer:
|
|
1042
|
|
1043 @itemize @bullet
|
|
1044 @item
|
|
1045 a local syntax table (@pxref{Syntax Tables});
|
|
1046
|
|
1047 @item
|
|
1048 a local keymap (@pxref{Keymaps}); and,
|
|
1049
|
|
1050 @item
|
|
1051 a local variable binding list (@pxref{Buffer-Local Variables}).
|
12098
|
1052
|
|
1053 @item
|
|
1054 a list of overlays (@pxref{Overlays}).
|
|
1055
|
|
1056 @item
|
|
1057 text properties for the text in the buffer (@pxref{Text Properties}).
|
6447
|
1058 @end itemize
|
|
1059
|
|
1060 @noindent
|
7118
|
1061 The local keymap and variable list contain entries that individually
|
6447
|
1062 override global bindings or values. These are used to customize the
|
|
1063 behavior of programs in different buffers, without actually changing the
|
|
1064 programs.
|
|
1065
|
12098
|
1066 A buffer may be @dfn{indirect}, which means it shares the text
|
|
1067 of another buffer. @xref{Indirect Buffers}.
|
|
1068
|
|
1069 Buffers have no read syntax. They print in hash notation, showing the
|
6447
|
1070 buffer name.
|
|
1071
|
|
1072 @example
|
|
1073 @group
|
|
1074 (current-buffer)
|
|
1075 @result{} #<buffer objects.texi>
|
|
1076 @end group
|
|
1077 @end example
|
|
1078
|
|
1079 @node Marker Type
|
|
1080 @subsection Marker Type
|
|
1081
|
|
1082 A @dfn{marker} denotes a position in a specific buffer. Markers
|
|
1083 therefore have two components: one for the buffer, and one for the
|
|
1084 position. Changes in the buffer's text automatically relocate the
|
|
1085 position value as necessary to ensure that the marker always points
|
|
1086 between the same two characters in the buffer.
|
|
1087
|
|
1088 Markers have no read syntax. They print in hash notation, giving the
|
|
1089 current character position and the name of the buffer.
|
|
1090
|
|
1091 @example
|
|
1092 @group
|
|
1093 (point-marker)
|
|
1094 @result{} #<marker at 10779 in objects.texi>
|
|
1095 @end group
|
|
1096 @end example
|
|
1097
|
|
1098 @xref{Markers}, for information on how to test, create, copy, and move
|
|
1099 markers.
|
|
1100
|
|
1101 @node Window Type
|
|
1102 @subsection Window Type
|
|
1103
|
|
1104 A @dfn{window} describes the portion of the terminal screen that Emacs
|
|
1105 uses to display a buffer. Every window has one associated buffer, whose
|
|
1106 contents appear in the window. By contrast, a given buffer may appear
|
|
1107 in one window, no window, or several windows.
|
|
1108
|
|
1109 Though many windows may exist simultaneously, at any time one window
|
|
1110 is designated the @dfn{selected window}. This is the window where the
|
|
1111 cursor is (usually) displayed when Emacs is ready for a command. The
|
|
1112 selected window usually displays the current buffer, but this is not
|
|
1113 necessarily the case.
|
|
1114
|
|
1115 Windows are grouped on the screen into frames; each window belongs to
|
|
1116 one and only one frame. @xref{Frame Type}.
|
|
1117
|
|
1118 Windows have no read syntax. They print in hash notation, giving the
|
|
1119 window number and the name of the buffer being displayed. The window
|
|
1120 numbers exist to identify windows uniquely, since the buffer displayed
|
|
1121 in any given window can change frequently.
|
|
1122
|
|
1123 @example
|
|
1124 @group
|
|
1125 (selected-window)
|
|
1126 @result{} #<window 1 on objects.texi>
|
|
1127 @end group
|
|
1128 @end example
|
|
1129
|
|
1130 @xref{Windows}, for a description of the functions that work on windows.
|
|
1131
|
|
1132 @node Frame Type
|
|
1133 @subsection Frame Type
|
|
1134
|
|
1135 A @var{frame} is a rectangle on the screen that contains one or more
|
|
1136 Emacs windows. A frame initially contains a single main window (plus
|
|
1137 perhaps a minibuffer window) which you can subdivide vertically or
|
|
1138 horizontally into smaller windows.
|
|
1139
|
|
1140 Frames have no read syntax. They print in hash notation, giving the
|
|
1141 frame's title, plus its address in core (useful to identify the frame
|
|
1142 uniquely).
|
|
1143
|
|
1144 @example
|
|
1145 @group
|
|
1146 (selected-frame)
|
|
1147 @result{} #<frame xemacs@@mole.gnu.ai.mit.edu 0xdac80>
|
|
1148 @end group
|
|
1149 @end example
|
|
1150
|
|
1151 @xref{Frames}, for a description of the functions that work on frames.
|
|
1152
|
|
1153 @node Window Configuration Type
|
|
1154 @subsection Window Configuration Type
|
|
1155 @cindex screen layout
|
|
1156
|
|
1157 A @dfn{window configuration} stores information about the positions,
|
|
1158 sizes, and contents of the windows in a frame, so you can recreate the
|
|
1159 same arrangement of windows later.
|
|
1160
|
|
1161 Window configurations do not have a read syntax. They print as
|
|
1162 @samp{#<window-configuration>}. @xref{Window Configurations}, for a
|
|
1163 description of several functions related to window configurations.
|
|
1164
|
|
1165 @node Process Type
|
|
1166 @subsection Process Type
|
|
1167
|
|
1168 The word @dfn{process} usually means a running program. Emacs itself
|
|
1169 runs in a process of this sort. However, in Emacs Lisp, a process is a
|
|
1170 Lisp object that designates a subprocess created by the Emacs process.
|
|
1171 Programs such as shells, GDB, ftp, and compilers, running in
|
|
1172 subprocesses of Emacs, extend the capabilities of Emacs.
|
|
1173
|
|
1174 An Emacs subprocess takes textual input from Emacs and returns textual
|
|
1175 output to Emacs for further manipulation. Emacs can also send signals
|
|
1176 to the subprocess.
|
|
1177
|
|
1178 Process objects have no read syntax. They print in hash notation,
|
|
1179 giving the name of the process:
|
|
1180
|
|
1181 @example
|
|
1182 @group
|
|
1183 (process-list)
|
|
1184 @result{} (#<process shell>)
|
|
1185 @end group
|
|
1186 @end example
|
|
1187
|
|
1188 @xref{Processes}, for information about functions that create, delete,
|
|
1189 return information about, send input or signals to, and receive output
|
|
1190 from processes.
|
|
1191
|
|
1192 @node Stream Type
|
|
1193 @subsection Stream Type
|
|
1194
|
|
1195 A @dfn{stream} is an object that can be used as a source or sink for
|
|
1196 characters---either to supply characters for input or to accept them as
|
|
1197 output. Many different types can be used this way: markers, buffers,
|
|
1198 strings, and functions. Most often, input streams (character sources)
|
|
1199 obtain characters from the keyboard, a buffer, or a file, and output
|
|
1200 streams (character sinks) send characters to a buffer, such as a
|
|
1201 @file{*Help*} buffer, or to the echo area.
|
|
1202
|
|
1203 The object @code{nil}, in addition to its other meanings, may be used
|
|
1204 as a stream. It stands for the value of the variable
|
|
1205 @code{standard-input} or @code{standard-output}. Also, the object
|
|
1206 @code{t} as a stream specifies input using the minibuffer
|
|
1207 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
|
|
1208 Area}).
|
|
1209
|
|
1210 Streams have no special printed representation or read syntax, and
|
|
1211 print as whatever primitive type they are.
|
|
1212
|
7337
|
1213 @xref{Read and Print}, for a description of functions
|
7118
|
1214 related to streams, including parsing and printing functions.
|
6447
|
1215
|
|
1216 @node Keymap Type
|
|
1217 @subsection Keymap Type
|
|
1218
|
|
1219 A @dfn{keymap} maps keys typed by the user to commands. This mapping
|
|
1220 controls how the user's command input is executed. A keymap is actually
|
|
1221 a list whose @sc{car} is the symbol @code{keymap}.
|
|
1222
|
|
1223 @xref{Keymaps}, for information about creating keymaps, handling prefix
|
|
1224 keys, local as well as global keymaps, and changing key bindings.
|
|
1225
|
|
1226 @node Syntax Table Type
|
|
1227 @subsection Syntax Table Type
|
|
1228
|
|
1229 A @dfn{syntax table} is a vector of 256 integers. Each element of the
|
|
1230 vector defines how one character is interpreted when it appears in a
|
|
1231 buffer. For example, in C mode (@pxref{Major Modes}), the @samp{+}
|
|
1232 character is punctuation, but in Lisp mode it is a valid character in a
|
|
1233 symbol. These modes specify different interpretations by changing the
|
|
1234 syntax table entry for @samp{+}, at index 43 in the syntax table.
|
|
1235
|
7118
|
1236 Syntax tables are used only for scanning text in buffers, not for
|
6447
|
1237 reading Lisp expressions. The table the Lisp interpreter uses to read
|
|
1238 expressions is built into the Emacs source code and cannot be changed;
|
|
1239 thus, to change the list delimiters to be @samp{@{} and @samp{@}}
|
|
1240 instead of @samp{(} and @samp{)} would be impossible.
|
|
1241
|
|
1242 @xref{Syntax Tables}, for details about syntax classes and how to make
|
|
1243 and modify syntax tables.
|
|
1244
|
|
1245 @node Display Table Type
|
|
1246 @subsection Display Table Type
|
|
1247
|
|
1248 A @dfn{display table} specifies how to display each character code.
|
|
1249 Each buffer and each window can have its own display table. A display
|
12098
|
1250 table is actually a vector of length 262. @xref{Display Tables}.
|
6447
|
1251
|
|
1252 @node Overlay Type
|
|
1253 @subsection Overlay Type
|
|
1254
|
|
1255 An @dfn{overlay} specifies temporary alteration of the display
|
|
1256 appearance of a part of a buffer. It contains markers delimiting a
|
|
1257 range of the buffer, plus a property list (a list whose elements are
|
|
1258 alternating property names and values). Overlays are used to present
|
12098
|
1259 parts of the buffer temporarily in a different display style. They have
|
|
1260 no read syntax, and print in hash notation, giving the buffer name and
|
|
1261 range of positions.
|
6447
|
1262
|
12098
|
1263 @xref{Overlays}, for how to create and use overlays.
|
6447
|
1264
|
|
1265 @node Type Predicates
|
|
1266 @section Type Predicates
|
|
1267 @cindex predicates
|
|
1268 @cindex type checking
|
|
1269 @kindex wrong-type-argument
|
|
1270
|
|
1271 The Emacs Lisp interpreter itself does not perform type checking on
|
|
1272 the actual arguments passed to functions when they are called. It could
|
|
1273 not do so, since function arguments in Lisp do not have declared data
|
|
1274 types, as they do in other programming languages. It is therefore up to
|
|
1275 the individual function to test whether each actual argument belongs to
|
|
1276 a type that the function can use.
|
|
1277
|
|
1278 All built-in functions do check the types of their actual arguments
|
|
1279 when appropriate, and signal a @code{wrong-type-argument} error if an
|
|
1280 argument is of the wrong type. For example, here is what happens if you
|
7118
|
1281 pass an argument to @code{+} that it cannot handle:
|
6447
|
1282
|
|
1283 @example
|
|
1284 @group
|
|
1285 (+ 2 'a)
|
|
1286 @error{} Wrong type argument: integer-or-marker-p, a
|
|
1287 @end group
|
|
1288 @end example
|
|
1289
|
|
1290 @cindex type predicates
|
|
1291 @cindex testing types
|
12067
|
1292 If you want your program to handle different types differently, you
|
|
1293 must do explicit type checking. The most common way to check the type
|
|
1294 of an object is to call a @dfn{type predicate} function. Emacs has a
|
|
1295 type predicate for each type, as well as some predicates for
|
|
1296 combinations of types.
|
|
1297
|
|
1298 A type predicate function takes one argument; it returns @code{t} if
|
|
1299 the argument belongs to the appropriate type, and @code{nil} otherwise.
|
|
1300 Following a general Lisp convention for predicate functions, most type
|
|
1301 predicates' names end with @samp{p}.
|
|
1302
|
|
1303 Here is an example which uses the predicates @code{listp} to check for
|
|
1304 a list and @code{symbolp} to check for a symbol.
|
6447
|
1305
|
12067
|
1306 @example
|
|
1307 (defun add-on (x)
|
|
1308 (cond ((symbolp x)
|
|
1309 ;; If X is a symbol, put it on LIST.
|
|
1310 (setq list (cons x list)))
|
|
1311 ((listp x)
|
|
1312 ;; If X is a list, add its elements to LIST.
|
|
1313 (setq list (append x list)))
|
12282
586e3ea81792
updates for version 19.29 made by melissa; also needed to check out files
Melissa Weisshaus <melissa@gnu.org>
diff
changeset
|
1314 @need 3000
|
12067
|
1315 (t
|
|
1316 ;; We only handle symbols and lists.
|
|
1317 (error "Invalid argument %s in add-on" x))))
|
|
1318 @end example
|
|
1319
|
|
1320 Here is a table of predefined type predicates, in alphabetical order,
|
6447
|
1321 with references to further information.
|
|
1322
|
|
1323 @table @code
|
|
1324 @item atom
|
|
1325 @xref{List-related Predicates, atom}.
|
|
1326
|
|
1327 @item arrayp
|
|
1328 @xref{Array Functions, arrayp}.
|
|
1329
|
|
1330 @item bufferp
|
|
1331 @xref{Buffer Basics, bufferp}.
|
|
1332
|
|
1333 @item byte-code-function-p
|
|
1334 @xref{Byte-Code Type, byte-code-function-p}.
|
|
1335
|
|
1336 @item case-table-p
|
|
1337 @xref{Case Table, case-table-p}.
|
|
1338
|
|
1339 @item char-or-string-p
|
|
1340 @xref{Predicates for Strings, char-or-string-p}.
|
|
1341
|
|
1342 @item commandp
|
|
1343 @xref{Interactive Call, commandp}.
|
|
1344
|
|
1345 @item consp
|
|
1346 @xref{List-related Predicates, consp}.
|
|
1347
|
|
1348 @item floatp
|
|
1349 @xref{Predicates on Numbers, floatp}.
|
|
1350
|
|
1351 @item frame-live-p
|
|
1352 @xref{Deleting Frames, frame-live-p}.
|
|
1353
|
|
1354 @item framep
|
|
1355 @xref{Frames, framep}.
|
|
1356
|
|
1357 @item integer-or-marker-p
|
|
1358 @xref{Predicates on Markers, integer-or-marker-p}.
|
|
1359
|
|
1360 @item integerp
|
|
1361 @xref{Predicates on Numbers, integerp}.
|
|
1362
|
|
1363 @item keymapp
|
|
1364 @xref{Creating Keymaps, keymapp}.
|
|
1365
|
|
1366 @item listp
|
|
1367 @xref{List-related Predicates, listp}.
|
|
1368
|
|
1369 @item markerp
|
|
1370 @xref{Predicates on Markers, markerp}.
|
|
1371
|
7118
|
1372 @item wholenump
|
|
1373 @xref{Predicates on Numbers, wholenump}.
|
6447
|
1374
|
|
1375 @item nlistp
|
|
1376 @xref{List-related Predicates, nlistp}.
|
|
1377
|
|
1378 @item numberp
|
|
1379 @xref{Predicates on Numbers, numberp}.
|
|
1380
|
|
1381 @item number-or-marker-p
|
|
1382 @xref{Predicates on Markers, number-or-marker-p}.
|
|
1383
|
|
1384 @item overlayp
|
|
1385 @xref{Overlays, overlayp}.
|
|
1386
|
|
1387 @item processp
|
|
1388 @xref{Processes, processp}.
|
|
1389
|
|
1390 @item sequencep
|
|
1391 @xref{Sequence Functions, sequencep}.
|
|
1392
|
|
1393 @item stringp
|
|
1394 @xref{Predicates for Strings, stringp}.
|
|
1395
|
|
1396 @item subrp
|
|
1397 @xref{Function Cells, subrp}.
|
|
1398
|
|
1399 @item symbolp
|
|
1400 @xref{Symbols, symbolp}.
|
|
1401
|
|
1402 @item syntax-table-p
|
|
1403 @xref{Syntax Tables, syntax-table-p}.
|
|
1404
|
|
1405 @item user-variable-p
|
|
1406 @xref{Defining Variables, user-variable-p}.
|
|
1407
|
|
1408 @item vectorp
|
|
1409 @xref{Vectors, vectorp}.
|
|
1410
|
|
1411 @item window-configuration-p
|
|
1412 @xref{Window Configurations, window-configuration-p}.
|
|
1413
|
|
1414 @item window-live-p
|
|
1415 @xref{Deleting Windows, window-live-p}.
|
|
1416
|
|
1417 @item windowp
|
|
1418 @xref{Basic Windows, windowp}.
|
|
1419 @end table
|
|
1420
|
12067
|
1421 The most general way to check the type of an object is to call the
|
|
1422 function @code{type-of}. Recall that each object belongs to one and
|
|
1423 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
|
|
1424 Data Types}). But @code{type-of} knows nothing about non-primitive
|
|
1425 types. In most cases, it is more convenient to use type predicates than
|
|
1426 @code{type-of}.
|
|
1427
|
|
1428 @defun type-of object
|
|
1429 This function returns a symbol naming the primitive type of
|
|
1430 @var{object}. The value is one of @code{symbol}, @code{integer},
|
|
1431 @code{float}, @code{string}, @code{cons}, @code{vector}, @code{marker},
|
|
1432 @code{overlay}, @code{window}, @code{buffer}, @code{subr},
|
|
1433 @code{compiled-function}, @code{window-configuration}, or
|
|
1434 @code{process}.
|
|
1435
|
|
1436 @example
|
|
1437 (type-of 1)
|
|
1438 @result{} integer
|
|
1439 (type-of 'nil)
|
|
1440 @result{} symbol
|
|
1441 (type-of '()) ; @r{@code{()} is @code{nil}.}
|
|
1442 @result{} symbol
|
|
1443 (type-of '(x))
|
|
1444 @result{} cons
|
|
1445 @end example
|
|
1446 @end defun
|
|
1447
|
6447
|
1448 @node Equality Predicates
|
|
1449 @section Equality Predicates
|
|
1450 @cindex equality
|
|
1451
|
|
1452 Here we describe two functions that test for equality between any two
|
|
1453 objects. Other functions test equality between objects of specific
|
7118
|
1454 types, e.g., strings. For these predicates, see the appropriate chapter
|
|
1455 describing the data type.
|
6447
|
1456
|
|
1457 @defun eq object1 object2
|
|
1458 This function returns @code{t} if @var{object1} and @var{object2} are
|
|
1459 the same object, @code{nil} otherwise. The ``same object'' means that a
|
|
1460 change in one will be reflected by the same change in the other.
|
|
1461
|
|
1462 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
|
|
1463 integers with the same value. Also, since symbol names are normally
|
|
1464 unique, if the arguments are symbols with the same name, they are
|
|
1465 @code{eq}. For other types (e.g., lists, vectors, strings), two
|
|
1466 arguments with the same contents or elements are not necessarily
|
|
1467 @code{eq} to each other: they are @code{eq} only if they are the same
|
|
1468 object.
|
|
1469
|
|
1470 (The @code{make-symbol} function returns an uninterned symbol that is
|
|
1471 not interned in the standard @code{obarray}. When uninterned symbols
|
|
1472 are in use, symbol names are no longer unique. Distinct symbols with
|
|
1473 the same name are not @code{eq}. @xref{Creating Symbols}.)
|
|
1474
|
|
1475 @example
|
|
1476 @group
|
|
1477 (eq 'foo 'foo)
|
|
1478 @result{} t
|
|
1479 @end group
|
|
1480
|
|
1481 @group
|
|
1482 (eq 456 456)
|
|
1483 @result{} t
|
|
1484 @end group
|
|
1485
|
|
1486 @group
|
|
1487 (eq "asdf" "asdf")
|
|
1488 @result{} nil
|
|
1489 @end group
|
|
1490
|
|
1491 @group
|
|
1492 (eq '(1 (2 (3))) '(1 (2 (3))))
|
|
1493 @result{} nil
|
|
1494 @end group
|
|
1495
|
|
1496 @group
|
|
1497 (setq foo '(1 (2 (3))))
|
|
1498 @result{} (1 (2 (3)))
|
|
1499 (eq foo foo)
|
|
1500 @result{} t
|
|
1501 (eq foo '(1 (2 (3))))
|
|
1502 @result{} nil
|
|
1503 @end group
|
|
1504
|
|
1505 @group
|
|
1506 (eq [(1 2) 3] [(1 2) 3])
|
|
1507 @result{} nil
|
|
1508 @end group
|
|
1509
|
|
1510 @group
|
|
1511 (eq (point-marker) (point-marker))
|
|
1512 @result{} nil
|
|
1513 @end group
|
|
1514 @end example
|
|
1515
|
|
1516 @end defun
|
|
1517
|
|
1518 @defun equal object1 object2
|
|
1519 This function returns @code{t} if @var{object1} and @var{object2} have
|
|
1520 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
|
|
1521 arguments are the same object, @code{equal} looks inside nonidentical
|
|
1522 arguments to see if their elements are the same. So, if two objects are
|
|
1523 @code{eq}, they are @code{equal}, but the converse is not always true.
|
|
1524
|
|
1525 @example
|
|
1526 @group
|
|
1527 (equal 'foo 'foo)
|
|
1528 @result{} t
|
|
1529 @end group
|
|
1530
|
|
1531 @group
|
|
1532 (equal 456 456)
|
|
1533 @result{} t
|
|
1534 @end group
|
|
1535
|
|
1536 @group
|
|
1537 (equal "asdf" "asdf")
|
|
1538 @result{} t
|
|
1539 @end group
|
|
1540 @group
|
|
1541 (eq "asdf" "asdf")
|
|
1542 @result{} nil
|
|
1543 @end group
|
|
1544
|
|
1545 @group
|
|
1546 (equal '(1 (2 (3))) '(1 (2 (3))))
|
|
1547 @result{} t
|
|
1548 @end group
|
|
1549 @group
|
|
1550 (eq '(1 (2 (3))) '(1 (2 (3))))
|
|
1551 @result{} nil
|
|
1552 @end group
|
|
1553
|
|
1554 @group
|
|
1555 (equal [(1 2) 3] [(1 2) 3])
|
|
1556 @result{} t
|
|
1557 @end group
|
|
1558 @group
|
|
1559 (eq [(1 2) 3] [(1 2) 3])
|
|
1560 @result{} nil
|
|
1561 @end group
|
|
1562
|
|
1563 @group
|
|
1564 (equal (point-marker) (point-marker))
|
|
1565 @result{} t
|
|
1566 @end group
|
|
1567
|
|
1568 @group
|
|
1569 (eq (point-marker) (point-marker))
|
|
1570 @result{} nil
|
|
1571 @end group
|
|
1572 @end example
|
|
1573
|
12067
|
1574 Comparison of strings is case-sensitive and takes account of text
|
|
1575 properties as well as the characters in the strings. To compare
|
|
1576 two strings' characters without comparing their text properties,
|
|
1577 use @code{string=} (@pxref{Text Comparison}).
|
6447
|
1578
|
|
1579 @example
|
|
1580 @group
|
|
1581 (equal "asdf" "ASDF")
|
|
1582 @result{} nil
|
|
1583 @end group
|
|
1584 @end example
|
12098
|
1585
|
|
1586 Two distinct buffers are never @code{equal}, even if their contents
|
|
1587 are the same.
|
6447
|
1588 @end defun
|
|
1589
|
|
1590 The test for equality is implemented recursively, and circular lists may
|
|
1591 therefore cause infinite recursion (leading to an error).
|