1 @c -*- mode: texinfo; coding: utf-8 -*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2017 Free Software
5 @c See the file elisp.texi for copying conditions.
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 @emph{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},
29 @dfn{byte-code function}, and @dfn{record}, plus several special
30 types, such as @dfn{buffer}, that are related to editing.
31 (@xref{Editing Types}.)
33 Each primitive type has a corresponding Lisp function that checks
34 whether an object is a member of that type.
36 Lisp is unlike many other languages in that its objects are
37 @dfn{self-typing}: the primitive type of each object is implicit in
38 the object itself. For example, if an object is a vector, nothing can
39 treat it as a number; Lisp knows it is a vector, not a number.
41 In most languages, the programmer must declare the data type of each
42 variable, and the type is known by the compiler but not represented in
43 the data. Such type declarations do not exist in Emacs Lisp. A Lisp
44 variable can have any type of value, and it remembers whatever value
45 you store in it, type and all. (Actually, a small number of Emacs
46 Lisp variables can only take on values of a certain type.
47 @xref{Variables with Restricted Values}.)
49 This chapter describes the purpose, printed representation, and read
50 syntax of each of the standard types in GNU Emacs Lisp. Details on how
51 to use these types can be found in later chapters.
54 * Printed Representation:: How Lisp objects are represented as text.
55 * Comments:: Comments and their formatting conventions.
56 * Programming Types:: Types found in all Lisp systems.
57 * Editing Types:: Types specific to Emacs.
58 * Circular Objects:: Read syntax for circular structure.
59 * Type Predicates:: Tests related to types.
60 * Equality Predicates:: Tests of equality between any two objects.
63 @node Printed Representation
64 @section Printed Representation and Read Syntax
65 @cindex printed representation
68 The @dfn{printed representation} of an object is the format of the
69 output generated by the Lisp printer (the function @code{prin1}) for
70 that object. Every data type has a unique printed representation.
71 The @dfn{read syntax} of an object is the format of the input accepted
72 by the Lisp reader (the function @code{read}) for that object. This
73 is not necessarily unique; many kinds of object have more than one
74 syntax. @xref{Read and Print}.
77 In most cases, an object's printed representation is also a read
78 syntax for the object. However, some types have no read syntax, since
79 it does not make sense to enter objects of these types as constants in
80 a Lisp program. These objects are printed in @dfn{hash notation},
81 which consists of the characters @samp{#<}, a descriptive string
82 (typically the type name followed by the name of the object), and a
83 closing @samp{>}. For example:
87 @result{} #<buffer objects.texi>
91 Hash notation cannot be read at all, so the Lisp reader signals the
92 error @code{invalid-read-syntax} whenever it encounters @samp{#<}.
93 @kindex invalid-read-syntax
95 In other languages, an expression is text; it has no other form. In
96 Lisp, an expression is primarily a Lisp object and only secondarily the
97 text that is the object's read syntax. Often there is no need to
98 emphasize this distinction, but you must keep it in the back of your
99 mind, or you will occasionally be very confused.
101 When you evaluate an expression interactively, the Lisp interpreter
102 first reads the textual representation of it, producing a Lisp object,
103 and then evaluates that object (@pxref{Evaluation}). However,
104 evaluation and reading are separate activities. Reading returns the
105 Lisp object represented by the text that is read; the object may or may
106 not be evaluated later. @xref{Input Functions}, for a description of
107 @code{read}, the basic function for reading objects.
112 @cindex @samp{;} in comment
114 A @dfn{comment} is text that is written in a program only for the sake
115 of humans that read the program, and that has no effect on the meaning
116 of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
117 is not within a string or character constant. The comment continues to
118 the end of line. The Lisp reader discards comments; they do not become
119 part of the Lisp objects which represent the program within the Lisp
122 The @samp{#@@@var{count}} construct, which skips the next @var{count}
123 characters, is useful for program-generated comments containing binary
124 data. The Emacs Lisp byte compiler uses this in its output files
125 (@pxref{Byte Compilation}). It isn't meant for source files, however.
127 @xref{Comment Tips}, for conventions for formatting comments.
129 @node Programming Types
130 @section Programming Types
131 @cindex programming types
133 There are two general categories of types in Emacs Lisp: those having
134 to do with Lisp programming, and those having to do with editing. The
135 former exist in many Lisp implementations, in one form or another. The
136 latter are unique to Emacs Lisp.
139 * Integer Type:: Numbers without fractional parts.
140 * Floating-Point Type:: Numbers with fractional parts and with a large range.
141 * Character Type:: The representation of letters, numbers and
143 * Symbol Type:: A multi-use object that refers to a function,
144 variable, or property list, and has a unique identity.
145 * Sequence Type:: Both lists and arrays are classified as sequences.
146 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
147 * Array Type:: Arrays include strings and vectors.
148 * String Type:: An (efficient) array of characters.
149 * Vector Type:: One-dimensional arrays.
150 * Char-Table Type:: One-dimensional sparse arrays indexed by characters.
151 * Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}.
152 * Hash Table Type:: Super-fast lookup tables.
153 * Function Type:: A piece of executable code you can call from elsewhere.
154 * Macro Type:: A method of expanding an expression into another
155 expression, more fundamental but less pretty.
156 * Primitive Function Type:: A function written in C, callable from Lisp.
157 * Byte-Code Type:: A function written in Lisp, then compiled.
158 * Record Type:: Compound objects with programmer-defined types.
159 * Type Descriptors:: Objects holding information about types.
160 * Autoload Type:: A type used for automatically loading seldom-used
162 * Finalizer Type:: Runs code when no longer reachable.
167 @subsection Integer Type
169 The range of values for an integer depends on the machine. The
170 minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e.,
184 but many machines provide a wider range.
185 Emacs Lisp arithmetic functions do not check for integer overflow. Thus
186 @code{(1+ 536870911)} is @minus{}536,870,912 if Emacs integers are 30 bits.
188 The read syntax for integers is a sequence of (base ten) digits with an
189 optional sign at the beginning and an optional period at the end. The
190 printed representation produced by the Lisp interpreter never has a
191 leading @samp{+} or a final @samp{.}.
195 -1 ; @r{The integer @minus{}1.}
196 1 ; @r{The integer 1.}
197 1. ; @r{Also the integer 1.}
198 +1 ; @r{Also the integer 1.}
203 As a special exception, if a sequence of digits specifies an integer
204 too large or too small to be a valid integer object, the Lisp reader
205 reads it as a floating-point number (@pxref{Floating-Point Type}).
206 For instance, if Emacs integers are 30 bits, @code{536870912} is read
207 as the floating-point number @code{536870912.0}.
209 @xref{Numbers}, for more information.
211 @node Floating-Point Type
212 @subsection Floating-Point Type
214 Floating-point numbers are the computer equivalent of scientific
215 notation; you can think of a floating-point number as a fraction
216 together with a power of ten. The precise number of significant
217 figures and the range of possible exponents is machine-specific; Emacs
218 uses the C data type @code{double} to store the value, and internally
219 this records a power of 2 rather than a power of 10.
221 The printed representation for floating-point numbers requires either
222 a decimal point (with at least one digit following), an exponent, or
223 both. For example, @samp{1500.0}, @samp{+15e2}, @samp{15.0e+2},
224 @samp{+1500000e-3}, and @samp{.15e4} are five ways of writing a floating-point
225 number whose value is 1500. They are all equivalent.
227 @xref{Numbers}, for more information.
230 @subsection Character Type
231 @cindex @acronym{ASCII} character codes
233 A @dfn{character} in Emacs Lisp is nothing more than an integer. In
234 other words, characters are represented by their character codes. For
235 example, the character @kbd{A} is represented as the @w{integer 65}.
237 Individual characters are used occasionally in programs, but it is
238 more common to work with @emph{strings}, which are sequences composed
239 of characters. @xref{String Type}.
241 Characters in strings and buffers are currently limited to the range
242 of 0 to 4194303---twenty two bits (@pxref{Character Codes}). Codes 0
243 through 127 are @acronym{ASCII} codes; the rest are
244 non-@acronym{ASCII} (@pxref{Non-ASCII Characters}). Characters that
245 represent keyboard input have a much wider range, to encode modifier
246 keys such as Control, Meta and Shift.
248 There are special functions for producing a human-readable textual
249 description of a character for the sake of messages. @xref{Describing
253 * Basic Char Syntax:: Syntax for regular characters.
254 * General Escape Syntax:: How to specify characters by their codes.
255 * Ctl-Char Syntax:: Syntax for control characters.
256 * Meta-Char Syntax:: Syntax for meta-characters.
257 * Other Char Bits:: Syntax for hyper-, super-, and alt-characters.
260 @node Basic Char Syntax
261 @subsubsection Basic Char Syntax
262 @cindex read syntax for characters
263 @cindex printed representation for characters
264 @cindex syntax for characters
265 @cindex @samp{?} in character constant
266 @cindex question mark in character constant
268 Since characters are really integers, the printed representation of
269 a character is a decimal number. This is also a possible read syntax
270 for a character, but writing characters that way in Lisp programs is
271 not clear programming. You should @emph{always} use the special read
272 syntax formats that Emacs Lisp provides for characters. These syntax
273 formats start with a question mark.
275 The usual read syntax for alphanumeric characters is a question mark
276 followed by the character; thus, @samp{?A} for the character
277 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
283 ?Q @result{} 81 ?q @result{} 113
286 You can use the same syntax for punctuation characters, but it is
287 often a good idea to add a @samp{\} so that the Emacs commands for
288 editing Lisp code don't get confused. For example, @samp{?\(} is the
289 way to write the open-paren character. If the character is @samp{\},
290 you @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
293 @cindex bell character
297 @cindex tab (ASCII character)
305 @cindex return (ASCII character)
307 @cindex escape (ASCII character)
309 @cindex space (ASCII character)
311 You can express the characters control-g, backspace, tab, newline,
312 vertical tab, formfeed, space, return, del, and escape as @samp{?\a},
313 @samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f},
314 @samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively.
315 (@samp{?\s} followed by a dash has a different meaning---it applies
316 the Super modifier to the following character.) Thus,
319 ?\a @result{} 7 ; @r{control-g, @kbd{C-g}}
320 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
321 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
322 ?\n @result{} 10 ; @r{newline, @kbd{C-j}}
323 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
324 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
325 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
326 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
327 ?\s @result{} 32 ; @r{space character, @key{SPC}}
328 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
329 ?\d @result{} 127 ; @r{delete character, @key{DEL}}
332 @cindex escape sequence
333 These sequences which start with backslash are also known as
334 @dfn{escape sequences}, because backslash plays the role of an
335 escape character; this has nothing to do with the
336 character @key{ESC}. @samp{\s} is meant for use in character
337 constants; in string constants, just write the space.
339 A backslash is allowed, and harmless, preceding any character without
340 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
341 There is no reason to add a backslash before most characters. However,
342 you should add a backslash before any of the characters
343 @samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
344 Lisp code. You can also add a backslash before whitespace characters such as
345 space, tab, newline and formfeed. However, it is cleaner to use one of
346 the easily readable escape sequences, such as @samp{\t} or @samp{\s},
347 instead of an actual whitespace character such as a tab or a space.
348 (If you do write backslash followed by a space, you should write
349 an extra space after the character constant to separate it from the
352 @node General Escape Syntax
353 @subsubsection General Escape Syntax
355 In addition to the specific escape sequences for special important
356 control characters, Emacs provides several types of escape syntax that
357 you can use to specify non-@acronym{ASCII} text characters.
361 @cindex @samp{\} in character constant
362 @cindex backslash in character constants
363 @cindex unicode character escape
364 You can specify characters by their Unicode names, if any.
365 @code{?\N@{@var{NAME}@}} represents the Unicode character named
366 @var{NAME}. Thus, @samp{?\N@{LATIN SMALL LETTER A WITH GRAVE@}} is
367 equivalent to @code{?Ã } and denotes the Unicode character U+00E0. To
368 simplify entering multi-line strings, you can replace spaces in the
369 names by non-empty sequences of whitespace (e.g., newlines).
372 You can specify characters by their Unicode values.
373 @code{?\N@{U+@var{X}@}} represents a character with Unicode code point
374 @var{X}, where @var{X} is a hexadecimal number. Also,
375 @code{?\u@var{xxxx}} and @code{?\U@var{xxxxxxxx}} represent code
376 points @var{xxxx} and @var{xxxxxxxx}, respectively, where each @var{x}
377 is a single hexadecimal digit. For example, @code{?\N@{U+E0@}},
378 @code{?\u00e0} and @code{?\U000000E0} are all equivalent to @code{?Ã }
379 and to @samp{?\N@{LATIN SMALL LETTER A WITH GRAVE@}}. The Unicode
380 Standard defines code points only up to @samp{U+@var{10ffff}}, so if
381 you specify a code point higher than that, Emacs signals an error.
384 You can specify characters by their hexadecimal character
385 codes. A hexadecimal escape sequence consists of a backslash,
386 @samp{x}, and the hexadecimal character code. Thus, @samp{?\x41} is
387 the character @kbd{A}, @samp{?\x1} is the character @kbd{C-a}, and
388 @code{?\xe0} is the character @kbd{Ã } (@kbd{a} with grave accent).
389 You can use any number of hex digits, so you can represent any
390 character code in this way.
393 @cindex octal character code
394 You can specify characters by their character code in
395 octal. An octal escape sequence consists of a backslash followed by
396 up to three octal digits; thus, @samp{?\101} for the character
397 @kbd{A}, @samp{?\001} for the character @kbd{C-a}, and @code{?\002}
398 for the character @kbd{C-b}. Only characters up to octal code 777 can
399 be specified this way.
403 These escape sequences may also be used in strings. @xref{Non-ASCII
406 @node Ctl-Char Syntax
407 @subsubsection Control-Character Syntax
409 @cindex control characters
410 Control characters can be represented using yet another read syntax.
411 This consists of a question mark followed by a backslash, caret, and the
412 corresponding non-control character, in either upper or lower case. For
413 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
414 character @kbd{C-i}, the character whose value is 9.
416 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
417 equivalent to @samp{?\^I} and to @samp{?\^i}:
420 ?\^I @result{} 9 ?\C-I @result{} 9
423 In strings and buffers, the only control characters allowed are those
424 that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn
425 any character into a control character with @samp{C-}. The character
426 codes for these non-@acronym{ASCII} control characters include the
433 bit as well as the code for the corresponding non-control character.
434 Ordinary text terminals have no way of generating non-@acronym{ASCII}
435 control characters, but you can generate them straightforwardly using
436 X and other window systems.
438 For historical reasons, Emacs treats the @key{DEL} character as
439 the control equivalent of @kbd{?}:
442 ?\^? @result{} 127 ?\C-? @result{} 127
446 As a result, it is currently not possible to represent the character
447 @kbd{Control-?}, which is a meaningful input character under X, using
448 @samp{\C-}. It is not easy to change this, as various Lisp files refer
449 to @key{DEL} in this way.
451 For representing control characters to be found in files or strings,
452 we recommend the @samp{^} syntax; for control characters in keyboard
453 input, we prefer the @samp{C-} syntax. Which one you use does not
454 affect the meaning of the program, but may guide the understanding of
457 @node Meta-Char Syntax
458 @subsubsection Meta-Character Syntax
460 @cindex meta characters
461 A @dfn{meta character} is a character typed with the @key{META}
462 modifier key. The integer that represents such a character has the
469 bit set. We use high bits for this and other modifiers to make
470 possible a wide range of basic character codes.
479 bit attached to an @acronym{ASCII} character indicates a meta
480 character; thus, the meta characters that can fit in a string have
481 codes in the range from 128 to 255, and are the meta versions of the
482 ordinary @acronym{ASCII} characters. @xref{Strings of Events}, for
483 details about @key{META}-handling in strings.
485 The read syntax for meta characters uses @samp{\M-}. For example,
486 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
487 octal character codes (see below), with @samp{\C-}, or with any other
488 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
489 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
490 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
492 @node Other Char Bits
493 @subsubsection Other Character Modifier Bits
495 The case of a graphic character is indicated by its character code;
496 for example, @acronym{ASCII} distinguishes between the characters @samp{a}
497 and @samp{A}. But @acronym{ASCII} has no way to represent whether a control
498 character is upper case or lower case. Emacs uses the
505 bit to indicate that the shift key was used in typing a control
506 character. This distinction is possible only when you use X terminals
507 or other special terminals; ordinary text terminals do not report the
508 distinction. The Lisp syntax for the shift bit is @samp{\S-}; thus,
509 @samp{?\C-\S-o} or @samp{?\C-\S-O} represents the shifted-control-o
512 @cindex hyper characters
513 @cindex super characters
514 @cindex alt characters
515 The X Window System defines three other
516 @anchor{modifier bits}modifier bits that can be set
517 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
518 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is
519 significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents
520 @kbd{Alt-Hyper-Meta-x}. (Note that @samp{\s} with no following @samp{-}
521 represents the space character.)
523 Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}}
524 for super and @math{2^{24}} for hyper.
528 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
532 @subsection Symbol Type
534 A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The
535 symbol name serves as the printed representation of the symbol. In
536 ordinary Lisp use, with one single obarray (@pxref{Creating Symbols}),
537 a symbol's name is unique---no two symbols have the same name.
539 A symbol can serve as a variable, as a function name, or to hold a
540 property list. Or it may serve only to be distinct from all other Lisp
541 objects, so that its presence in a data structure may be recognized
542 reliably. In a given context, usually only one of these uses is
543 intended. But you can use one symbol in all of these ways,
546 A symbol whose name starts with a colon (@samp{:}) is called a
547 @dfn{keyword symbol}. These symbols automatically act as constants,
548 and are normally used only by comparing an unknown symbol with a few
549 specific alternatives. @xref{Constant Variables}.
551 @cindex @samp{\} in symbols
552 @cindex backslash in symbols
553 A symbol name can contain any characters whatever. Most symbol names
554 are written with letters, digits, and the punctuation characters
555 @samp{-+=*/}. Such names require no special punctuation; the characters
556 of the name suffice as long as the name does not look like a number.
557 (If it does, write a @samp{\} at the beginning of the name to force
558 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}?} are
559 less often used but also require no special punctuation. Any other
560 characters may be included in a symbol's name by escaping them with a
561 backslash. In contrast to its use in strings, however, a backslash in
562 the name of a symbol simply quotes the single character that follows the
563 backslash. For example, in a string, @samp{\t} represents a tab
564 character; in the name of a symbol, however, @samp{\t} merely quotes the
565 letter @samp{t}. To have a symbol with a tab character in its name, you
566 must actually use a tab (preceded with a backslash). But it's rare to
569 @cindex CL note---case of letters
571 @b{Common Lisp note:} In Common Lisp, lower case letters are always
572 folded to upper case, unless they are explicitly escaped. In Emacs
573 Lisp, upper case and lower case letters are distinct.
576 Here are several examples of symbol names. Note that the @samp{+} in
577 the fourth example is escaped to prevent it from being read as a number.
578 This is not necessary in the sixth example because the rest of the name
579 makes it invalid as a number.
583 foo ; @r{A symbol named @samp{foo}.}
584 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
587 1+ ; @r{A symbol named @samp{1+}}
588 ; @r{(not @samp{+1}, which is an integer).}
591 \+1 ; @r{A symbol named @samp{+1}}
592 ; @r{(not a very readable name).}
595 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
596 @c the @'s in this next line use up three characters, hence the
597 @c apparent misalignment of the comment.
598 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
599 ; @r{These characters need not be escaped.}
603 @cindex @samp{##} read syntax
605 @c This uses "colon" instead of a literal ':' because Info cannot
606 @c cope with a ':' in a menu.
607 @cindex @samp{#@var{colon}} read syntax
610 @cindex @samp{#:} read syntax
612 As an exception to the rule that a symbol's name serves as its
613 printed representation, @samp{##} is the printed representation for an
614 interned symbol whose name is an empty string. Furthermore,
615 @samp{#:@var{foo}} is the printed representation for an uninterned
616 symbol whose name is @var{foo}. (Normally, the Lisp reader interns
617 all symbols; @pxref{Creating Symbols}.)
620 @subsection Sequence Types
622 A @dfn{sequence} is a Lisp object that represents an ordered set of
623 elements. There are two kinds of sequence in Emacs Lisp: @dfn{lists}
626 Lists are the most commonly-used sequences. A list can hold
627 elements of any type, and its length can be easily changed by adding
628 or removing elements. See the next subsection for more about lists.
630 Arrays are fixed-length sequences. They are further subdivided into
631 strings, vectors, char-tables and bool-vectors. Vectors can hold
632 elements of any type, whereas string elements must be characters, and
633 bool-vector elements must be @code{t} or @code{nil}. Char-tables are
634 like vectors except that they are indexed by any valid character code.
635 The characters in a string can have text properties like characters in
636 a buffer (@pxref{Text Properties}), but vectors do not support text
637 properties, even when their elements happen to be characters.
639 Lists, strings and the other array types also share important
640 similarities. For example, all have a length @var{l}, and all have
641 elements which can be indexed from zero to @var{l} minus one. Several
642 functions, called sequence functions, accept any kind of sequence.
643 For example, the function @code{length} reports the length of any kind
644 of sequence. @xref{Sequences Arrays Vectors}.
646 It is generally impossible to read the same sequence twice, since
647 sequences are always created anew upon reading. If you read the read
648 syntax for a sequence twice, you get two sequences with equal contents.
649 There is one exception: the empty list @code{()} always stands for the
650 same object, @code{nil}.
653 @subsection Cons Cell and List Types
654 @cindex address field of register
655 @cindex decrement field of register
658 A @dfn{cons cell} is an object that consists of two slots, called
659 the @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} any
660 Lisp object. We also say that the @sc{car} of this cons cell is
661 whatever object its @sc{car} slot currently holds, and likewise for
664 @cindex list structure
665 A @dfn{list} is a series of cons cells, linked together so that the
666 @sc{cdr} slot of each cons cell holds either the next cons cell or the
667 empty list. The empty list is actually the symbol @code{nil}.
668 @xref{Lists}, for details. Because most cons cells are used as part
669 of lists, we refer to any structure made out of cons cells as a
670 @dfn{list structure}.
674 A note to C programmers: a Lisp list thus works as a @dfn{linked list}
675 built up of cons cells. Because pointers in Lisp are implicit, we do
676 not distinguish between a cons cell slot holding a value versus
677 pointing to the value.
681 Because cons cells are so central to Lisp, we also have a word for
682 an object which is not a cons cell. These objects are called
686 @cindex @samp{(@dots{})} in lists
687 The read syntax and printed representation for lists are identical, and
688 consist of a left parenthesis, an arbitrary number of elements, and a
689 right parenthesis. Here are examples of lists:
692 (A 2 "A") ; @r{A list of three elements.}
693 () ; @r{A list of no elements (the empty list).}
694 nil ; @r{A list of no elements (the empty list).}
695 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
696 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
697 (A nil) ; @r{Equivalent to the previous.}
698 ((A B C)) ; @r{A list of one element}
699 ; @r{(which is a list of three elements).}
702 Upon reading, each object inside the parentheses becomes an element
703 of the list. That is, a cons cell is made for each element. The
704 @sc{car} slot of the cons cell holds the element, and its @sc{cdr}
705 slot refers to the next cons cell of the list, which holds the next
706 element in the list. The @sc{cdr} slot of the last cons cell is set to
709 The names @sc{car} and @sc{cdr} derive from the history of Lisp. The
710 original Lisp implementation ran on an @w{IBM 704} computer which
711 divided words into two parts, the address and the
712 decrement; @sc{car} was an instruction to extract the contents of
713 the address part of a register, and @sc{cdr} an instruction to extract
714 the contents of the decrement. By contrast, cons cells are named
715 for the function @code{cons} that creates them, which in turn was named
716 for its purpose, the construction of cells.
719 * Box Diagrams:: Drawing pictures of lists.
720 * Dotted Pair Notation:: A general syntax for cons cells.
721 * Association List Type:: A specially constructed list.
725 @subsubsection Drawing Lists as Box Diagrams
726 @cindex box diagrams, for lists
727 @cindex diagrams, boxed, for lists
729 A list can be illustrated by a diagram in which the cons cells are
730 shown as pairs of boxes, like dominoes. (The Lisp reader cannot read
731 such an illustration; unlike the textual notation, which can be
732 understood by both humans and computers, the box illustrations can be
733 understood only by humans.) This picture represents the three-element
734 list @code{(rose violet buttercup)}:
738 --- --- --- --- --- ---
739 | | |--> | | |--> | | |--> nil
740 --- --- --- --- --- ---
743 --> rose --> violet --> buttercup
747 In this diagram, each box represents a slot that can hold or refer to
748 any Lisp object. Each pair of boxes represents a cons cell. Each arrow
749 represents a reference to a Lisp object, either an atom or another cons
752 In this example, the first box, which holds the @sc{car} of the first
753 cons cell, refers to or holds @code{rose} (a symbol). The second
754 box, holding the @sc{cdr} of the first cons cell, refers to the next
755 pair of boxes, the second cons cell. The @sc{car} of the second cons
756 cell is @code{violet}, and its @sc{cdr} is the third cons cell. The
757 @sc{cdr} of the third (and last) cons cell is @code{nil}.
759 Here is another diagram of the same list, @code{(rose violet
760 buttercup)}, sketched in a different manner:
764 --------------- ---------------- -------------------
765 | car | cdr | | car | cdr | | car | cdr |
766 | rose | o-------->| violet | o-------->| buttercup | nil |
768 --------------- ---------------- -------------------
772 @cindex @code{nil} as a list
774 A list with no elements in it is the @dfn{empty list}; it is identical
775 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
778 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
779 depicted with boxes and arrows:
784 | | |--> | | |--> nil
792 Here is a more complex illustration, showing the three-element list,
793 @code{((pine needles) oak maple)}, the first element of which is a
798 --- --- --- --- --- ---
799 | | |--> | | |--> | | |--> nil
800 --- --- --- --- --- ---
806 --> | | |--> | | |--> nil
814 The same list represented in the second box notation looks like this:
818 -------------- -------------- --------------
819 | car | cdr | | car | cdr | | car | cdr |
820 | o | o------->| oak | o------->| maple | nil |
822 -- | --------- -------------- --------------
825 | -------------- ----------------
826 | | car | cdr | | car | cdr |
827 ------>| pine | o------->| needles | nil |
829 -------------- ----------------
833 @node Dotted Pair Notation
834 @subsubsection Dotted Pair Notation
835 @cindex dotted pair notation
836 @cindex @samp{.} in lists
838 @dfn{Dotted pair notation} is a general syntax for cons cells that
839 represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
840 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
841 the object @var{a} and whose @sc{cdr} is the object @var{b}. Dotted
842 pair notation is more general than list syntax because the @sc{cdr}
843 does not have to be a list. However, it is more cumbersome in cases
844 where list syntax would work. In dotted pair notation, the list
845 @samp{(1 2 3)} is written as @samp{(1 . (2 . (3 . nil)))}. For
846 @code{nil}-terminated lists, you can use either notation, but list
847 notation is usually clearer and more convenient. When printing a
848 list, the dotted pair notation is only used if the @sc{cdr} of a cons
851 Here's an example using boxes to illustrate dotted pair notation.
852 This example shows the pair @code{(rose . violet)}:
865 You can combine dotted pair notation with list notation to represent
866 conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}.
867 You write a dot after the last element of the list, followed by the
868 @sc{cdr} of the final cons cell. For example, @code{(rose violet
869 . buttercup)} is equivalent to @code{(rose . (violet . buttercup))}.
870 The object looks like this:
875 | | |--> | | |--> buttercup
883 The syntax @code{(rose .@: violet .@: buttercup)} is invalid because
884 there is nothing that it could mean. If anything, it would say to put
885 @code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already
886 used for @code{violet}.
888 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))},
894 | | |--> | | |--> nil
902 Similarly, the three-element list @code{(rose violet buttercup)}
903 is equivalent to @code{(rose . (violet . (buttercup)))}.
909 --- --- --- --- --- ---
910 | | |--> | | |--> | | |--> nil
911 --- --- --- --- --- ---
914 --> rose --> violet --> buttercup
919 @node Association List Type
920 @subsubsection Association List Type
922 An @dfn{association list} or @dfn{alist} is a specially-constructed
923 list whose elements are cons cells. In each element, the @sc{car} is
924 considered a @dfn{key}, and the @sc{cdr} is considered an
925 @dfn{associated value}. (In some cases, the associated value is stored
926 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
927 stacks, since it is easy to add or remove associations at the front of
933 (setq alist-of-colors
934 '((rose . red) (lily . white) (buttercup . yellow)))
938 sets the variable @code{alist-of-colors} to an alist of three elements. In the
939 first element, @code{rose} is the key and @code{red} is the value.
941 @xref{Association Lists}, for a further explanation of alists and for
942 functions that work on alists. @xref{Hash Tables}, for another kind of
943 lookup table, which is much faster for handling a large number of keys.
946 @subsection Array Type
948 An @dfn{array} is composed of an arbitrary number of slots for
949 holding or referring to other Lisp objects, arranged in a contiguous block of
950 memory. Accessing any element of an array takes approximately the same
951 amount of time. In contrast, accessing an element of a list requires
952 time proportional to the position of the element in the list. (Elements
953 at the end of a list take longer to access than elements at the
954 beginning of a list.)
956 Emacs defines four types of array: strings, vectors, bool-vectors, and
959 A string is an array of characters and a vector is an array of
960 arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}.
961 These kinds of array may have any length up to the largest integer.
962 Char-tables are sparse arrays indexed by any valid character code; they
963 can hold arbitrary objects.
965 The first element of an array has index zero, the second element has
966 index 1, and so on. This is called @dfn{zero-origin} indexing. For
967 example, an array of four elements has indices 0, 1, 2, @w{and 3}. The
968 largest possible index value is one less than the length of the array.
969 Once an array is created, its length is fixed.
971 All Emacs Lisp arrays are one-dimensional. (Most other programming
972 languages support multidimensional arrays, but they are not essential;
973 you can get the same effect with nested one-dimensional arrays.) Each
974 type of array has its own read syntax; see the following sections for
977 The array type is a subset of the sequence type, and contains the
978 string type, the vector type, the bool-vector type, and the char-table
982 @subsection String Type
984 A @dfn{string} is an array of characters. Strings are used for many
985 purposes in Emacs, as can be expected in a text editor; for example, as
986 the names of Lisp symbols, as messages for the user, and to represent
987 text extracted from buffers. Strings in Lisp are constants: evaluation
988 of a string returns the same string.
990 @xref{Strings and Characters}, for functions that operate on strings.
993 * Syntax for Strings:: How to specify Lisp strings.
994 * Non-ASCII in Strings:: International characters in strings.
995 * Nonprinting Characters:: Literal unprintable characters in strings.
996 * Text Props and Strings:: Strings with text properties.
999 @node Syntax for Strings
1000 @subsubsection Syntax for Strings
1002 @cindex @samp{"} in strings
1003 @cindex double-quote in strings
1004 @cindex @samp{\} in strings
1005 @cindex backslash in strings
1006 The read syntax for a string is a double-quote, an arbitrary number
1007 of characters, and another double-quote, @code{"like this"}. To
1008 include a double-quote in a string, precede it with a backslash; thus,
1009 @code{"\""} is a string containing just one double-quote
1010 character. Likewise, you can include a backslash by preceding it with
1011 another backslash, like this: @code{"this \\ is a single embedded
1014 @cindex newline in strings
1015 The newline character is not special in the read syntax for strings;
1016 if you write a new line between the double-quotes, it becomes a
1017 character in the string. But an escaped newline---one that is preceded
1018 by @samp{\}---does not become part of the string; i.e., the Lisp reader
1019 ignores an escaped newline while reading a string. An escaped space
1020 @w{@samp{\ }} is likewise ignored.
1023 "It is useful to include newlines
1024 in documentation strings,
1025 but the newline is \
1026 ignored if escaped."
1027 @result{} "It is useful to include newlines
1028 in documentation strings,
1029 but the newline is ignored if escaped."
1032 @node Non-ASCII in Strings
1033 @subsubsection Non-@acronym{ASCII} Characters in Strings
1035 There are two text representations for non-@acronym{ASCII}
1036 characters in Emacs strings: multibyte and unibyte (@pxref{Text
1037 Representations}). Roughly speaking, unibyte strings store raw bytes,
1038 while multibyte strings store human-readable text. Each character in
1039 a unibyte string is a byte, i.e., its value is between 0 and 255. By
1040 contrast, each character in a multibyte string may have a value
1041 between 0 to 4194303 (@pxref{Character Type}). In both cases,
1042 characters above 127 are non-@acronym{ASCII}.
1044 You can include a non-@acronym{ASCII} character in a string constant
1045 by writing it literally. If the string constant is read from a
1046 multibyte source, such as a multibyte buffer or string, or a file that
1047 would be visited as multibyte, then Emacs reads each
1048 non-@acronym{ASCII} character as a multibyte character and
1049 automatically makes the string a multibyte string. If the string
1050 constant is read from a unibyte source, then Emacs reads the
1051 non-@acronym{ASCII} character as unibyte, and makes the string
1054 Instead of writing a character literally into a multibyte string,
1055 you can write it as its character code using an escape sequence.
1056 @xref{General Escape Syntax}, for details about escape sequences.
1058 If you use any Unicode-style escape sequence @samp{\uNNNN} or
1059 @samp{\U00NNNNNN} in a string constant (even for an @acronym{ASCII}
1060 character), Emacs automatically assumes that it is multibyte.
1062 You can also use hexadecimal escape sequences (@samp{\x@var{n}}) and
1063 octal escape sequences (@samp{\@var{n}}) in string constants.
1064 @strong{But beware:} If a string constant contains hexadecimal or
1065 octal escape sequences, and these escape sequences all specify unibyte
1066 characters (i.e., less than 256), and there are no other literal
1067 non-@acronym{ASCII} characters or Unicode-style escape sequences in
1068 the string, then Emacs automatically assumes that it is a unibyte
1069 string. That is to say, it assumes that all non-@acronym{ASCII}
1070 characters occurring in the string are 8-bit raw bytes.
1072 In hexadecimal and octal escape sequences, the escaped character
1073 code may contain a variable number of digits, so the first subsequent
1074 character which is not a valid hexadecimal or octal digit terminates
1075 the escape sequence. If the next character in a string could be
1076 interpreted as a hexadecimal or octal digit, write @w{@samp{\ }}
1077 (backslash and space) to terminate the escape sequence. For example,
1078 @w{@samp{\xe0\ }} represents one character, @samp{a} with grave
1079 accent. @w{@samp{\ }} in a string constant is just like
1080 backslash-newline; it does not contribute any character to the string,
1081 but it does terminate any preceding hex escape.
1083 @node Nonprinting Characters
1084 @subsubsection Nonprinting Characters in Strings
1086 You can use the same backslash escape-sequences in a string constant
1087 as in character literals (but do not use the question mark that begins a
1088 character constant). For example, you can write a string containing the
1089 nonprinting characters tab and @kbd{C-a}, with commas and spaces between
1090 them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a
1091 description of the read syntax for characters.
1093 However, not all of the characters you can write with backslash
1094 escape-sequences are valid in strings. The only control characters that
1095 a string can hold are the @acronym{ASCII} control characters. Strings do not
1096 distinguish case in @acronym{ASCII} control characters.
1098 Properly speaking, strings cannot hold meta characters; but when a
1099 string is to be used as a key sequence, there is a special convention
1100 that provides a way to represent meta versions of @acronym{ASCII}
1101 characters in a string. If you use the @samp{\M-} syntax to indicate
1102 a meta character in a string constant, this sets the
1109 bit of the character in the string. If the string is used in
1110 @code{define-key} or @code{lookup-key}, this numeric code is translated
1111 into the equivalent meta character. @xref{Character Type}.
1113 Strings cannot hold characters that have the hyper, super, or alt
1116 @node Text Props and Strings
1117 @subsubsection Text Properties in Strings
1119 @cindex @samp{#(} read syntax
1120 @cindex text properties, read syntax
1121 A string can hold properties for the characters it contains, in
1122 addition to the characters themselves. This enables programs that copy
1123 text between strings and buffers to copy the text's properties with no
1124 special effort. @xref{Text Properties}, for an explanation of what text
1125 properties mean. Strings with text properties use a special read and
1129 #("@var{characters}" @var{property-data}...)
1133 where @var{property-data} consists of zero or more elements, in groups
1134 of three as follows:
1137 @var{beg} @var{end} @var{plist}
1141 The elements @var{beg} and @var{end} are integers, and together specify
1142 a range of indices in the string; @var{plist} is the property list for
1143 that range. For example,
1146 #("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
1150 represents a string whose textual contents are @samp{foo bar}, in which
1151 the first three characters have a @code{face} property with value
1152 @code{bold}, and the last three have a @code{face} property with value
1153 @code{italic}. (The fourth character has no text properties, so its
1154 property list is @code{nil}. It is not actually necessary to mention
1155 ranges with @code{nil} as the property list, since any characters not
1156 mentioned in any range will default to having no properties.)
1159 @subsection Vector Type
1161 A @dfn{vector} is a one-dimensional array of elements of any type. It
1162 takes a constant amount of time to access any element of a vector. (In
1163 a list, the access time of an element is proportional to the distance of
1164 the element from the beginning of the list.)
1166 The printed representation of a vector consists of a left square
1167 bracket, the elements, and a right square bracket. This is also the
1168 read syntax. Like numbers and strings, vectors are considered constants
1172 [1 "two" (three)] ; @r{A vector of three elements.}
1173 @result{} [1 "two" (three)]
1176 @xref{Vectors}, for functions that work with vectors.
1178 @node Char-Table Type
1179 @subsection Char-Table Type
1181 A @dfn{char-table} is a one-dimensional array of elements of any type,
1182 indexed by character codes. Char-tables have certain extra features to
1183 make them more useful for many jobs that involve assigning information
1184 to character codes---for example, a char-table can have a parent to
1185 inherit from, a default value, and a small number of extra slots to use for
1186 special purposes. A char-table can also specify a single value for
1187 a whole character set.
1189 @cindex @samp{#^} read syntax
1190 The printed representation of a char-table is like a vector
1191 except that there is an extra @samp{#^} at the beginning.@footnote{You
1192 may also encounter @samp{#^^}, used for sub-char-tables.}
1194 @xref{Char-Tables}, for special functions to operate on char-tables.
1195 Uses of char-tables include:
1199 Case tables (@pxref{Case Tables}).
1202 Character category tables (@pxref{Categories}).
1205 Display tables (@pxref{Display Tables}).
1208 Syntax tables (@pxref{Syntax Tables}).
1211 @node Bool-Vector Type
1212 @subsection Bool-Vector Type
1214 A @dfn{bool-vector} is a one-dimensional array whose elements must
1215 be @code{t} or @code{nil}.
1217 The printed representation of a bool-vector is like a string, except
1218 that it begins with @samp{#&} followed by the length. The string
1219 constant that follows actually specifies the contents of the bool-vector
1220 as a bitmap---each character in the string contains 8 bits, which
1221 specify the next 8 elements of the bool-vector (1 stands for @code{t},
1222 and 0 for @code{nil}). The least significant bits of the character
1223 correspond to the lowest indices in the bool-vector.
1226 (make-bool-vector 3 t)
1228 (make-bool-vector 3 nil)
1233 These results make sense, because the binary code for @samp{C-g} is
1234 111 and @samp{C-@@} is the character with code 0.
1236 If the length is not a multiple of 8, the printed representation
1237 shows extra elements, but these extras really make no difference. For
1238 instance, in the next example, the two bool-vectors are equal, because
1239 only the first 3 bits are used:
1242 (equal #&3"\377" #&3"\007")
1246 @node Hash Table Type
1247 @subsection Hash Table Type
1249 A hash table is a very fast kind of lookup table, somewhat like an
1250 alist in that it maps keys to corresponding values, but much faster.
1251 The printed representation of a hash table specifies its properties
1252 and contents, like this:
1256 @result{} #s(hash-table size 65 test eql rehash-size 1.5
1257 rehash-threshold 0.8125 data ())
1261 @xref{Hash Tables}, for more information about hash tables.
1264 @subsection Function Type
1266 Lisp functions are executable code, just like functions in other
1267 programming languages. In Lisp, unlike most languages, functions are
1268 also Lisp objects. A non-compiled function in Lisp is a lambda
1269 expression: that is, a list whose first element is the symbol
1270 @code{lambda} (@pxref{Lambda Expressions}).
1272 In most programming languages, it is impossible to have a function
1273 without a name. In Lisp, a function has no intrinsic name. A lambda
1274 expression can be called as a function even though it has no name; to
1275 emphasize this, we also call it an @dfn{anonymous function}
1276 (@pxref{Anonymous Functions}). A named function in Lisp is just a
1277 symbol with a valid function in its function cell (@pxref{Defining
1280 Most of the time, functions are called when their names are written in
1281 Lisp expressions in Lisp programs. However, you can construct or obtain
1282 a function object at run time and then call it with the primitive
1283 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
1286 @subsection Macro Type
1288 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
1289 language. It is represented as an object much like a function, but with
1290 different argument-passing semantics. A Lisp macro has the form of a
1291 list whose first element is the symbol @code{macro} and whose @sc{cdr}
1292 is a Lisp function object, including the @code{lambda} symbol.
1294 Lisp macro objects are usually defined with the built-in
1295 @code{defmacro} macro, but any list that begins with @code{macro} is a
1296 macro as far as Emacs is concerned. @xref{Macros}, for an explanation
1297 of how to write a macro.
1299 @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard
1300 Macros}) are entirely different things. When we use the word ``macro''
1301 without qualification, we mean a Lisp macro, not a keyboard macro.
1303 @node Primitive Function Type
1304 @subsection Primitive Function Type
1305 @cindex primitive function
1307 A @dfn{primitive function} is a function callable from Lisp but
1308 written in the C programming language. Primitive functions are also
1309 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
1310 derived from ``subroutine''.) Most primitive functions evaluate all
1311 their arguments when they are called. A primitive function that does
1312 not evaluate all its arguments is called a @dfn{special form}
1313 (@pxref{Special Forms}).
1315 It does not matter to the caller of a function whether the function is
1316 primitive. However, this does matter if you try to redefine a primitive
1317 with a function written in Lisp. The reason is that the primitive
1318 function may be called directly from C code. Calls to the redefined
1319 function from Lisp will use the new definition, but calls from C code
1320 may still use the built-in definition. Therefore, @strong{we discourage
1321 redefinition of primitive functions}.
1323 The term @dfn{function} refers to all Emacs functions, whether written
1324 in Lisp or C@. @xref{Function Type}, for information about the
1325 functions written in Lisp.
1327 Primitive functions have no read syntax and print in hash notation
1328 with the name of the subroutine.
1332 (symbol-function 'car) ; @r{Access the function cell}
1333 ; @r{of the symbol.}
1334 @result{} #<subr car>
1335 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
1336 @result{} t ; @r{Yes.}
1340 @node Byte-Code Type
1341 @subsection Byte-Code Function Type
1343 @dfn{Byte-code function objects} are produced by byte-compiling Lisp
1344 code (@pxref{Byte Compilation}). Internally, a byte-code function
1345 object is much like a vector; however, the evaluator handles this data
1346 type specially when it appears in a function call. @xref{Byte-Code
1349 The printed representation and read syntax for a byte-code function
1350 object is like that for a vector, with an additional @samp{#} before the
1354 @subsection Record Type
1356 A @dfn{record} is much like a @code{vector}. However, the first
1357 element is used to hold its type as returned by @code{type-of}. The
1358 purpose of records is to allow programmers to create objects with new
1359 types that are not built into Emacs.
1361 @xref{Records}, for functions that work with records.
1363 @node Type Descriptors
1364 @subsection Type Descriptors
1366 A @dfn{type descriptor} is a @code{record} which holds information
1367 about a type. Slot 1 in the record must be a symbol naming the type, and
1368 @code{type-of} relies on this to return the type of @code{record}
1369 objects. No other type descriptor slot is used by Emacs; they are
1370 free for use by Lisp extensions.
1372 An example of a type descriptor is any instance of
1373 @code{cl-structure-class}.
1376 @subsection Autoload Type
1378 An @dfn{autoload object} is a list whose first element is the symbol
1379 @code{autoload}. It is stored as the function definition of a symbol,
1380 where it serves as a placeholder for the real definition. The autoload
1381 object says that the real definition is found in a file of Lisp code
1382 that should be loaded when necessary. It contains the name of the file,
1383 plus some other information about the real definition.
1385 After the file has been loaded, the symbol should have a new function
1386 definition that is not an autoload object. The new definition is then
1387 called as if it had been there to begin with. From the user's point of
1388 view, the function call works as expected, using the function definition
1391 An autoload object is usually created with the function
1392 @code{autoload}, which stores the object in the function cell of a
1393 symbol. @xref{Autoload}, for more details.
1395 @node Finalizer Type
1396 @subsection Finalizer Type
1398 A @dfn{finalizer object} helps Lisp code clean up after objects that
1399 are no longer needed. A finalizer holds a Lisp function object.
1400 When a finalizer object becomes unreachable after a garbage collection
1401 pass, Emacs calls the finalizer's associated function object.
1402 When deciding whether a finalizer is reachable, Emacs does not count
1403 references from finalizer objects themselves, allowing you to use
1404 finalizers without having to worry about accidentally capturing
1405 references to finalized objects themselves.
1407 Errors in finalizers are printed to @code{*Messages*}. Emacs runs
1408 a given finalizer object's associated function exactly once, even
1409 if that function fails.
1411 @defun make-finalizer function
1412 Make a finalizer that will run @var{function}. @var{function} will be
1413 called after garbage collection when the returned finalizer object
1414 becomes unreachable. If the finalizer object is reachable only
1415 through references from finalizer objects, it does not count as
1416 reachable for the purpose of deciding whether to run @var{function}.
1417 @var{function} will be run once per finalizer object.
1421 @section Editing Types
1422 @cindex editing types
1424 The types in the previous section are used for general programming
1425 purposes, and most of them are common to most Lisp dialects. Emacs Lisp
1426 provides several additional data types for purposes connected with
1430 * Buffer Type:: The basic object of editing.
1431 * Marker Type:: A position in a buffer.
1432 * Window Type:: Buffers are displayed in windows.
1433 * Frame Type:: Windows subdivide frames.
1434 * Terminal Type:: A terminal device displays frames.
1435 * Window Configuration Type:: Recording the way a frame is subdivided.
1436 * Frame Configuration Type:: Recording the status of all frames.
1437 * Process Type:: A subprocess of Emacs running on the underlying OS.
1438 * Thread Type:: A thread of Emacs Lisp execution.
1439 * Mutex Type:: An exclusive lock for thread synchronization.
1440 * Condition Variable Type:: Condition variable for thread synchronization.
1441 * Stream Type:: Receive or send characters.
1442 * Keymap Type:: What function a keystroke invokes.
1443 * Overlay Type:: How an overlay is represented.
1444 * Font Type:: Fonts for displaying text.
1448 @subsection Buffer Type
1450 A @dfn{buffer} is an object that holds text that can be edited
1451 (@pxref{Buffers}). Most buffers hold the contents of a disk file
1452 (@pxref{Files}) so they can be edited, but some are used for other
1453 purposes. Most buffers are also meant to be seen by the user, and
1454 therefore displayed, at some time, in a window (@pxref{Windows}). But
1455 a buffer need not be displayed in any window. Each buffer has a
1456 designated position called @dfn{point} (@pxref{Positions}); most
1457 editing commands act on the contents of the current buffer in the
1458 neighborhood of point. At any time, one buffer is the @dfn{current
1461 The contents of a buffer are much like a string, but buffers are not
1462 used like strings in Emacs Lisp, and the available operations are
1463 different. For example, you can insert text efficiently into an
1464 existing buffer, altering the buffer's contents, whereas inserting
1465 text into a string requires concatenating substrings, and the result
1466 is an entirely new string object.
1468 Many of the standard Emacs functions manipulate or test the
1469 characters in the current buffer; a whole chapter in this manual is
1470 devoted to describing these functions (@pxref{Text}).
1472 Several other data structures are associated with each buffer:
1476 a local syntax table (@pxref{Syntax Tables});
1479 a local keymap (@pxref{Keymaps}); and,
1482 a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
1485 overlays (@pxref{Overlays}).
1488 text properties for the text in the buffer (@pxref{Text Properties}).
1492 The local keymap and variable list contain entries that individually
1493 override global bindings or values. These are used to customize the
1494 behavior of programs in different buffers, without actually changing the
1497 A buffer may be @dfn{indirect}, which means it shares the text
1498 of another buffer, but presents it differently. @xref{Indirect Buffers}.
1500 Buffers have no read syntax. They print in hash notation, showing the
1506 @result{} #<buffer objects.texi>
1511 @subsection Marker Type
1513 A @dfn{marker} denotes a position in a specific buffer. Markers
1514 therefore have two components: one for the buffer, and one for the
1515 position. Changes in the buffer's text automatically relocate the
1516 position value as necessary to ensure that the marker always points
1517 between the same two characters in the buffer.
1519 Markers have no read syntax. They print in hash notation, giving the
1520 current character position and the name of the buffer.
1525 @result{} #<marker at 10779 in objects.texi>
1529 @xref{Markers}, for information on how to test, create, copy, and move
1533 @subsection Window Type
1535 A @dfn{window} describes the portion of the terminal screen that Emacs
1536 uses to display a buffer. Every window has one associated buffer, whose
1537 contents appear in the window. By contrast, a given buffer may appear
1538 in one window, no window, or several windows.
1540 Though many windows may exist simultaneously, at any time one window
1541 is designated the @dfn{selected window}. This is the window where the
1542 cursor is (usually) displayed when Emacs is ready for a command. The
1543 selected window usually displays the current buffer (@pxref{Current
1544 Buffer}), but this is not necessarily the case.
1546 Windows are grouped on the screen into frames; each window belongs to
1547 one and only one frame. @xref{Frame Type}.
1549 Windows have no read syntax. They print in hash notation, giving the
1550 window number and the name of the buffer being displayed. The window
1551 numbers exist to identify windows uniquely, since the buffer displayed
1552 in any given window can change frequently.
1557 @result{} #<window 1 on objects.texi>
1561 @xref{Windows}, for a description of the functions that work on windows.
1564 @subsection Frame Type
1566 A @dfn{frame} is a screen area that contains one or more Emacs
1567 windows; we also use the term ``frame'' to refer to the Lisp object
1568 that Emacs uses to refer to the screen area.
1570 Frames have no read syntax. They print in hash notation, giving the
1571 frame's title, plus its address in core (useful to identify the frame
1577 @result{} #<frame emacs@@psilocin.gnu.org 0xdac80>
1581 @xref{Frames}, for a description of the functions that work on frames.
1584 @subsection Terminal Type
1585 @cindex terminal type
1587 A @dfn{terminal} is a device capable of displaying one or more
1588 Emacs frames (@pxref{Frame Type}).
1590 Terminals have no read syntax. They print in hash notation giving
1591 the terminal's ordinal number and its TTY device file name.
1595 (get-device-terminal nil)
1596 @result{} #<terminal 1 on /dev/tty>
1600 @c FIXME: add an xref to where terminal-related primitives are described.
1602 @node Window Configuration Type
1603 @subsection Window Configuration Type
1604 @cindex window layout in a frame
1606 A @dfn{window configuration} stores information about the positions,
1607 sizes, and contents of the windows in a frame, so you can recreate the
1608 same arrangement of windows later.
1610 Window configurations do not have a read syntax; their print syntax
1611 looks like @samp{#<window-configuration>}. @xref{Window
1612 Configurations}, for a description of several functions related to
1613 window configurations.
1615 @node Frame Configuration Type
1616 @subsection Frame Configuration Type
1617 @cindex screen layout
1618 @cindex window layout, all frames
1620 A @dfn{frame configuration} stores information about the positions,
1621 sizes, and contents of the windows in all frames. It is not a
1622 primitive type---it is actually a list whose @sc{car} is
1623 @code{frame-configuration} and whose @sc{cdr} is an alist. Each alist
1624 element describes one frame, which appears as the @sc{car} of that
1627 @xref{Frame Configurations}, for a description of several functions
1628 related to frame configurations.
1631 @subsection Process Type
1633 The word @dfn{process} usually means a running program. Emacs itself
1634 runs in a process of this sort. However, in Emacs Lisp, a process is a
1635 Lisp object that designates a subprocess created by the Emacs process.
1636 Programs such as shells, GDB, ftp, and compilers, running in
1637 subprocesses of Emacs, extend the capabilities of Emacs.
1638 An Emacs subprocess takes textual input from Emacs and returns textual
1639 output to Emacs for further manipulation. Emacs can also send signals
1642 Process objects have no read syntax. They print in hash notation,
1643 giving the name of the process:
1648 @result{} (#<process shell>)
1652 @xref{Processes}, for information about functions that create, delete,
1653 return information about, send input or signals to, and receive output
1657 @subsection Thread Type
1659 A @dfn{thread} in Emacs represents a separate thread of Emacs Lisp
1660 execution. It runs its own Lisp program, has its own current buffer,
1661 and can have subprocesses locked to it, i.e.@: subprocesses whose
1662 output only this thread can accept. @xref{Threads}.
1664 Thread objects have no read syntax. They print in hash notation,
1665 giving the name of the thread (if it has been given a name) or its
1671 @result{} (#<thread 0176fc40>)
1676 @subsection Mutex Type
1678 A @dfn{mutex} is an exclusive lock that threads can own and disown,
1679 in order to synchronize between them. @xref{Mutexes}.
1681 Mutex objects have no read syntax. They print in hash notation,
1682 giving the name of the mutex (if it has been given a name) or its
1687 (make-mutex "my-mutex")
1688 @result{} #<mutex my-mutex>
1690 @result{} #<mutex 01c7e4e0>
1694 @node Condition Variable Type
1695 @subsection Condition Variable Type
1697 A @dfn{condition variable} is a device for a more complex thread
1698 synchronization than the one supported by a mutex. A thread can wait
1699 on a condition variable, to be woken up when some other thread
1700 notifies the condition.
1702 Condition variable objects have no read syntax. They print in hash
1703 notation, giving the name of the condition variable (if it has been
1704 given a name) or its address in core:
1708 (make-condition-variable (make-mutex))
1709 @result{} #<condvar 01c45ae8>
1714 @subsection Stream Type
1716 A @dfn{stream} is an object that can be used as a source or sink for
1717 characters---either to supply characters for input or to accept them as
1718 output. Many different types can be used this way: markers, buffers,
1719 strings, and functions. Most often, input streams (character sources)
1720 obtain characters from the keyboard, a buffer, or a file, and output
1721 streams (character sinks) send characters to a buffer, such as a
1722 @file{*Help*} buffer, or to the echo area.
1724 The object @code{nil}, in addition to its other meanings, may be used
1725 as a stream. It stands for the value of the variable
1726 @code{standard-input} or @code{standard-output}. Also, the object
1727 @code{t} as a stream specifies input using the minibuffer
1728 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
1731 Streams have no special printed representation or read syntax, and
1732 print as whatever primitive type they are.
1734 @xref{Read and Print}, for a description of functions
1735 related to streams, including parsing and printing functions.
1738 @subsection Keymap Type
1740 A @dfn{keymap} maps keys typed by the user to commands. This mapping
1741 controls how the user's command input is executed. A keymap is actually
1742 a list whose @sc{car} is the symbol @code{keymap}.
1744 @xref{Keymaps}, for information about creating keymaps, handling prefix
1745 keys, local as well as global keymaps, and changing key bindings.
1748 @subsection Overlay Type
1750 An @dfn{overlay} specifies properties that apply to a part of a
1751 buffer. Each overlay applies to a specified range of the buffer, and
1752 contains a property list (a list whose elements are alternating property
1753 names and values). Overlay properties are used to present parts of the
1754 buffer temporarily in a different display style. Overlays have no read
1755 syntax, and print in hash notation, giving the buffer name and range of
1758 @xref{Overlays}, for information on how you can create and use overlays.
1761 @subsection Font Type
1763 A @dfn{font} specifies how to display text on a graphical terminal.
1764 There are actually three separate font types---@dfn{font objects},
1765 @dfn{font specs}, and @dfn{font entities}---each of which has slightly
1766 different properties. None of them have a read syntax; their print
1767 syntax looks like @samp{#<font-object>}, @samp{#<font-spec>}, and
1768 @samp{#<font-entity>} respectively. @xref{Low-Level Font}, for a
1769 description of these Lisp objects.
1771 @node Circular Objects
1772 @section Read Syntax for Circular Objects
1773 @cindex circular structure, read syntax
1774 @cindex shared structure, read syntax
1775 @cindex @samp{#@var{n}=} read syntax
1776 @cindex @samp{#@var{n}#} read syntax
1778 To represent shared or circular structures within a complex of Lisp
1779 objects, you can use the reader constructs @samp{#@var{n}=} and
1782 Use @code{#@var{n}=} before an object to label it for later reference;
1783 subsequently, you can use @code{#@var{n}#} to refer the same object in
1784 another place. Here, @var{n} is some integer. For example, here is how
1785 to make a list in which the first element recurs as the third element:
1792 This differs from ordinary syntax such as this
1799 which would result in a list whose first and third elements
1800 look alike but are not the same Lisp object. This shows the difference:
1804 (setq x '(#1=(a) b #1#)))
1805 (eq (nth 0 x) (nth 2 x))
1807 (setq x '((a) b (a)))
1808 (eq (nth 0 x) (nth 2 x))
1812 You can also use the same syntax to make a circular structure, which
1813 appears as an element within itself. Here is an example:
1820 This makes a list whose second element is the list itself.
1821 Here's how you can see that it really works:
1825 (setq x '#1=(a #1#)))
1830 The Lisp printer can produce this syntax to record circular and shared
1831 structure in a Lisp object, if you bind the variable @code{print-circle}
1832 to a non-@code{nil} value. @xref{Output Variables}.
1834 @node Type Predicates
1835 @section Type Predicates
1836 @cindex type checking
1837 @kindex wrong-type-argument
1839 The Emacs Lisp interpreter itself does not perform type checking on
1840 the actual arguments passed to functions when they are called. It could
1841 not do so, since function arguments in Lisp do not have declared data
1842 types, as they do in other programming languages. It is therefore up to
1843 the individual function to test whether each actual argument belongs to
1844 a type that the function can use.
1846 All built-in functions do check the types of their actual arguments
1847 when appropriate, and signal a @code{wrong-type-argument} error if an
1848 argument is of the wrong type. For example, here is what happens if you
1849 pass an argument to @code{+} that it cannot handle:
1854 @error{} Wrong type argument: number-or-marker-p, a
1858 @cindex type predicates
1859 @cindex testing types
1860 If you want your program to handle different types differently, you
1861 must do explicit type checking. The most common way to check the type
1862 of an object is to call a @dfn{type predicate} function. Emacs has a
1863 type predicate for each type, as well as some predicates for
1864 combinations of types.
1866 A type predicate function takes one argument; it returns @code{t} if
1867 the argument belongs to the appropriate type, and @code{nil} otherwise.
1868 Following a general Lisp convention for predicate functions, most type
1869 predicates' names end with @samp{p}.
1871 Here is an example which uses the predicates @code{listp} to check for
1872 a list and @code{symbolp} to check for a symbol.
1877 ;; If X is a symbol, put it on LIST.
1878 (setq list (cons x list)))
1880 ;; If X is a list, add its elements to LIST.
1881 (setq list (append x list)))
1883 ;; We handle only symbols and lists.
1884 (error "Invalid argument %s in add-on" x))))
1887 Here is a table of predefined type predicates, in alphabetical order,
1888 with references to further information.
1892 @xref{List-related Predicates, atom}.
1895 @xref{Array Functions, arrayp}.
1898 @xref{Bool-Vectors, bool-vector-p}.
1901 @xref{Buffer Basics, bufferp}.
1903 @item byte-code-function-p
1904 @xref{Byte-Code Type, byte-code-function-p}.
1907 @xref{Case Tables, case-table-p}.
1909 @item char-or-string-p
1910 @xref{Predicates for Strings, char-or-string-p}.
1913 @xref{Char-Tables, char-table-p}.
1916 @xref{Interactive Call, commandp}.
1918 @item condition-variable-p
1919 @xref{Condition Variables, condition-variable-p}.
1922 @xref{List-related Predicates, consp}.
1924 @item custom-variable-p
1925 @xref{Variable Definitions, custom-variable-p}.
1928 @xref{Predicates on Numbers, floatp}.
1931 @xref{Low-Level Font}.
1933 @item frame-configuration-p
1934 @xref{Frame Configurations, frame-configuration-p}.
1937 @xref{Deleting Frames, frame-live-p}.
1940 @xref{Frames, framep}.
1943 @xref{Functions, functionp}.
1946 @xref{Other Hash, hash-table-p}.
1948 @item integer-or-marker-p
1949 @xref{Predicates on Markers, integer-or-marker-p}.
1952 @xref{Predicates on Numbers, integerp}.
1955 @xref{Creating Keymaps, keymapp}.
1958 @xref{Constant Variables}.
1961 @xref{List-related Predicates, listp}.
1964 @xref{Predicates on Markers, markerp}.
1967 @xref{Mutexes, mutexp}.
1970 @xref{Predicates on Numbers, wholenump}.
1973 @xref{List-related Predicates, nlistp}.
1976 @xref{Predicates on Numbers, numberp}.
1978 @item number-or-marker-p
1979 @xref{Predicates on Markers, number-or-marker-p}.
1982 @xref{Overlays, overlayp}.
1985 @xref{Processes, processp}.
1988 @xref{Record Type, recordp}.
1991 @xref{Sequence Functions, sequencep}.
1994 @xref{Predicates for Strings, stringp}.
1997 @xref{Function Cells, subrp}.
2000 @xref{Symbols, symbolp}.
2002 @item syntax-table-p
2003 @xref{Syntax Tables, syntax-table-p}.
2006 @xref{Basic Thread Functions, threadp}.
2009 @xref{Vectors, vectorp}.
2011 @item window-configuration-p
2012 @xref{Window Configurations, window-configuration-p}.
2015 @xref{Deleting Windows, window-live-p}.
2018 @xref{Basic Windows, windowp}.
2021 @xref{nil and t, booleanp}.
2023 @item string-or-null-p
2024 @xref{Predicates for Strings, string-or-null-p}.
2027 @xref{Basic Thread Functions, threadp}.
2030 @xref{Mutexes, mutexp}.
2032 @item condition-variable-p
2033 @xref{Condition Variables, condition-variable-p}.
2036 The most general way to check the type of an object is to call the
2037 function @code{type-of}. Recall that each object belongs to one and
2038 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
2039 Data Types}). But @code{type-of} knows nothing about non-primitive
2040 types. In most cases, it is more convenient to use type predicates than
2043 @defun type-of object
2044 This function returns a symbol naming the primitive type of
2045 @var{object}. The value is one of the symbols @code{bool-vector},
2046 @code{buffer}, @code{char-table}, @code{compiled-function},
2047 @code{condition-variable}, @code{cons}, @code{finalizer},
2048 @code{float}, @code{font-entity}, @code{font-object},
2049 @code{font-spec}, @code{frame}, @code{hash-table}, @code{integer},
2050 @code{marker}, @code{mutex}, @code{overlay}, @code{process},
2051 @code{string}, @code{subr}, @code{symbol}, @code{thread},
2052 @code{vector}, @code{window}, or @code{window-configuration}.
2053 However, if @var{object} is a record, the type specified by its first
2054 slot is returned; @ref{Records}.
2062 (type-of '()) ; @r{@code{()} is @code{nil}.}
2066 (type-of (record 'foo))
2072 @node Equality Predicates
2073 @section Equality Predicates
2076 Here we describe functions that test for equality between two
2077 objects. Other functions test equality of contents between objects of
2078 specific types, e.g., strings. For these predicates, see the
2079 appropriate chapter describing the data type.
2081 @defun eq object1 object2
2082 This function returns @code{t} if @var{object1} and @var{object2} are
2083 the same object, and @code{nil} otherwise.
2085 If @var{object1} and @var{object2} are integers with the same value,
2086 they are considered to be the same object (i.e., @code{eq} returns
2087 @code{t}). If @var{object1} and @var{object2} are symbols with the
2088 same name, they are normally the same object---but see @ref{Creating
2089 Symbols} for exceptions. For other types (e.g., lists, vectors,
2090 strings), two arguments with the same contents or elements are not
2091 necessarily @code{eq} to each other: they are @code{eq} only if they
2092 are the same object, meaning that a change in the contents of one will
2093 be reflected by the same change in the contents of the other.
2114 ;; @r{This exception occurs because Emacs Lisp}
2115 ;; @r{makes just one multibyte empty string, to save space.}
2119 (eq '(1 (2 (3))) '(1 (2 (3))))
2124 (setq foo '(1 (2 (3))))
2125 @result{} (1 (2 (3)))
2128 (eq foo '(1 (2 (3))))
2133 (eq [(1 2) 3] [(1 2) 3])
2138 (eq (point-marker) (point-marker))
2144 The @code{make-symbol} function returns an uninterned symbol, distinct
2145 from the symbol that is used if you write the name in a Lisp expression.
2146 Distinct symbols with the same name are not @code{eq}. @xref{Creating
2151 (eq (make-symbol "foo") 'foo)
2157 @defun equal object1 object2
2158 This function returns @code{t} if @var{object1} and @var{object2} have
2159 equal components, and @code{nil} otherwise. Whereas @code{eq} tests
2160 if its arguments are the same object, @code{equal} looks inside
2161 nonidentical arguments to see if their elements or contents are the
2162 same. So, if two objects are @code{eq}, they are @code{equal}, but
2163 the converse is not always true.
2177 (equal "asdf" "asdf")
2186 (equal '(1 (2 (3))) '(1 (2 (3))))
2190 (eq '(1 (2 (3))) '(1 (2 (3))))
2195 (equal [(1 2) 3] [(1 2) 3])
2199 (eq [(1 2) 3] [(1 2) 3])
2204 (equal (point-marker) (point-marker))
2209 (eq (point-marker) (point-marker))
2214 Comparison of strings is case-sensitive, but does not take account of
2215 text properties---it compares only the characters in the strings.
2216 @xref{Text Properties}. Use @code{equal-including-properties} to also
2217 compare text properties. For technical reasons, a unibyte string and
2218 a multibyte string are @code{equal} if and only if they contain the
2219 same sequence of character codes and all these codes are either in the
2220 range 0 through 127 (@acronym{ASCII}) or 160 through 255
2221 (@code{eight-bit-graphic}). (@pxref{Text Representations}).
2225 (equal "asdf" "ASDF")
2230 However, two distinct buffers are never considered @code{equal}, even if
2231 their textual contents are the same.
2234 The test for equality is implemented recursively; for example, given
2235 two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})}
2236 returns @code{t} if and only if both the expressions below return
2240 (equal (car @var{x}) (car @var{y}))
2241 (equal (cdr @var{x}) (cdr @var{y}))
2244 Because of this recursive method, circular lists may therefore cause
2245 infinite recursion (leading to an error).
2247 @defun equal-including-properties object1 object2
2248 This function behaves like @code{equal} in all cases but also requires
2249 that for two strings to be equal, they have the same text properties.
2253 (equal "asdf" (propertize "asdf" 'asdf t))
2257 (equal-including-properties "asdf"
2258 (propertize "asdf" 'asdf t))