2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/objects
6 @node Lisp Data Types, Numbers, Introduction, Top
7 @chapter Lisp Data Types
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
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.
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 types}.
26 Each object belongs to one and only one primitive type. These types
27 include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
28 @dfn{string}, @dfn{vector}, @dfn{hash-table}, @dfn{subr}, and
29 @dfn{byte-code function}, plus several special types, such as
30 @dfn{buffer}, that are related to editing. (@xref{Editing Types}.)
32 Each primitive type has a corresponding Lisp function that checks
33 whether an object is a member of that type.
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.
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
43 variable can have any type of value, and it remembers whatever value
44 you store in it, type and all.
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.
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 * Circular Objects:: Read syntax for circular structure.
56 * Type Predicates:: Tests related to types.
57 * Equality Predicates:: Tests of equality between any two objects.
60 @node Printed Representation
61 @comment node-name, next, previous, up
62 @section Printed Representation and Read Syntax
63 @cindex printed representation
66 The @dfn{printed representation} of an object is the format of the
67 output generated by the Lisp printer (the function @code{prin1}) for
68 that object. The @dfn{read syntax} of an object is the format of the
69 input accepted by the Lisp reader (the function @code{read}) for that
70 object. @xref{Read and Print}.
72 Most objects have more than one possible read syntax. Some types of
73 object have no read syntax, since it may not make sense to enter objects
74 of these types directly in a Lisp program. Except for these cases, the
75 printed representation of an object is also a read syntax for it.
77 In other languages, an expression is text; it has no other form. In
78 Lisp, an expression is primarily a Lisp object and only secondarily the
79 text that is the object's read syntax. Often there is no need to
80 emphasize this distinction, but you must keep it in the back of your
81 mind, or you will occasionally be very confused.
84 Every type has a printed representation. Some types have no read
85 syntax---for example, the buffer type has none. Objects of these types
86 are printed in @dfn{hash notation}: the characters @samp{#<} followed by
87 a descriptive string (typically the type name followed by the name of
88 the object), and closed with a matching @samp{>}. Hash notation cannot
89 be read at all, so the Lisp reader signals the error
90 @code{invalid-read-syntax} whenever it encounters @samp{#<}.
91 @kindex invalid-read-syntax
95 @result{} #<buffer objects.texi>
98 When you evaluate an expression interactively, the Lisp interpreter
99 first reads the textual representation of it, producing a Lisp object,
100 and then evaluates that object (@pxref{Evaluation}). However,
101 evaluation and reading are separate activities. Reading returns the
102 Lisp object represented by the text that is read; the object may or may
103 not be evaluated later. @xref{Input Functions}, for a description of
104 @code{read}, the basic function for reading objects.
107 @comment node-name, next, previous, up
110 @cindex @samp{;} in comment
112 A @dfn{comment} is text that is written in a program only for the sake
113 of humans that read the program, and that has no effect on the meaning
114 of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
115 is not within a string or character constant. The comment continues to
116 the end of line. The Lisp reader discards comments; they do not become
117 part of the Lisp objects which represent the program within the Lisp
120 The @samp{#@@@var{count}} construct, which skips the next @var{count}
121 characters, is useful for program-generated comments containing binary
122 data. The Emacs Lisp byte compiler uses this in its output files
123 (@pxref{Byte Compilation}). It isn't meant for source files, however.
125 @xref{Comment Tips}, for conventions for formatting comments.
127 @node Programming Types
128 @section Programming Types
129 @cindex programming types
131 There are two general categories of types in Emacs Lisp: those having
132 to do with Lisp programming, and those having to do with editing. The
133 former exist in many Lisp implementations, in one form or another. The
134 latter are unique to Emacs Lisp.
137 * Integer Type:: Numbers without fractional parts.
138 * Floating Point Type:: Numbers with fractional parts and with a large range.
139 * Character Type:: The representation of letters, numbers and
141 * Symbol Type:: A multi-use object that refers to a function,
142 variable, or property list, and has a unique identity.
143 * Sequence Type:: Both lists and arrays are classified as sequences.
144 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
145 * Array Type:: Arrays include strings and vectors.
146 * String Type:: An (efficient) array of characters.
147 * Vector Type:: One-dimensional arrays.
148 * Char-Table Type:: One-dimensional sparse arrays indexed by characters.
149 * Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}.
150 * Hash Table Type:: Super-fast lookup tables.
151 * Function Type:: A piece of executable code you can call from elsewhere.
152 * Macro Type:: A method of expanding an expression into another
153 expression, more fundamental but less pretty.
154 * Primitive Function Type:: A function written in C, callable from Lisp.
155 * Byte-Code Type:: A function written in Lisp, then compiled.
156 * Autoload Type:: A type used for automatically loading seldom-used
161 @subsection Integer Type
163 The range of values for integers in Emacs Lisp is @minus{}134217728 to
164 134217727 (28 bits; i.e.,
178 on most machines. (Some machines may provide a wider range.) It is
179 important to note that the Emacs Lisp arithmetic functions do not check
180 for overflow. Thus @code{(1+ 134217727)} is @minus{}134217728 on most
183 The read syntax for integers is a sequence of (base ten) digits with an
184 optional sign at the beginning and an optional period at the end. The
185 printed representation produced by the Lisp interpreter never has a
186 leading @samp{+} or a final @samp{.}.
190 -1 ; @r{The integer -1.}
191 1 ; @r{The integer 1.}
192 1. ; @r{Also the integer 1.}
193 +1 ; @r{Also the integer 1.}
194 268435457 ; @r{Also the integer 1 on a 28-bit implementation.}
198 @xref{Numbers}, for more information.
200 @node Floating Point Type
201 @subsection Floating Point Type
203 Emacs supports floating point numbers (though there is a compilation
204 option to disable them). The precise range of floating point numbers is
207 The printed representation for floating point numbers requires either
208 a decimal point (with at least one digit following), an exponent, or
209 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
210 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
211 number whose value is 1500. They are all equivalent.
213 @xref{Numbers}, for more information.
216 @subsection Character Type
217 @cindex @sc{ascii} character codes
219 A @dfn{character} in Emacs Lisp is nothing more than an integer. In
220 other words, characters are represented by their character codes. For
221 example, the character @kbd{A} is represented as the @w{integer 65}.
223 Individual characters are not often used in programs. It is far more
224 common to work with @emph{strings}, which are sequences composed of
225 characters. @xref{String Type}.
227 Characters in strings, buffers, and files are currently limited to the
228 range of 0 to 524287---nineteen bits. But not all values in that range
229 are valid character codes. Codes 0 through 127 are ASCII codes; the
230 rest are non-ASCII (@pxref{Non-ASCII Characters}). Characters that represent
231 keyboard input have a much wider range, to encode modifier keys such as
232 Control, Meta and Shift.
234 @cindex read syntax for characters
235 @cindex printed representation for characters
236 @cindex syntax for characters
237 @cindex @samp{?} in character constant
238 @cindex question mark in character constant
239 Since characters are really integers, the printed representation of a
240 character is a decimal number. This is also a possible read syntax for
241 a character, but writing characters that way in Lisp programs is a very
242 bad idea. You should @emph{always} use the special read syntax formats
243 that Emacs Lisp provides for characters. These syntax formats start
244 with a question mark.
246 The usual read syntax for alphanumeric characters is a question mark
247 followed by the character; thus, @samp{?A} for the character
248 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
254 ?Q @result{} 81 ?q @result{} 113
257 You can use the same syntax for punctuation characters, but it is
258 often a good idea to add a @samp{\} so that the Emacs commands for
259 editing Lisp code don't get confused. For example, @samp{?\ } is the
260 way to write the space character. If the character is @samp{\}, you
261 @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
264 @cindex bell character
280 You can express the characters Control-g, backspace, tab, newline,
281 vertical tab, formfeed, return, and escape as @samp{?\a}, @samp{?\b},
282 @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e},
286 ?\a @result{} 7 ; @r{@kbd{C-g}}
287 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
288 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
289 ?\n @result{} 10 ; @r{newline, @kbd{C-j}}
290 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
291 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
292 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
293 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
294 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
295 ?\d @result{} 127 ; @r{delete character, @key{DEL}}
298 @cindex escape sequence
299 These sequences which start with backslash are also known as
300 @dfn{escape sequences}, because backslash plays the role of an escape
301 character; this usage has nothing to do with the character @key{ESC}.
303 @cindex control characters
304 Control characters may be represented using yet another read syntax.
305 This consists of a question mark followed by a backslash, caret, and the
306 corresponding non-control character, in either upper or lower case. For
307 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
308 character @kbd{C-i}, the character whose value is 9.
310 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
311 equivalent to @samp{?\^I} and to @samp{?\^i}:
314 ?\^I @result{} 9 ?\C-I @result{} 9
317 In strings and buffers, the only control characters allowed are those
318 that exist in @sc{ascii}; but for keyboard input purposes, you can turn
319 any character into a control character with @samp{C-}. The character
320 codes for these non-@sc{ascii} control characters include the
327 bit as well as the code for the corresponding non-control
328 character. Ordinary terminals have no way of generating non-@sc{ascii}
329 control characters, but you can generate them straightforwardly using X
330 and other window systems.
332 For historical reasons, Emacs treats the @key{DEL} character as
333 the control equivalent of @kbd{?}:
336 ?\^? @result{} 127 ?\C-? @result{} 127
340 As a result, it is currently not possible to represent the character
341 @kbd{Control-?}, which is a meaningful input character under X, using
342 @samp{\C-}. It is not easy to change this, as various Lisp files refer
343 to @key{DEL} in this way.
345 For representing control characters to be found in files or strings,
346 we recommend the @samp{^} syntax; for control characters in keyboard
347 input, we prefer the @samp{C-} syntax. Which one you use does not
348 affect the meaning of the program, but may guide the understanding of
351 @cindex meta characters
352 A @dfn{meta character} is a character typed with the @key{META}
353 modifier key. The integer that represents such a character has the
360 bit set (which on most machines makes it a negative number). We
361 use high bits for this and other modifiers to make possible a wide range
362 of basic character codes.
371 bit attached to an ASCII character indicates a meta character; thus, the
372 meta characters that can fit in a string have codes in the range from
373 128 to 255, and are the meta versions of the ordinary @sc{ascii}
374 characters. (In Emacs versions 18 and older, this convention was used
375 for characters outside of strings as well.)
377 The read syntax for meta characters uses @samp{\M-}. For example,
378 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
379 octal character codes (see below), with @samp{\C-}, or with any other
380 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
381 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
382 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
384 The case of a graphic character is indicated by its character code;
385 for example, @sc{ascii} distinguishes between the characters @samp{a}
386 and @samp{A}. But @sc{ascii} has no way to represent whether a control
387 character is upper case or lower case. Emacs uses the
394 bit to indicate that the shift key was used in typing a control
395 character. This distinction is possible only when you use X terminals
396 or other special terminals; ordinary terminals do not report the
397 distinction to the computer in any way. The Lisp syntax for
398 the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O}
399 represents the shifted-control-o character.
401 @cindex hyper characters
402 @cindex super characters
403 @cindex alt characters
404 The X Window System defines three other modifier bits that can be set
405 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
406 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is
407 significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents
408 @kbd{Alt-Hyper-Meta-x}.
411 bit values are @math{2^{22}} for alt, @math{2^{23}} for super and @math{2^{24}} for hyper.
415 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
418 @cindex @samp{\} in character constant
419 @cindex backslash in character constant
420 @cindex octal character code
421 Finally, the most general read syntax for a character represents the
422 character code in either octal or hex. To use octal, write a question
423 mark followed by a backslash and the octal character code (up to three
424 octal digits); thus, @samp{?\101} for the character @kbd{A},
425 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
426 character @kbd{C-b}. Although this syntax can represent any @sc{ascii}
427 character, it is preferred only when the precise octal value is more
428 important than the @sc{ascii} representation.
432 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
433 ?\101 @result{} 65 ?A @result{} 65
437 To use hex, write a question mark followed by a backslash, @samp{x},
438 and the hexadecimal character code. You can use any number of hex
439 digits, so you can represent any character code in this way.
440 Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
441 character @kbd{C-a}, and @code{?\x8e0} for the character
446 @samp{a} with grave accent.
449 A backslash is allowed, and harmless, preceding any character without
450 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
451 There is no reason to add a backslash before most characters. However,
452 you should add a backslash before any of the characters
453 @samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
454 Lisp code. Also add a backslash before whitespace characters such as
455 space, tab, newline and formfeed. However, it is cleaner to use one of
456 the easily readable escape sequences, such as @samp{\t}, instead of an
457 actual whitespace character such as a tab.
460 @subsection Symbol Type
462 A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The symbol
463 name serves as the printed representation of the symbol. In ordinary
464 use, the name is unique---no two symbols have the same name.
466 A symbol can serve as a variable, as a function name, or to hold a
467 property list. Or it may serve only to be distinct from all other Lisp
468 objects, so that its presence in a data structure may be recognized
469 reliably. In a given context, usually only one of these uses is
470 intended. But you can use one symbol in all of these ways,
473 A symbol whose name starts with a colon (@samp{:}) is called a
474 @dfn{keyword symbol}. These symbols automatically act as constants, and
475 are normally used only by comparing an unknown symbol with a few
476 specific alternatives.
478 @cindex @samp{\} in symbols
479 @cindex backslash in symbols
480 A symbol name can contain any characters whatever. Most symbol names
481 are written with letters, digits, and the punctuation characters
482 @samp{-+=*/}. Such names require no special punctuation; the characters
483 of the name suffice as long as the name does not look like a number.
484 (If it does, write a @samp{\} at the beginning of the name to force
485 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}} are
486 less often used but also require no special punctuation. Any other
487 characters may be included in a symbol's name by escaping them with a
488 backslash. In contrast to its use in strings, however, a backslash in
489 the name of a symbol simply quotes the single character that follows the
490 backslash. For example, in a string, @samp{\t} represents a tab
491 character; in the name of a symbol, however, @samp{\t} merely quotes the
492 letter @samp{t}. To have a symbol with a tab character in its name, you
493 must actually use a tab (preceded with a backslash). But it's rare to
496 @cindex CL note---case of letters
498 @b{Common Lisp note:} In Common Lisp, lower case letters are always
499 ``folded'' to upper case, unless they are explicitly escaped. In Emacs
500 Lisp, upper case and lower case letters are distinct.
503 Here are several examples of symbol names. Note that the @samp{+} in
504 the fifth example is escaped to prevent it from being read as a number.
505 This is not necessary in the sixth example because the rest of the name
506 makes it invalid as a number.
510 foo ; @r{A symbol named @samp{foo}.}
511 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
512 char-to-string ; @r{A symbol named @samp{char-to-string}.}
515 1+ ; @r{A symbol named @samp{1+}}
516 ; @r{(not @samp{+1}, which is an integer).}
519 \+1 ; @r{A symbol named @samp{+1}}
520 ; @r{(not a very readable name).}
523 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
524 @c the @'s in this next line use up three characters, hence the
525 @c apparent misalignment of the comment.
526 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
527 ; @r{These characters need not be escaped.}
531 @cindex @samp{#:} read syntax
532 Normally the Lisp reader interns all symbols (@pxref{Creating
533 Symbols}). To prevent interning, you can write @samp{#:} before the
537 @subsection Sequence Types
539 A @dfn{sequence} is a Lisp object that represents an ordered set of
540 elements. There are two kinds of sequence in Emacs Lisp, lists and
541 arrays. Thus, an object of type list or of type array is also
542 considered a sequence.
544 Arrays are further subdivided into strings, vectors, char-tables and
545 bool-vectors. Vectors can hold elements of any type, but string
546 elements must be characters, and bool-vector elements must be @code{t}
547 or @code{nil}. The characters in a string can have text properties like
548 characters in a buffer (@pxref{Text Properties}); vectors and
549 bool-vectors do not support text properties even when their elements
550 happen to be characters. Char-tables are like vectors except that they
551 are indexed by any valid character code.
553 Lists, strings and the other array types are different, but they have
554 important similarities. For example, all have a length @var{l}, and all
555 have elements which can be indexed from zero to @var{l} minus one.
556 Several functions, called sequence functions, accept any kind of
557 sequence. For example, the function @code{elt} can be used to extract
558 an element of a sequence, given its index. @xref{Sequences Arrays
561 It is generally impossible to read the same sequence twice, since
562 sequences are always created anew upon reading. If you read the read
563 syntax for a sequence twice, you get two sequences with equal contents.
564 There is one exception: the empty list @code{()} always stands for the
565 same object, @code{nil}.
568 @subsection Cons Cell and List Types
569 @cindex address field of register
570 @cindex decrement field of register
573 A @dfn{cons cell} is an object that consists of two slots, called the
574 @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or
575 @dfn{refer to} any Lisp object. We also say that ``the @sc{car} of
576 this cons cell is'' whatever object its @sc{car} slot currently holds,
577 and likewise for the @sc{cdr}.
580 A note to C programmers: in Lisp, we do not distinguish between
581 ``holding'' a value and ``pointing to'' the value, because pointers in
585 A @dfn{list} is a series of cons cells, linked together so that the
586 @sc{cdr} slot of each cons cell holds either the next cons cell or the
587 empty list. @xref{Lists}, for functions that work on lists. Because
588 most cons cells are used as part of lists, the phrase @dfn{list
589 structure} has come to refer to any structure made out of cons cells.
591 The names @sc{car} and @sc{cdr} derive from the history of Lisp. The
592 original Lisp implementation ran on an @w{IBM 704} computer which
593 divided words into two parts, called the ``address'' part and the
594 ``decrement''; @sc{car} was an instruction to extract the contents of
595 the address part of a register, and @sc{cdr} an instruction to extract
596 the contents of the decrement. By contrast, ``cons cells'' are named
597 for the function @code{cons} that creates them, which in turn was named
598 for its purpose, the construction of cells.
601 Because cons cells are so central to Lisp, we also have a word for
602 ``an object which is not a cons cell''. These objects are called
606 The read syntax and printed representation for lists are identical, and
607 consist of a left parenthesis, an arbitrary number of elements, and a
610 Upon reading, each object inside the parentheses becomes an element
611 of the list. That is, a cons cell is made for each element. The
612 @sc{car} slot of the cons cell holds the element, and its @sc{cdr}
613 slot refers to the next cons cell of the list, which holds the next
614 element in the list. The @sc{cdr} slot of the last cons cell is set to
617 @cindex box diagrams, for lists
618 @cindex diagrams, boxed, for lists
619 A list can be illustrated by a diagram in which the cons cells are
620 shown as pairs of boxes, like dominoes. (The Lisp reader cannot read
621 such an illustration; unlike the textual notation, which can be
622 understood by both humans and computers, the box illustrations can be
623 understood only by humans.) This picture represents the three-element
624 list @code{(rose violet buttercup)}:
628 --- --- --- --- --- ---
629 | | |--> | | |--> | | |--> nil
630 --- --- --- --- --- ---
633 --> rose --> violet --> buttercup
637 In this diagram, each box represents a slot that can hold or refer to
638 any Lisp object. Each pair of boxes represents a cons cell. Each arrow
639 represents a reference to a Lisp object, either an atom or another cons
642 In this example, the first box, which holds the @sc{car} of the first
643 cons cell, refers to or ``holds'' @code{rose} (a symbol). The second
644 box, holding the @sc{cdr} of the first cons cell, refers to the next
645 pair of boxes, the second cons cell. The @sc{car} of the second cons
646 cell is @code{violet}, and its @sc{cdr} is the third cons cell. The
647 @sc{cdr} of the third (and last) cons cell is @code{nil}.
649 Here is another diagram of the same list, @code{(rose violet
650 buttercup)}, sketched in a different manner:
654 --------------- ---------------- -------------------
655 | car | cdr | | car | cdr | | car | cdr |
656 | rose | o-------->| violet | o-------->| buttercup | nil |
658 --------------- ---------------- -------------------
662 @cindex @samp{(@dots{})} in lists
663 @cindex @code{nil} in lists
665 A list with no elements in it is the @dfn{empty list}; it is identical
666 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
669 Here are examples of lists written in Lisp syntax:
672 (A 2 "A") ; @r{A list of three elements.}
673 () ; @r{A list of no elements (the empty list).}
674 nil ; @r{A list of no elements (the empty list).}
675 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
676 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
677 (A nil) ; @r{Equivalent to the previous.}
678 ((A B C)) ; @r{A list of one element}
679 ; @r{(which is a list of three elements).}
682 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
683 depicted with boxes and arrows:
688 | | |--> | | |--> nil
697 * Dotted Pair Notation:: An alternative syntax for lists.
698 * Association List Type:: A specially constructed list.
701 @node Dotted Pair Notation
702 @comment node-name, next, previous, up
703 @subsubsection Dotted Pair Notation
704 @cindex dotted pair notation
705 @cindex @samp{.} in lists
707 @dfn{Dotted pair notation} is an alternative syntax for cons cells
708 that represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
709 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
710 the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted
711 pair notation is therefore more general than list syntax. In the dotted
712 pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
713 . nil)))}. For @code{nil}-terminated lists, you can use either
714 notation, but list notation is usually clearer and more convenient.
715 When printing a list, the dotted pair notation is only used if the
716 @sc{cdr} of a cons cell is not a list.
718 Here's an example using boxes to illustrate dotted pair notation.
719 This example shows the pair @code{(rose . violet)}:
732 You can combine dotted pair notation with list notation to represent
733 conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}.
734 You write a dot after the last element of the list, followed by the
735 @sc{cdr} of the final cons cell. For example, @code{(rose violet
736 . buttercup)} is equivalent to @code{(rose . (violet . buttercup))}.
737 The object looks like this:
742 | | |--> | | |--> buttercup
750 The syntax @code{(rose .@: violet .@: buttercup)} is invalid because
751 there is nothing that it could mean. If anything, it would say to put
752 @code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already
753 used for @code{violet}.
755 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))},
761 | | |--> | | |--> nil
769 Similarly, the three-element list @code{(rose violet buttercup)}
770 is equivalent to @code{(rose . (violet . (buttercup)))}.
776 --- --- --- --- --- ---
777 | | |--> | | |--> | | |--> nil
778 --- --- --- --- --- ---
781 --> rose --> violet --> buttercup
786 @node Association List Type
787 @comment node-name, next, previous, up
788 @subsubsection Association List Type
790 An @dfn{association list} or @dfn{alist} is a specially-constructed
791 list whose elements are cons cells. In each element, the @sc{car} is
792 considered a @dfn{key}, and the @sc{cdr} is considered an
793 @dfn{associated value}. (In some cases, the associated value is stored
794 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
795 stacks, since it is easy to add or remove associations at the front of
801 (setq alist-of-colors
802 '((rose . red) (lily . white) (buttercup . yellow)))
806 sets the variable @code{alist-of-colors} to an alist of three elements. In the
807 first element, @code{rose} is the key and @code{red} is the value.
809 @xref{Association Lists}, for a further explanation of alists and for
810 functions that work on alists. @xref{Hash Tables}, for another kind of
811 lookup table, which is much faster for handling a large number of keys.
814 @subsection Array Type
816 An @dfn{array} is composed of an arbitrary number of slots for
817 holding or referring to other Lisp objects, arranged in a contiguous block of
818 memory. Accessing any element of an array takes approximately the same
819 amount of time. In contrast, accessing an element of a list requires
820 time proportional to the position of the element in the list. (Elements
821 at the end of a list take longer to access than elements at the
822 beginning of a list.)
824 Emacs defines four types of array: strings, vectors, bool-vectors, and
827 A string is an array of characters and a vector is an array of
828 arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}.
829 These kinds of array may have any length up to the largest integer.
830 Char-tables are sparse arrays indexed by any valid character code; they
831 can hold arbitrary objects.
833 The first element of an array has index zero, the second element has
834 index 1, and so on. This is called @dfn{zero-origin} indexing. For
835 example, an array of four elements has indices 0, 1, 2, @w{and 3}. The
836 largest possible index value is one less than the length of the array.
837 Once an array is created, its length is fixed.
839 All Emacs Lisp arrays are one-dimensional. (Most other programming
840 languages support multidimensional arrays, but they are not essential;
841 you can get the same effect with an array of arrays.) Each type of
842 array has its own read syntax; see the following sections for details.
844 The array type is contained in the sequence type and
845 contains the string type, the vector type, the bool-vector type, and the
849 @subsection String Type
851 A @dfn{string} is an array of characters. Strings are used for many
852 purposes in Emacs, as can be expected in a text editor; for example, as
853 the names of Lisp symbols, as messages for the user, and to represent
854 text extracted from buffers. Strings in Lisp are constants: evaluation
855 of a string returns the same string.
857 @xref{Strings and Characters}, for functions that operate on strings.
860 * Syntax for Strings::
861 * Non-ASCII in Strings::
862 * Nonprinting Characters::
863 * Text Props and Strings::
866 @node Syntax for Strings
867 @subsubsection Syntax for Strings
869 @cindex @samp{"} in strings
870 @cindex double-quote in strings
871 @cindex @samp{\} in strings
872 @cindex backslash in strings
873 The read syntax for strings is a double-quote, an arbitrary number of
874 characters, and another double-quote, @code{"like this"}. To include a
875 double-quote in a string, precede it with a backslash; thus, @code{"\""}
876 is a string containing just a single double-quote character. Likewise,
877 you can include a backslash by preceding it with another backslash, like
878 this: @code{"this \\ is a single embedded backslash"}.
880 @cindex newline in strings
881 The newline character is not special in the read syntax for strings;
882 if you write a new line between the double-quotes, it becomes a
883 character in the string. But an escaped newline---one that is preceded
884 by @samp{\}---does not become part of the string; i.e., the Lisp reader
885 ignores an escaped newline while reading a string. An escaped space
886 @w{@samp{\ }} is likewise ignored.
889 "It is useful to include newlines
890 in documentation strings,
893 @result{} "It is useful to include newlines
894 in documentation strings,
895 but the newline is ignored if escaped."
898 @node Non-ASCII in Strings
899 @subsubsection Non-ASCII Characters in Strings
901 You can include a non-@sc{ascii} international character in a string
902 constant by writing it literally. There are two text representations
903 for non-@sc{ascii} characters in Emacs strings (and in buffers): unibyte
904 and multibyte. If the string constant is read from a multibyte source,
905 such as a multibyte buffer or string, or a file that would be visited as
906 multibyte, then the character is read as a multibyte character, and that
907 makes the string multibyte. If the string constant is read from a
908 unibyte source, then the character is read as unibyte and that makes the
911 You can also represent a multibyte non-@sc{ASCII} character with its
912 character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
913 digits as necessary. (Multibyte non-@sc{ASCII} character codes are all
914 greater than 256.) Any character which is not a valid hex digit
915 terminates this construct. If the next character in the string could be
916 interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
917 terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents
918 one character, @samp{a} with grave accent. @w{@samp{\ }} in a string
919 constant is just like backslash-newline; it does not contribute any
920 character to the string, but it does terminate the preceding hex escape.
922 Using a multibyte hex escape forces the string to multibyte. You can
923 represent a unibyte non-@sc{ascii} character with its character code,
924 which must be in the range from 128 (0200 octal) to 255 (0377 octal).
925 This forces a unibyte string.
927 @xref{Text Representations}, for more information about the two
928 text representations.
930 @node Nonprinting Characters
931 @subsubsection Nonprinting Characters in Strings
933 You can use the same backslash escape-sequences in a string constant
934 as in character literals (but do not use the question mark that begins a
935 character constant). For example, you can write a string containing the
936 nonprinting characters tab and @kbd{C-a}, with commas and spaces between
937 them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a
938 description of the read syntax for characters.
940 However, not all of the characters you can write with backslash
941 escape-sequences are valid in strings. The only control characters that
942 a string can hold are the @sc{ascii} control characters. Strings do not
943 distinguish case in @sc{ascii} control characters.
945 Properly speaking, strings cannot hold meta characters; but when a
946 string is to be used as a key sequence, there is a special convention
947 that provides a way to represent meta versions of @sc{ascii} characters in a
948 string. If you use the @samp{\M-} syntax to indicate a meta character
949 in a string constant, this sets the
956 bit of the character in the string. If the string is used in
957 @code{define-key} or @code{lookup-key}, this numeric code is translated
958 into the equivalent meta character. @xref{Character Type}.
960 Strings cannot hold characters that have the hyper, super, or alt
963 @node Text Props and Strings
964 @subsubsection Text Properties in Strings
966 A string can hold properties for the characters it contains, in
967 addition to the characters themselves. This enables programs that copy
968 text between strings and buffers to copy the text's properties with no
969 special effort. @xref{Text Properties}, for an explanation of what text
970 properties mean. Strings with text properties use a special read and
974 #("@var{characters}" @var{property-data}...)
978 where @var{property-data} consists of zero or more elements, in groups
982 @var{beg} @var{end} @var{plist}
986 The elements @var{beg} and @var{end} are integers, and together specify
987 a range of indices in the string; @var{plist} is the property list for
988 that range. For example,
991 #("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
995 represents a string whose textual contents are @samp{foo bar}, in which
996 the first three characters have a @code{face} property with value
997 @code{bold}, and the last three have a @code{face} property with value
998 @code{italic}. (The fourth character has no text properties, so its
999 property list is @code{nil}. It is not actually necessary to mention
1000 ranges with @code{nil} as the property list, since any characters not
1001 mentioned in any range will default to having no properties.)
1004 @subsection Vector Type
1006 A @dfn{vector} is a one-dimensional array of elements of any type. It
1007 takes a constant amount of time to access any element of a vector. (In
1008 a list, the access time of an element is proportional to the distance of
1009 the element from the beginning of the list.)
1011 The printed representation of a vector consists of a left square
1012 bracket, the elements, and a right square bracket. This is also the
1013 read syntax. Like numbers and strings, vectors are considered constants
1017 [1 "two" (three)] ; @r{A vector of three elements.}
1018 @result{} [1 "two" (three)]
1021 @xref{Vectors}, for functions that work with vectors.
1023 @node Char-Table Type
1024 @subsection Char-Table Type
1026 A @dfn{char-table} is a one-dimensional array of elements of any type,
1027 indexed by character codes. Char-tables have certain extra features to
1028 make them more useful for many jobs that involve assigning information
1029 to character codes---for example, a char-table can have a parent to
1030 inherit from, a default value, and a small number of extra slots to use for
1031 special purposes. A char-table can also specify a single value for
1032 a whole character set.
1034 The printed representation of a char-table is like a vector
1035 except that there is an extra @samp{#^} at the beginning.
1037 @xref{Char-Tables}, for special functions to operate on char-tables.
1038 Uses of char-tables include:
1042 Case tables (@pxref{Case Tables}).
1045 Character category tables (@pxref{Categories}).
1048 Display Tables (@pxref{Display Tables}).
1051 Syntax tables (@pxref{Syntax Tables}).
1054 @node Bool-Vector Type
1055 @subsection Bool-Vector Type
1057 A @dfn{bool-vector} is a one-dimensional array of elements that
1058 must be @code{t} or @code{nil}.
1060 The printed representation of a bool-vector is like a string, except
1061 that it begins with @samp{#&} followed by the length. The string
1062 constant that follows actually specifies the contents of the bool-vector
1063 as a bitmap---each ``character'' in the string contains 8 bits, which
1064 specify the next 8 elements of the bool-vector (1 stands for @code{t},
1065 and 0 for @code{nil}). The least significant bits of the character
1066 correspond to the lowest indices in the bool-vector. If the length is not a
1067 multiple of 8, the printed representation shows extra elements, but
1068 these extras really make no difference.
1071 (make-bool-vector 3 t)
1073 (make-bool-vector 3 nil)
1075 ;; @r{These are equal since only the first 3 bits are used.}
1076 (equal #&3"\377" #&3"\007")
1080 @node Hash Table Type
1081 @subsection Hash Table Type
1083 A hash table is a very fast kind of lookup table, somewhat like an
1084 alist in that it maps keys to corresponding values, but much faster.
1085 Hash tables are a new feature in Emacs 21; they have no read syntax, and
1086 print using hash notation. @xref{Hash Tables}.
1090 @result{} #<hash-table 'eql nil 0/65 0x83af980>
1094 @subsection Function Type
1096 Just as functions in other programming languages are executable,
1097 @dfn{Lisp function} objects are pieces of executable code. However,
1098 functions in Lisp are primarily Lisp objects, and only secondarily the
1099 text which represents them. These Lisp objects are lambda expressions:
1100 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
1103 In most programming languages, it is impossible to have a function
1104 without a name. In Lisp, a function has no intrinsic name. A lambda
1105 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
1106 Functions}). A named function in Lisp is actually a symbol with a valid
1107 function in its function cell (@pxref{Defining Functions}).
1109 Most of the time, functions are called when their names are written in
1110 Lisp expressions in Lisp programs. However, you can construct or obtain
1111 a function object at run time and then call it with the primitive
1112 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
1115 @subsection Macro Type
1117 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
1118 language. It is represented as an object much like a function, but with
1119 different argument-passing semantics. A Lisp macro has the form of a
1120 list whose first element is the symbol @code{macro} and whose @sc{cdr}
1121 is a Lisp function object, including the @code{lambda} symbol.
1123 Lisp macro objects are usually defined with the built-in
1124 @code{defmacro} function, but any list that begins with @code{macro} is
1125 a macro as far as Emacs is concerned. @xref{Macros}, for an explanation
1126 of how to write a macro.
1128 @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard
1129 Macros}) are entirely different things. When we use the word ``macro''
1130 without qualification, we mean a Lisp macro, not a keyboard macro.
1132 @node Primitive Function Type
1133 @subsection Primitive Function Type
1134 @cindex special forms
1136 A @dfn{primitive function} is a function callable from Lisp but
1137 written in the C programming language. Primitive functions are also
1138 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
1139 derived from ``subroutine''.) Most primitive functions evaluate all
1140 their arguments when they are called. A primitive function that does
1141 not evaluate all its arguments is called a @dfn{special form}
1142 (@pxref{Special Forms}).@refill
1144 It does not matter to the caller of a function whether the function is
1145 primitive. However, this does matter if you try to redefine a primitive
1146 with a function written in Lisp. The reason is that the primitive
1147 function may be called directly from C code. Calls to the redefined
1148 function from Lisp will use the new definition, but calls from C code
1149 may still use the built-in definition. Therefore, @strong{we discourage
1150 redefinition of primitive functions}.
1152 The term @dfn{function} refers to all Emacs functions, whether written
1153 in Lisp or C. @xref{Function Type}, for information about the
1154 functions written in Lisp.
1156 Primitive functions have no read syntax and print in hash notation
1157 with the name of the subroutine.
1161 (symbol-function 'car) ; @r{Access the function cell}
1162 ; @r{of the symbol.}
1163 @result{} #<subr car>
1164 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
1165 @result{} t ; @r{Yes.}
1169 @node Byte-Code Type
1170 @subsection Byte-Code Function Type
1172 The byte compiler produces @dfn{byte-code function objects}.
1173 Internally, a byte-code function object is much like a vector; however,
1174 the evaluator handles this data type specially when it appears as a
1175 function to be called. @xref{Byte Compilation}, for information about
1178 The printed representation and read syntax for a byte-code function
1179 object is like that for a vector, with an additional @samp{#} before the
1183 @subsection Autoload Type
1185 An @dfn{autoload object} is a list whose first element is the symbol
1186 @code{autoload}. It is stored as the function definition of a symbol,
1187 where it serves as a placeholder for the real definition. The autoload
1188 object says that the real definition is found in a file of Lisp code
1189 that should be loaded when necessary. It contains the name of the file,
1190 plus some other information about the real definition.
1192 After the file has been loaded, the symbol should have a new function
1193 definition that is not an autoload object. The new definition is then
1194 called as if it had been there to begin with. From the user's point of
1195 view, the function call works as expected, using the function definition
1198 An autoload object is usually created with the function
1199 @code{autoload}, which stores the object in the function cell of a
1200 symbol. @xref{Autoload}, for more details.
1203 @section Editing Types
1204 @cindex editing types
1206 The types in the previous section are used for general programming
1207 purposes, and most of them are common to most Lisp dialects. Emacs Lisp
1208 provides several additional data types for purposes connected with
1212 * Buffer Type:: The basic object of editing.
1213 * Marker Type:: A position in a buffer.
1214 * Window Type:: Buffers are displayed in windows.
1215 * Frame Type:: Windows subdivide frames.
1216 * Window Configuration Type:: Recording the way a frame is subdivided.
1217 * Frame Configuration Type:: Recording the status of all frames.
1218 * Process Type:: A process running on the underlying OS.
1219 * Stream Type:: Receive or send characters.
1220 * Keymap Type:: What function a keystroke invokes.
1221 * Overlay Type:: How an overlay is represented.
1225 @subsection Buffer Type
1227 A @dfn{buffer} is an object that holds text that can be edited
1228 (@pxref{Buffers}). Most buffers hold the contents of a disk file
1229 (@pxref{Files}) so they can be edited, but some are used for other
1230 purposes. Most buffers are also meant to be seen by the user, and
1231 therefore displayed, at some time, in a window (@pxref{Windows}). But a
1232 buffer need not be displayed in any window.
1234 The contents of a buffer are much like a string, but buffers are not
1235 used like strings in Emacs Lisp, and the available operations are
1236 different. For example, you can insert text efficiently into an
1237 existing buffer, altering the buffer's contents, whereas ``inserting''
1238 text into a string requires concatenating substrings, and the result is
1239 an entirely new string object.
1241 Each buffer has a designated position called @dfn{point}
1242 (@pxref{Positions}). At any time, one buffer is the @dfn{current
1243 buffer}. Most editing commands act on the contents of the current
1244 buffer in the neighborhood of point. Many of the standard Emacs
1245 functions manipulate or test the characters in the current buffer; a
1246 whole chapter in this manual is devoted to describing these functions
1249 Several other data structures are associated with each buffer:
1253 a local syntax table (@pxref{Syntax Tables});
1256 a local keymap (@pxref{Keymaps}); and,
1259 a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
1262 overlays (@pxref{Overlays}).
1265 text properties for the text in the buffer (@pxref{Text Properties}).
1269 The local keymap and variable list contain entries that individually
1270 override global bindings or values. These are used to customize the
1271 behavior of programs in different buffers, without actually changing the
1274 A buffer may be @dfn{indirect}, which means it shares the text
1275 of another buffer, but presents it differently. @xref{Indirect Buffers}.
1277 Buffers have no read syntax. They print in hash notation, showing the
1283 @result{} #<buffer objects.texi>
1288 @subsection Marker Type
1290 A @dfn{marker} denotes a position in a specific buffer. Markers
1291 therefore have two components: one for the buffer, and one for the
1292 position. Changes in the buffer's text automatically relocate the
1293 position value as necessary to ensure that the marker always points
1294 between the same two characters in the buffer.
1296 Markers have no read syntax. They print in hash notation, giving the
1297 current character position and the name of the buffer.
1302 @result{} #<marker at 10779 in objects.texi>
1306 @xref{Markers}, for information on how to test, create, copy, and move
1310 @subsection Window Type
1312 A @dfn{window} describes the portion of the terminal screen that Emacs
1313 uses to display a buffer. Every window has one associated buffer, whose
1314 contents appear in the window. By contrast, a given buffer may appear
1315 in one window, no window, or several windows.
1317 Though many windows may exist simultaneously, at any time one window
1318 is designated the @dfn{selected window}. This is the window where the
1319 cursor is (usually) displayed when Emacs is ready for a command. The
1320 selected window usually displays the current buffer, but this is not
1321 necessarily the case.
1323 Windows are grouped on the screen into frames; each window belongs to
1324 one and only one frame. @xref{Frame Type}.
1326 Windows have no read syntax. They print in hash notation, giving the
1327 window number and the name of the buffer being displayed. The window
1328 numbers exist to identify windows uniquely, since the buffer displayed
1329 in any given window can change frequently.
1334 @result{} #<window 1 on objects.texi>
1338 @xref{Windows}, for a description of the functions that work on windows.
1341 @subsection Frame Type
1343 A @dfn{frame} is a rectangle on the screen that contains one or more
1344 Emacs windows. A frame initially contains a single main window (plus
1345 perhaps a minibuffer window) which you can subdivide vertically or
1346 horizontally into smaller windows.
1348 Frames have no read syntax. They print in hash notation, giving the
1349 frame's title, plus its address in core (useful to identify the frame
1355 @result{} #<frame emacs@@psilocin.gnu.org 0xdac80>
1359 @xref{Frames}, for a description of the functions that work on frames.
1361 @node Window Configuration Type
1362 @subsection Window Configuration Type
1363 @cindex screen layout
1365 A @dfn{window configuration} stores information about the positions,
1366 sizes, and contents of the windows in a frame, so you can recreate the
1367 same arrangement of windows later.
1369 Window configurations do not have a read syntax; their print syntax
1370 looks like @samp{#<window-configuration>}. @xref{Window
1371 Configurations}, for a description of several functions related to
1372 window configurations.
1374 @node Frame Configuration Type
1375 @subsection Frame Configuration Type
1376 @cindex screen layout
1378 A @dfn{frame configuration} stores information about the positions,
1379 sizes, and contents of the windows in all frames. It is actually
1380 a list whose @sc{car} is @code{frame-configuration} and whose
1381 @sc{cdr} is an alist. Each alist element describes one frame,
1382 which appears as the @sc{car} of that element.
1384 @xref{Frame Configurations}, for a description of several functions
1385 related to frame configurations.
1388 @subsection Process Type
1390 The word @dfn{process} usually means a running program. Emacs itself
1391 runs in a process of this sort. However, in Emacs Lisp, a process is a
1392 Lisp object that designates a subprocess created by the Emacs process.
1393 Programs such as shells, GDB, ftp, and compilers, running in
1394 subprocesses of Emacs, extend the capabilities of Emacs.
1396 An Emacs subprocess takes textual input from Emacs and returns textual
1397 output to Emacs for further manipulation. Emacs can also send signals
1400 Process objects have no read syntax. They print in hash notation,
1401 giving the name of the process:
1406 @result{} (#<process shell>)
1410 @xref{Processes}, for information about functions that create, delete,
1411 return information about, send input or signals to, and receive output
1415 @subsection Stream Type
1417 A @dfn{stream} is an object that can be used as a source or sink for
1418 characters---either to supply characters for input or to accept them as
1419 output. Many different types can be used this way: markers, buffers,
1420 strings, and functions. Most often, input streams (character sources)
1421 obtain characters from the keyboard, a buffer, or a file, and output
1422 streams (character sinks) send characters to a buffer, such as a
1423 @file{*Help*} buffer, or to the echo area.
1425 The object @code{nil}, in addition to its other meanings, may be used
1426 as a stream. It stands for the value of the variable
1427 @code{standard-input} or @code{standard-output}. Also, the object
1428 @code{t} as a stream specifies input using the minibuffer
1429 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
1432 Streams have no special printed representation or read syntax, and
1433 print as whatever primitive type they are.
1435 @xref{Read and Print}, for a description of functions
1436 related to streams, including parsing and printing functions.
1439 @subsection Keymap Type
1441 A @dfn{keymap} maps keys typed by the user to commands. This mapping
1442 controls how the user's command input is executed. A keymap is actually
1443 a list whose @sc{car} is the symbol @code{keymap}.
1445 @xref{Keymaps}, for information about creating keymaps, handling prefix
1446 keys, local as well as global keymaps, and changing key bindings.
1449 @subsection Overlay Type
1451 An @dfn{overlay} specifies properties that apply to a part of a
1452 buffer. Each overlay applies to a specified range of the buffer, and
1453 contains a property list (a list whose elements are alternating property
1454 names and values). Overlay properties are used to present parts of the
1455 buffer temporarily in a different display style. Overlays have no read
1456 syntax, and print in hash notation, giving the buffer name and range of
1459 @xref{Overlays}, for how to create and use overlays.
1461 @node Circular Objects
1462 @section Read Syntax for Circular Objects
1463 @cindex circular structure, read syntax
1464 @cindex shared structure, read syntax
1465 @cindex @samp{#@var{n}=} read syntax
1466 @cindex @samp{#@var{n}#} read syntax
1468 In Emacs 21, to represent shared or circular structure within a
1469 complex of Lisp objects, you can use the reader constructs
1470 @samp{#@var{n}=} and @samp{#@var{n}#}.
1472 Use @code{#@var{n}=} before an object to label it for later reference;
1473 subsequently, you can use @code{#@var{n}#} to refer the same object in
1474 another place. Here, @var{n} is some integer. For example, here is how
1475 to make a list in which the first element recurs as the third element:
1482 This differs from ordinary syntax such as this
1489 which would result in a list whose first and third elements
1490 look alike but are not the same Lisp object. This shows the difference:
1494 (setq x '(#1=(a) b #1#)))
1495 (eq (nth 0 x) (nth 2 x))
1497 (setq x '((a) b (a)))
1498 (eq (nth 0 x) (nth 2 x))
1502 You can also use the same syntax to make a circular structure, which
1503 appears as an ``element'' within itself. Here is an example:
1510 This makes a list whose second element is the list itself.
1511 Here's how you can see that it really works:
1515 (setq x '#1=(a #1#)))
1520 The Lisp printer can produce this syntax to record circular and shared
1521 structure in a Lisp object, if you bind the variable @code{print-circle}
1522 to a non-@code{nil} value. @xref{Output Variables}.
1524 @node Type Predicates
1525 @section Type Predicates
1527 @cindex type checking
1528 @kindex wrong-type-argument
1530 The Emacs Lisp interpreter itself does not perform type checking on
1531 the actual arguments passed to functions when they are called. It could
1532 not do so, since function arguments in Lisp do not have declared data
1533 types, as they do in other programming languages. It is therefore up to
1534 the individual function to test whether each actual argument belongs to
1535 a type that the function can use.
1537 All built-in functions do check the types of their actual arguments
1538 when appropriate, and signal a @code{wrong-type-argument} error if an
1539 argument is of the wrong type. For example, here is what happens if you
1540 pass an argument to @code{+} that it cannot handle:
1545 @error{} Wrong type argument: number-or-marker-p, a
1549 @cindex type predicates
1550 @cindex testing types
1551 If you want your program to handle different types differently, you
1552 must do explicit type checking. The most common way to check the type
1553 of an object is to call a @dfn{type predicate} function. Emacs has a
1554 type predicate for each type, as well as some predicates for
1555 combinations of types.
1557 A type predicate function takes one argument; it returns @code{t} if
1558 the argument belongs to the appropriate type, and @code{nil} otherwise.
1559 Following a general Lisp convention for predicate functions, most type
1560 predicates' names end with @samp{p}.
1562 Here is an example which uses the predicates @code{listp} to check for
1563 a list and @code{symbolp} to check for a symbol.
1568 ;; If X is a symbol, put it on LIST.
1569 (setq list (cons x list)))
1571 ;; If X is a list, add its elements to LIST.
1572 (setq list (append x list)))
1574 ;; We handle only symbols and lists.
1575 (error "Invalid argument %s in add-on" x))))
1578 Here is a table of predefined type predicates, in alphabetical order,
1579 with references to further information.
1583 @xref{List-related Predicates, atom}.
1586 @xref{Array Functions, arrayp}.
1589 @xref{Bool-Vectors, bool-vector-p}.
1592 @xref{Buffer Basics, bufferp}.
1594 @item byte-code-function-p
1595 @xref{Byte-Code Type, byte-code-function-p}.
1598 @xref{Case Tables, case-table-p}.
1600 @item char-or-string-p
1601 @xref{Predicates for Strings, char-or-string-p}.
1604 @xref{Char-Tables, char-table-p}.
1607 @xref{Interactive Call, commandp}.
1610 @xref{List-related Predicates, consp}.
1612 @item display-table-p
1613 @xref{Display Tables, display-table-p}.
1616 @xref{Predicates on Numbers, floatp}.
1618 @item frame-configuration-p
1619 @xref{Frame Configurations, frame-configuration-p}.
1622 @xref{Deleting Frames, frame-live-p}.
1625 @xref{Frames, framep}.
1628 @xref{Functions, functionp}.
1630 @item integer-or-marker-p
1631 @xref{Predicates on Markers, integer-or-marker-p}.
1634 @xref{Predicates on Numbers, integerp}.
1637 @xref{Creating Keymaps, keymapp}.
1640 @xref{List-related Predicates, listp}.
1643 @xref{Predicates on Markers, markerp}.
1646 @xref{Predicates on Numbers, wholenump}.
1649 @xref{List-related Predicates, nlistp}.
1652 @xref{Predicates on Numbers, numberp}.
1654 @item number-or-marker-p
1655 @xref{Predicates on Markers, number-or-marker-p}.
1658 @xref{Overlays, overlayp}.
1661 @xref{Processes, processp}.
1664 @xref{Sequence Functions, sequencep}.
1667 @xref{Predicates for Strings, stringp}.
1670 @xref{Function Cells, subrp}.
1673 @xref{Symbols, symbolp}.
1675 @item syntax-table-p
1676 @xref{Syntax Tables, syntax-table-p}.
1678 @item user-variable-p
1679 @xref{Defining Variables, user-variable-p}.
1682 @xref{Vectors, vectorp}.
1684 @item window-configuration-p
1685 @xref{Window Configurations, window-configuration-p}.
1688 @xref{Deleting Windows, window-live-p}.
1691 @xref{Basic Windows, windowp}.
1694 The most general way to check the type of an object is to call the
1695 function @code{type-of}. Recall that each object belongs to one and
1696 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
1697 Data Types}). But @code{type-of} knows nothing about non-primitive
1698 types. In most cases, it is more convenient to use type predicates than
1701 @defun type-of object
1702 This function returns a symbol naming the primitive type of
1703 @var{object}. The value is one of the symbols @code{symbol},
1704 @code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector},
1705 @code{char-table}, @code{bool-vector}, @code{hash-table}, @code{subr},
1706 @code{compiled-function}, @code{marker}, @code{overlay}, @code{window},
1707 @code{buffer}, @code{frame}, @code{process}, or
1708 @code{window-configuration}.
1715 (type-of '()) ; @r{@code{()} is @code{nil}.}
1722 @node Equality Predicates
1723 @section Equality Predicates
1726 Here we describe two functions that test for equality between any two
1727 objects. Other functions test equality between objects of specific
1728 types, e.g., strings. For these predicates, see the appropriate chapter
1729 describing the data type.
1731 @defun eq object1 object2
1732 This function returns @code{t} if @var{object1} and @var{object2} are
1733 the same object, @code{nil} otherwise. The ``same object'' means that a
1734 change in one will be reflected by the same change in the other.
1736 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
1737 integers with the same value. Also, since symbol names are normally
1738 unique, if the arguments are symbols with the same name, they are
1739 @code{eq}. For other types (e.g., lists, vectors, strings), two
1740 arguments with the same contents or elements are not necessarily
1741 @code{eq} to each other: they are @code{eq} only if they are the same
1761 (eq '(1 (2 (3))) '(1 (2 (3))))
1766 (setq foo '(1 (2 (3))))
1767 @result{} (1 (2 (3)))
1770 (eq foo '(1 (2 (3))))
1775 (eq [(1 2) 3] [(1 2) 3])
1780 (eq (point-marker) (point-marker))
1785 The @code{make-symbol} function returns an uninterned symbol, distinct
1786 from the symbol that is used if you write the name in a Lisp expression.
1787 Distinct symbols with the same name are not @code{eq}. @xref{Creating
1792 (eq (make-symbol "foo") 'foo)
1798 @defun equal object1 object2
1799 This function returns @code{t} if @var{object1} and @var{object2} have
1800 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
1801 arguments are the same object, @code{equal} looks inside nonidentical
1802 arguments to see if their elements or contents are the same. So, if two
1803 objects are @code{eq}, they are @code{equal}, but the converse is not
1818 (equal "asdf" "asdf")
1827 (equal '(1 (2 (3))) '(1 (2 (3))))
1831 (eq '(1 (2 (3))) '(1 (2 (3))))
1836 (equal [(1 2) 3] [(1 2) 3])
1840 (eq [(1 2) 3] [(1 2) 3])
1845 (equal (point-marker) (point-marker))
1850 (eq (point-marker) (point-marker))
1855 Comparison of strings is case-sensitive, but does not take account of
1856 text properties---it compares only the characters in the strings.
1857 A unibyte string never equals a multibyte string unless the
1858 contents are entirely @sc{ascii} (@pxref{Text Representations}).
1862 (equal "asdf" "ASDF")
1867 However, two distinct buffers are never considered @code{equal}, even if
1868 their textual contents are the same.
1871 The test for equality is implemented recursively; for example, given
1872 two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})}
1873 returns @code{t} if and only if both the expressions below return
1877 (equal (car @var{x}) (car @var{y}))
1878 (equal (cdr @var{x}) (cdr @var{y}))
1881 Because of this recursive method, circular lists may therefore cause
1882 infinite recursion (leading to an error).