2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/objects
7 @node Lisp Data Types, Numbers, Introduction, Top
8 @chapter Lisp Data Types
14 A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
15 programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of
18 Every object belongs to at least one type. Objects of the same type
19 have similar structures and may usually be used in the same contexts.
20 Types can overlap, and objects can belong to two or more types.
21 Consequently, we can ask whether an object belongs to a particular type,
22 but not for ``the'' type of an object.
24 @cindex primitive type
25 A few fundamental object types are built into Emacs. These, from
26 which all other types are constructed, are called @dfn{primitive types}.
27 Each object belongs to one and only one primitive type. These types
28 include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
29 @dfn{string}, @dfn{vector}, @dfn{hash-table}, @dfn{subr}, and
30 @dfn{byte-code function}, plus several special types, such as
31 @dfn{buffer}, that are related to editing. (@xref{Editing Types}.)
33 Each primitive type has a corresponding Lisp function that checks
34 whether an object is a member of that type.
36 Note that Lisp is unlike many other languages in that Lisp objects are
37 @dfn{self-typing}: the primitive type of the object is implicit in the
38 object itself. For example, if an object is a vector, nothing can treat
39 it as a number; Lisp knows it is a vector, not a number.
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 @comment node-name, next, previous, up
65 @section Printed Representation and Read Syntax
66 @cindex printed representation
69 The @dfn{printed representation} of an object is the format of the
70 output generated by the Lisp printer (the function @code{prin1}) for
71 that object. Every data type has a unique printed representation.
72 The @dfn{read syntax} of an object is the format of the input accepted
73 by the Lisp reader (the function @code{read}) for that object. This
74 is not necessarily unique; many kinds of object have more than one
75 syntax. @xref{Read and Print}.
78 In most cases, an object's printed representation is also a read
79 syntax for the object. However, some types have no read syntax, since
80 it does not make sense to enter objects of these types as constants in
81 a Lisp program. These objects are printed in @dfn{hash notation},
82 which consists of the characters @samp{#<}, a descriptive string
83 (typically the type name followed by the name of the object), and a
84 closing @samp{>}. For example:
88 @result{} #<buffer objects.texi>
92 Hash notation cannot be read at all, so the Lisp reader signals the
93 error @code{invalid-read-syntax} whenever it encounters @samp{#<}.
94 @kindex invalid-read-syntax
96 In other languages, an expression is text; it has no other form. In
97 Lisp, an expression is primarily a Lisp object and only secondarily the
98 text that is the object's read syntax. Often there is no need to
99 emphasize this distinction, but you must keep it in the back of your
100 mind, or you will occasionally be very confused.
102 When you evaluate an expression interactively, the Lisp interpreter
103 first reads the textual representation of it, producing a Lisp object,
104 and then evaluates that object (@pxref{Evaluation}). However,
105 evaluation and reading are separate activities. Reading returns the
106 Lisp object represented by the text that is read; the object may or may
107 not be evaluated later. @xref{Input Functions}, for a description of
108 @code{read}, the basic function for reading objects.
111 @comment node-name, next, previous, up
114 @cindex @samp{;} in comment
116 A @dfn{comment} is text that is written in a program only for the sake
117 of humans that read the program, and that has no effect on the meaning
118 of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
119 is not within a string or character constant. The comment continues to
120 the end of line. The Lisp reader discards comments; they do not become
121 part of the Lisp objects which represent the program within the Lisp
124 The @samp{#@@@var{count}} construct, which skips the next @var{count}
125 characters, is useful for program-generated comments containing binary
126 data. The Emacs Lisp byte compiler uses this in its output files
127 (@pxref{Byte Compilation}). It isn't meant for source files, however.
129 @xref{Comment Tips}, for conventions for formatting comments.
131 @node Programming Types
132 @section Programming Types
133 @cindex programming types
135 There are two general categories of types in Emacs Lisp: those having
136 to do with Lisp programming, and those having to do with editing. The
137 former exist in many Lisp implementations, in one form or another. The
138 latter are unique to Emacs Lisp.
141 * Integer Type:: Numbers without fractional parts.
142 * Floating Point Type:: Numbers with fractional parts and with a large range.
143 * Character Type:: The representation of letters, numbers and
145 * Symbol Type:: A multi-use object that refers to a function,
146 variable, or property list, and has a unique identity.
147 * Sequence Type:: Both lists and arrays are classified as sequences.
148 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
149 * Array Type:: Arrays include strings and vectors.
150 * String Type:: An (efficient) array of characters.
151 * Vector Type:: One-dimensional arrays.
152 * Char-Table Type:: One-dimensional sparse arrays indexed by characters.
153 * Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}.
154 * Hash Table Type:: Super-fast lookup tables.
155 * Function Type:: A piece of executable code you can call from elsewhere.
156 * Macro Type:: A method of expanding an expression into another
157 expression, more fundamental but less pretty.
158 * Primitive Function Type:: A function written in C, callable from Lisp.
159 * Byte-Code Type:: A function written in Lisp, then compiled.
160 * Autoload Type:: A type used for automatically loading seldom-used
165 @subsection Integer Type
167 The range of values for integers in Emacs Lisp is @minus{}268435456 to
168 268435455 (29 bits; i.e.,
182 on most machines. (Some machines may provide a wider range.) It is
183 important to note that the Emacs Lisp arithmetic functions do not check
184 for overflow. Thus @code{(1+ 268435455)} is @minus{}268435456 on most
187 The read syntax for integers is a sequence of (base ten) digits with an
188 optional sign at the beginning and an optional period at the end. The
189 printed representation produced by the Lisp interpreter never has a
190 leading @samp{+} or a final @samp{.}.
194 -1 ; @r{The integer -1.}
195 1 ; @r{The integer 1.}
196 1. ; @r{Also the integer 1.}
197 +1 ; @r{Also the integer 1.}
198 536870913 ; @r{Also the integer 1 on a 29-bit implementation.}
202 @xref{Numbers}, for more information.
204 @node Floating Point Type
205 @subsection Floating Point Type
207 Floating point numbers are the computer equivalent of scientific
208 notation; you can think of a floating point number as a fraction
209 together with a power of ten. The precise number of significant
210 figures and the range of possible exponents is machine-specific; Emacs
211 uses the C data type @code{double} to store the value, and internally
212 this records a power of 2 rather than a power of 10.
214 The printed representation for floating point numbers requires either
215 a decimal point (with at least one digit following), an exponent, or
216 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
217 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
218 number whose value is 1500. They are all equivalent.
220 @xref{Numbers}, for more information.
223 @subsection Character Type
224 @cindex @acronym{ASCII} character codes
226 A @dfn{character} in Emacs Lisp is nothing more than an integer. In
227 other words, characters are represented by their character codes. For
228 example, the character @kbd{A} is represented as the @w{integer 65}.
230 Individual characters are used occasionally in programs, but it is
231 more common to work with @emph{strings}, which are sequences composed
232 of characters. @xref{String Type}.
234 Characters in strings and buffers are currently limited to the range
235 of 0 to 4194303---twenty two bits (@pxref{Character Codes}). Codes 0
236 through 127 are @acronym{ASCII} codes; the rest are
237 non-@acronym{ASCII} (@pxref{Non-ASCII Characters}). Characters that
238 represent keyboard input have a much wider range, to encode modifier
239 keys such as Control, Meta and Shift.
241 There are special functions for producing a human-readable textual
242 description of a character for the sake of messages. @xref{Describing
246 * Basic Char Syntax::
247 * General Escape Syntax::
253 @node Basic Char Syntax
254 @subsubsection Basic Char Syntax
255 @cindex read syntax for characters
256 @cindex printed representation for characters
257 @cindex syntax for characters
258 @cindex @samp{?} in character constant
259 @cindex question mark in character constant
261 Since characters are really integers, the printed representation of
262 a character is a decimal number. This is also a possible read syntax
263 for a character, but writing characters that way in Lisp programs is
264 not clear programming. You should @emph{always} use the special read
265 syntax formats that Emacs Lisp provides for characters. These syntax
266 formats start with a question mark.
268 The usual read syntax for alphanumeric characters is a question mark
269 followed by the character; thus, @samp{?A} for the character
270 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
276 ?Q @result{} 81 ?q @result{} 113
279 You can use the same syntax for punctuation characters, but it is
280 often a good idea to add a @samp{\} so that the Emacs commands for
281 editing Lisp code don't get confused. For example, @samp{?\(} is the
282 way to write the open-paren character. If the character is @samp{\},
283 you @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
286 @cindex bell character
290 @cindex tab (ASCII character)
298 @cindex return (ASCII character)
300 @cindex escape (ASCII character)
302 @cindex space (ASCII character)
304 You can express the characters control-g, backspace, tab, newline,
305 vertical tab, formfeed, space, return, del, and escape as @samp{?\a},
306 @samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f},
307 @samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively.
308 (@samp{?\s} followed by a dash has a different meaning---it applies
309 the ``super'' modifier to the following character.) Thus,
312 ?\a @result{} 7 ; @r{control-g, @kbd{C-g}}
313 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
314 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
315 ?\n @result{} 10 ; @r{newline, @kbd{C-j}}
316 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
317 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
318 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
319 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
320 ?\s @result{} 32 ; @r{space character, @key{SPC}}
321 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
322 ?\d @result{} 127 ; @r{delete character, @key{DEL}}
325 @cindex escape sequence
326 These sequences which start with backslash are also known as
327 @dfn{escape sequences}, because backslash plays the role of an
328 ``escape character''; this terminology has nothing to do with the
329 character @key{ESC}. @samp{\s} is meant for use in character
330 constants; in string constants, just write the space.
332 A backslash is allowed, and harmless, preceding any character without
333 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
334 There is no reason to add a backslash before most characters. However,
335 you should add a backslash before any of the characters
336 @samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
337 Lisp code. You can also add a backslash before whitespace characters such as
338 space, tab, newline and formfeed. However, it is cleaner to use one of
339 the easily readable escape sequences, such as @samp{\t} or @samp{\s},
340 instead of an actual whitespace character such as a tab or a space.
341 (If you do write backslash followed by a space, you should write
342 an extra space after the character constant to separate it from the
345 @node General Escape Syntax
346 @subsubsection General Escape Syntax
348 In addition to the specific escape sequences for special important
349 control characters, Emacs provides general categories of escape syntax
350 that you can use to specify non-ASCII text characters.
352 @cindex unicode character escape
353 For instance, you can specify characters by their Unicode values.
354 @code{?\u@var{nnnn}} represents a character that maps to the Unicode
355 code point @samp{U+@var{nnnn}}. There is a slightly different syntax
356 for specifying characters with code points above @code{#xFFFF};
357 @code{\U00@var{nnnnnn}} represents the character whose Unicode code
358 point is @samp{U+@var{nnnnnn}}, if such a character is supported by
359 Emacs. If the corresponding character is not supported, Emacs signals
362 This peculiar and inconvenient syntax was adopted for compatibility
363 with other programming languages. Unlike some other languages, Emacs
364 Lisp supports this syntax only in character literals and strings.
366 @cindex @samp{\} in character constant
367 @cindex backslash in character constant
368 @cindex octal character code
369 The most general read syntax for a character represents the
370 character code in either octal or hex. To use octal, write a question
371 mark followed by a backslash and the octal character code (up to three
372 octal digits); thus, @samp{?\101} for the character @kbd{A},
373 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
374 character @kbd{C-b}. Although this syntax can represent any
375 @acronym{ASCII} character, it is preferred only when the precise octal
376 value is more important than the @acronym{ASCII} representation.
380 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
381 ?\101 @result{} 65 ?A @result{} 65
385 To use hex, write a question mark followed by a backslash, @samp{x},
386 and the hexadecimal character code. You can use any number of hex
387 digits, so you can represent any character code in this way.
388 Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
389 character @kbd{C-a}, and @code{?\x8e0} for the Latin-1 character
394 @samp{a} with grave accent.
397 @node Ctl-Char Syntax
398 @subsubsection Control-Character Syntax
400 @cindex control characters
401 Control characters can be represented using yet another read syntax.
402 This consists of a question mark followed by a backslash, caret, and the
403 corresponding non-control character, in either upper or lower case. For
404 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
405 character @kbd{C-i}, the character whose value is 9.
407 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
408 equivalent to @samp{?\^I} and to @samp{?\^i}:
411 ?\^I @result{} 9 ?\C-I @result{} 9
414 In strings and buffers, the only control characters allowed are those
415 that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn
416 any character into a control character with @samp{C-}. The character
417 codes for these non-@acronym{ASCII} control characters include the
424 bit as well as the code for the corresponding non-control
425 character. Ordinary terminals have no way of generating non-@acronym{ASCII}
426 control characters, but you can generate them straightforwardly using X
427 and other window systems.
429 For historical reasons, Emacs treats the @key{DEL} character as
430 the control equivalent of @kbd{?}:
433 ?\^? @result{} 127 ?\C-? @result{} 127
437 As a result, it is currently not possible to represent the character
438 @kbd{Control-?}, which is a meaningful input character under X, using
439 @samp{\C-}. It is not easy to change this, as various Lisp files refer
440 to @key{DEL} in this way.
442 For representing control characters to be found in files or strings,
443 we recommend the @samp{^} syntax; for control characters in keyboard
444 input, we prefer the @samp{C-} syntax. Which one you use does not
445 affect the meaning of the program, but may guide the understanding of
448 @node Meta-Char Syntax
449 @subsubsection Meta-Character Syntax
451 @cindex meta characters
452 A @dfn{meta character} is a character typed with the @key{META}
453 modifier key. The integer that represents such a character has the
460 bit set. We use high bits for this and other modifiers to make
461 possible a wide range of basic character codes.
470 bit attached to an @acronym{ASCII} character indicates a meta
471 character; thus, the meta characters that can fit in a string have
472 codes in the range from 128 to 255, and are the meta versions of the
473 ordinary @acronym{ASCII} characters. (In Emacs versions 18 and older,
474 this convention was used for characters outside of strings as well.)
476 The read syntax for meta characters uses @samp{\M-}. For example,
477 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
478 octal character codes (see below), with @samp{\C-}, or with any other
479 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
480 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
481 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
483 @node Other Char Bits
484 @subsubsection Other Character Modifier Bits
486 The case of a graphic character is indicated by its character code;
487 for example, @acronym{ASCII} distinguishes between the characters @samp{a}
488 and @samp{A}. But @acronym{ASCII} has no way to represent whether a control
489 character is upper case or lower case. Emacs uses the
496 bit to indicate that the shift key was used in typing a control
497 character. This distinction is possible only when you use X terminals
498 or other special terminals; ordinary terminals do not report the
499 distinction to the computer in any way. The Lisp syntax for
500 the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O}
501 represents the shifted-control-o character.
503 @cindex hyper characters
504 @cindex super characters
505 @cindex alt characters
506 The X Window System defines three other
507 @anchor{modifier bits}modifier bits that can be set
508 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
509 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is
510 significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents
511 @kbd{Alt-Hyper-Meta-x}. (Note that @samp{\s} with no following @samp{-}
512 represents the space character.)
514 Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}}
515 for super and @math{2^{24}} for hyper.
519 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
523 @subsection Symbol Type
525 A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The
526 symbol name serves as the printed representation of the symbol. In
527 ordinary Lisp use, with one single obarray (@pxref{Creating Symbols}),
528 a symbol's name is unique---no two symbols have the same name.
530 A symbol can serve as a variable, as a function name, or to hold a
531 property list. Or it may serve only to be distinct from all other Lisp
532 objects, so that its presence in a data structure may be recognized
533 reliably. In a given context, usually only one of these uses is
534 intended. But you can use one symbol in all of these ways,
537 A symbol whose name starts with a colon (@samp{:}) is called a
538 @dfn{keyword symbol}. These symbols automatically act as constants, and
539 are normally used only by comparing an unknown symbol with a few
540 specific alternatives.
542 @cindex @samp{\} in symbols
543 @cindex backslash in symbols
544 A symbol name can contain any characters whatever. Most symbol names
545 are written with letters, digits, and the punctuation characters
546 @samp{-+=*/}. Such names require no special punctuation; the characters
547 of the name suffice as long as the name does not look like a number.
548 (If it does, write a @samp{\} at the beginning of the name to force
549 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}?} are
550 less often used but also require no special punctuation. Any other
551 characters may be included in a symbol's name by escaping them with a
552 backslash. In contrast to its use in strings, however, a backslash in
553 the name of a symbol simply quotes the single character that follows the
554 backslash. For example, in a string, @samp{\t} represents a tab
555 character; in the name of a symbol, however, @samp{\t} merely quotes the
556 letter @samp{t}. To have a symbol with a tab character in its name, you
557 must actually use a tab (preceded with a backslash). But it's rare to
560 @cindex CL note---case of letters
562 @b{Common Lisp note:} In Common Lisp, lower case letters are always
563 ``folded'' to upper case, unless they are explicitly escaped. In Emacs
564 Lisp, upper case and lower case letters are distinct.
567 Here are several examples of symbol names. Note that the @samp{+} in
568 the fifth example is escaped to prevent it from being read as a number.
569 This is not necessary in the fourth example because the rest of the name
570 makes it invalid as a number.
574 foo ; @r{A symbol named @samp{foo}.}
575 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
576 char-to-string ; @r{A symbol named @samp{char-to-string}.}
579 1+ ; @r{A symbol named @samp{1+}}
580 ; @r{(not @samp{+1}, which is an integer).}
583 \+1 ; @r{A symbol named @samp{+1}}
584 ; @r{(not a very readable name).}
587 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
588 @c the @'s in this next line use up three characters, hence the
589 @c apparent misalignment of the comment.
590 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
591 ; @r{These characters need not be escaped.}
596 @c This uses ``colon'' instead of a literal `:' because Info cannot
597 @c cope with a `:' in a menu
598 @cindex @samp{#@var{colon}} read syntax
601 @cindex @samp{#:} read syntax
603 Normally the Lisp reader interns all symbols (@pxref{Creating
604 Symbols}). To prevent interning, you can write @samp{#:} before the
608 @subsection Sequence Types
610 A @dfn{sequence} is a Lisp object that represents an ordered set of
611 elements. There are two kinds of sequence in Emacs Lisp, lists and
612 arrays. Thus, an object of type list or of type array is also
613 considered a sequence.
615 Arrays are further subdivided into strings, vectors, char-tables and
616 bool-vectors. Vectors can hold elements of any type, but string
617 elements must be characters, and bool-vector elements must be @code{t}
618 or @code{nil}. Char-tables are like vectors except that they are
619 indexed by any valid character code. The characters in a string can
620 have text properties like characters in a buffer (@pxref{Text
621 Properties}), but vectors do not support text properties, even when
622 their elements happen to be characters.
624 Lists, strings and the other array types are different, but they have
625 important similarities. For example, all have a length @var{l}, and all
626 have elements which can be indexed from zero to @var{l} minus one.
627 Several functions, called sequence functions, accept any kind of
628 sequence. For example, the function @code{elt} can be used to extract
629 an element of a sequence, given its index. @xref{Sequences Arrays
632 It is generally impossible to read the same sequence twice, since
633 sequences are always created anew upon reading. If you read the read
634 syntax for a sequence twice, you get two sequences with equal contents.
635 There is one exception: the empty list @code{()} always stands for the
636 same object, @code{nil}.
639 @subsection Cons Cell and List Types
640 @cindex address field of register
641 @cindex decrement field of register
644 A @dfn{cons cell} is an object that consists of two slots, called the
645 @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or
646 @dfn{refer to} any Lisp object. We also say that ``the @sc{car} of
647 this cons cell is'' whatever object its @sc{car} slot currently holds,
648 and likewise for the @sc{cdr}.
651 A note to C programmers: in Lisp, we do not distinguish between
652 ``holding'' a value and ``pointing to'' the value, because pointers in
656 A @dfn{list} is a series of cons cells, linked together so that the
657 @sc{cdr} slot of each cons cell holds either the next cons cell or the
658 empty list. The empty list is actually the symbol @code{nil}.
659 @xref{Lists}, for functions that work on lists. Because most cons
660 cells are used as part of lists, the phrase @dfn{list structure} has
661 come to refer to any structure made out of cons cells.
664 Because cons cells are so central to Lisp, we also have a word for
665 ``an object which is not a cons cell.'' These objects are called
669 @cindex @samp{(@dots{})} in lists
670 The read syntax and printed representation for lists are identical, and
671 consist of a left parenthesis, an arbitrary number of elements, and a
672 right parenthesis. Here are examples of lists:
675 (A 2 "A") ; @r{A list of three elements.}
676 () ; @r{A list of no elements (the empty list).}
677 nil ; @r{A list of no elements (the empty list).}
678 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
679 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
680 (A nil) ; @r{Equivalent to the previous.}
681 ((A B C)) ; @r{A list of one element}
682 ; @r{(which is a list of three elements).}
685 Upon reading, each object inside the parentheses becomes an element
686 of the list. That is, a cons cell is made for each element. The
687 @sc{car} slot of the cons cell holds the element, and its @sc{cdr}
688 slot refers to the next cons cell of the list, which holds the next
689 element in the list. The @sc{cdr} slot of the last cons cell is set to
692 The names @sc{car} and @sc{cdr} derive from the history of Lisp. The
693 original Lisp implementation ran on an @w{IBM 704} computer which
694 divided words into two parts, called the ``address'' part and the
695 ``decrement''; @sc{car} was an instruction to extract the contents of
696 the address part of a register, and @sc{cdr} an instruction to extract
697 the contents of the decrement. By contrast, ``cons cells'' are named
698 for the function @code{cons} that creates them, which in turn was named
699 for its purpose, the construction of cells.
702 * Box Diagrams:: Drawing pictures of lists.
703 * Dotted Pair Notation:: A general syntax for cons cells.
704 * Association List Type:: A specially constructed list.
708 @subsubsection Drawing Lists as Box Diagrams
709 @cindex box diagrams, for lists
710 @cindex diagrams, boxed, for lists
712 A list can be illustrated by a diagram in which the cons cells are
713 shown as pairs of boxes, like dominoes. (The Lisp reader cannot read
714 such an illustration; unlike the textual notation, which can be
715 understood by both humans and computers, the box illustrations can be
716 understood only by humans.) This picture represents the three-element
717 list @code{(rose violet buttercup)}:
721 --- --- --- --- --- ---
722 | | |--> | | |--> | | |--> nil
723 --- --- --- --- --- ---
726 --> rose --> violet --> buttercup
730 In this diagram, each box represents a slot that can hold or refer to
731 any Lisp object. Each pair of boxes represents a cons cell. Each arrow
732 represents a reference to a Lisp object, either an atom or another cons
735 In this example, the first box, which holds the @sc{car} of the first
736 cons cell, refers to or ``holds'' @code{rose} (a symbol). The second
737 box, holding the @sc{cdr} of the first cons cell, refers to the next
738 pair of boxes, the second cons cell. The @sc{car} of the second cons
739 cell is @code{violet}, and its @sc{cdr} is the third cons cell. The
740 @sc{cdr} of the third (and last) cons cell is @code{nil}.
742 Here is another diagram of the same list, @code{(rose violet
743 buttercup)}, sketched in a different manner:
747 --------------- ---------------- -------------------
748 | car | cdr | | car | cdr | | car | cdr |
749 | rose | o-------->| violet | o-------->| buttercup | nil |
751 --------------- ---------------- -------------------
755 @cindex @code{nil} as a list
757 A list with no elements in it is the @dfn{empty list}; it is identical
758 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
761 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
762 depicted with boxes and arrows:
767 | | |--> | | |--> nil
775 Here is a more complex illustration, showing the three-element list,
776 @code{((pine needles) oak maple)}, the first element of which is a
781 --- --- --- --- --- ---
782 | | |--> | | |--> | | |--> nil
783 --- --- --- --- --- ---
789 --> | | |--> | | |--> nil
797 The same list represented in the second box notation looks like this:
801 -------------- -------------- --------------
802 | car | cdr | | car | cdr | | car | cdr |
803 | o | o------->| oak | o------->| maple | nil |
805 -- | --------- -------------- --------------
808 | -------------- ----------------
809 | | car | cdr | | car | cdr |
810 ------>| pine | o------->| needles | nil |
812 -------------- ----------------
816 @node Dotted Pair Notation
817 @subsubsection Dotted Pair Notation
818 @cindex dotted pair notation
819 @cindex @samp{.} in lists
821 @dfn{Dotted pair notation} is a general syntax for cons cells that
822 represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
823 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
824 the object @var{a} and whose @sc{cdr} is the object @var{b}. Dotted
825 pair notation is more general than list syntax because the @sc{cdr}
826 does not have to be a list. However, it is more cumbersome in cases
827 where list syntax would work. In dotted pair notation, the list
828 @samp{(1 2 3)} is written as @samp{(1 . (2 . (3 . nil)))}. For
829 @code{nil}-terminated lists, you can use either notation, but list
830 notation is usually clearer and more convenient. When printing a
831 list, the dotted pair notation is only used if the @sc{cdr} of a cons
834 Here's an example using boxes to illustrate dotted pair notation.
835 This example shows the pair @code{(rose . violet)}:
848 You can combine dotted pair notation with list notation to represent
849 conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}.
850 You write a dot after the last element of the list, followed by the
851 @sc{cdr} of the final cons cell. For example, @code{(rose violet
852 . buttercup)} is equivalent to @code{(rose . (violet . buttercup))}.
853 The object looks like this:
858 | | |--> | | |--> buttercup
866 The syntax @code{(rose .@: violet .@: buttercup)} is invalid because
867 there is nothing that it could mean. If anything, it would say to put
868 @code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already
869 used for @code{violet}.
871 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))},
877 | | |--> | | |--> nil
885 Similarly, the three-element list @code{(rose violet buttercup)}
886 is equivalent to @code{(rose . (violet . (buttercup)))}.
892 --- --- --- --- --- ---
893 | | |--> | | |--> | | |--> nil
894 --- --- --- --- --- ---
897 --> rose --> violet --> buttercup
902 @node Association List Type
903 @comment node-name, next, previous, up
904 @subsubsection Association List Type
906 An @dfn{association list} or @dfn{alist} is a specially-constructed
907 list whose elements are cons cells. In each element, the @sc{car} is
908 considered a @dfn{key}, and the @sc{cdr} is considered an
909 @dfn{associated value}. (In some cases, the associated value is stored
910 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
911 stacks, since it is easy to add or remove associations at the front of
917 (setq alist-of-colors
918 '((rose . red) (lily . white) (buttercup . yellow)))
922 sets the variable @code{alist-of-colors} to an alist of three elements. In the
923 first element, @code{rose} is the key and @code{red} is the value.
925 @xref{Association Lists}, for a further explanation of alists and for
926 functions that work on alists. @xref{Hash Tables}, for another kind of
927 lookup table, which is much faster for handling a large number of keys.
930 @subsection Array Type
932 An @dfn{array} is composed of an arbitrary number of slots for
933 holding or referring to other Lisp objects, arranged in a contiguous block of
934 memory. Accessing any element of an array takes approximately the same
935 amount of time. In contrast, accessing an element of a list requires
936 time proportional to the position of the element in the list. (Elements
937 at the end of a list take longer to access than elements at the
938 beginning of a list.)
940 Emacs defines four types of array: strings, vectors, bool-vectors, and
943 A string is an array of characters and a vector is an array of
944 arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}.
945 These kinds of array may have any length up to the largest integer.
946 Char-tables are sparse arrays indexed by any valid character code; they
947 can hold arbitrary objects.
949 The first element of an array has index zero, the second element has
950 index 1, and so on. This is called @dfn{zero-origin} indexing. For
951 example, an array of four elements has indices 0, 1, 2, @w{and 3}. The
952 largest possible index value is one less than the length of the array.
953 Once an array is created, its length is fixed.
955 All Emacs Lisp arrays are one-dimensional. (Most other programming
956 languages support multidimensional arrays, but they are not essential;
957 you can get the same effect with nested one-dimensional arrays.) Each
958 type of array has its own read syntax; see the following sections for
961 The array type is a subset of the sequence type, and contains the
962 string type, the vector type, the bool-vector type, and the char-table
966 @subsection String Type
968 A @dfn{string} is an array of characters. Strings are used for many
969 purposes in Emacs, as can be expected in a text editor; for example, as
970 the names of Lisp symbols, as messages for the user, and to represent
971 text extracted from buffers. Strings in Lisp are constants: evaluation
972 of a string returns the same string.
974 @xref{Strings and Characters}, for functions that operate on strings.
977 * Syntax for Strings::
978 * Non-ASCII in Strings::
979 * Nonprinting Characters::
980 * Text Props and Strings::
983 @node Syntax for Strings
984 @subsubsection Syntax for Strings
986 @cindex @samp{"} in strings
987 @cindex double-quote in strings
988 @cindex @samp{\} in strings
989 @cindex backslash in strings
990 The read syntax for strings is a double-quote, an arbitrary number of
991 characters, and another double-quote, @code{"like this"}. To include a
992 double-quote in a string, precede it with a backslash; thus, @code{"\""}
993 is a string containing just a single double-quote character. Likewise,
994 you can include a backslash by preceding it with another backslash, like
995 this: @code{"this \\ is a single embedded backslash"}.
997 @cindex newline in strings
998 The newline character is not special in the read syntax for strings;
999 if you write a new line between the double-quotes, it becomes a
1000 character in the string. But an escaped newline---one that is preceded
1001 by @samp{\}---does not become part of the string; i.e., the Lisp reader
1002 ignores an escaped newline while reading a string. An escaped space
1003 @w{@samp{\ }} is likewise ignored.
1006 "It is useful to include newlines
1007 in documentation strings,
1008 but the newline is \
1009 ignored if escaped."
1010 @result{} "It is useful to include newlines
1011 in documentation strings,
1012 but the newline is ignored if escaped."
1015 @node Non-ASCII in Strings
1016 @subsubsection Non-@acronym{ASCII} Characters in Strings
1018 You can include a non-@acronym{ASCII} international character in a string
1019 constant by writing it literally. There are two text representations
1020 for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte
1021 and multibyte. If the string constant is read from a multibyte source,
1022 such as a multibyte buffer or string, or a file that would be visited as
1023 multibyte, then the character is read as a multibyte character, and that
1024 makes the string multibyte. If the string constant is read from a
1025 unibyte source, then the character is read as unibyte and that makes the
1028 You can also represent a multibyte non-@acronym{ASCII} character with its
1029 character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
1030 digits as necessary. (Multibyte non-@acronym{ASCII} character codes are all
1031 greater than 256.) Any character which is not a valid hex digit
1032 terminates this construct. If the next character in the string could be
1033 interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
1034 terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents
1035 one character, @samp{a} with grave accent. @w{@samp{\ }} in a string
1036 constant is just like backslash-newline; it does not contribute any
1037 character to the string, but it does terminate the preceding hex escape.
1039 You can represent a unibyte non-@acronym{ASCII} character with its
1040 character code, which must be in the range from 128 (0200 octal) to
1041 255 (0377 octal). If you write all such character codes in octal and
1042 the string contains no other characters forcing it to be multibyte,
1043 this produces a unibyte string. However, using any hex escape in a
1044 string (even for an @acronym{ASCII} character) forces the string to be
1047 You can also specify characters in a string by their numeric values
1048 in Unicode, using @samp{\u} and @samp{\U} (@pxref{Character Type}).
1050 @xref{Text Representations}, for more information about the two
1051 text representations.
1053 @node Nonprinting Characters
1054 @subsubsection Nonprinting Characters in Strings
1056 You can use the same backslash escape-sequences in a string constant
1057 as in character literals (but do not use the question mark that begins a
1058 character constant). For example, you can write a string containing the
1059 nonprinting characters tab and @kbd{C-a}, with commas and spaces between
1060 them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a
1061 description of the read syntax for characters.
1063 However, not all of the characters you can write with backslash
1064 escape-sequences are valid in strings. The only control characters that
1065 a string can hold are the @acronym{ASCII} control characters. Strings do not
1066 distinguish case in @acronym{ASCII} control characters.
1068 Properly speaking, strings cannot hold meta characters; but when a
1069 string is to be used as a key sequence, there is a special convention
1070 that provides a way to represent meta versions of @acronym{ASCII}
1071 characters in a string. If you use the @samp{\M-} syntax to indicate
1072 a meta character in a string constant, this sets the
1079 bit of the character in the string. If the string is used in
1080 @code{define-key} or @code{lookup-key}, this numeric code is translated
1081 into the equivalent meta character. @xref{Character Type}.
1083 Strings cannot hold characters that have the hyper, super, or alt
1086 @node Text Props and Strings
1087 @subsubsection Text Properties in Strings
1089 @cindex @samp{#(} read syntax
1090 @cindex text properties, read syntax
1091 A string can hold properties for the characters it contains, in
1092 addition to the characters themselves. This enables programs that copy
1093 text between strings and buffers to copy the text's properties with no
1094 special effort. @xref{Text Properties}, for an explanation of what text
1095 properties mean. Strings with text properties use a special read and
1099 #("@var{characters}" @var{property-data}...)
1103 where @var{property-data} consists of zero or more elements, in groups
1104 of three as follows:
1107 @var{beg} @var{end} @var{plist}
1111 The elements @var{beg} and @var{end} are integers, and together specify
1112 a range of indices in the string; @var{plist} is the property list for
1113 that range. For example,
1116 #("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
1120 represents a string whose textual contents are @samp{foo bar}, in which
1121 the first three characters have a @code{face} property with value
1122 @code{bold}, and the last three have a @code{face} property with value
1123 @code{italic}. (The fourth character has no text properties, so its
1124 property list is @code{nil}. It is not actually necessary to mention
1125 ranges with @code{nil} as the property list, since any characters not
1126 mentioned in any range will default to having no properties.)
1129 @subsection Vector Type
1131 A @dfn{vector} is a one-dimensional array of elements of any type. It
1132 takes a constant amount of time to access any element of a vector. (In
1133 a list, the access time of an element is proportional to the distance of
1134 the element from the beginning of the list.)
1136 The printed representation of a vector consists of a left square
1137 bracket, the elements, and a right square bracket. This is also the
1138 read syntax. Like numbers and strings, vectors are considered constants
1142 [1 "two" (three)] ; @r{A vector of three elements.}
1143 @result{} [1 "two" (three)]
1146 @xref{Vectors}, for functions that work with vectors.
1148 @node Char-Table Type
1149 @subsection Char-Table Type
1151 A @dfn{char-table} is a one-dimensional array of elements of any type,
1152 indexed by character codes. Char-tables have certain extra features to
1153 make them more useful for many jobs that involve assigning information
1154 to character codes---for example, a char-table can have a parent to
1155 inherit from, a default value, and a small number of extra slots to use for
1156 special purposes. A char-table can also specify a single value for
1157 a whole character set.
1159 The printed representation of a char-table is like a vector
1160 except that there is an extra @samp{#^} at the beginning.
1162 @xref{Char-Tables}, for special functions to operate on char-tables.
1163 Uses of char-tables include:
1167 Case tables (@pxref{Case Tables}).
1170 Character category tables (@pxref{Categories}).
1173 Display tables (@pxref{Display Tables}).
1176 Syntax tables (@pxref{Syntax Tables}).
1179 @node Bool-Vector Type
1180 @subsection Bool-Vector Type
1182 A @dfn{bool-vector} is a one-dimensional array of elements that
1183 must be @code{t} or @code{nil}.
1185 The printed representation of a bool-vector is like a string, except
1186 that it begins with @samp{#&} followed by the length. The string
1187 constant that follows actually specifies the contents of the bool-vector
1188 as a bitmap---each ``character'' in the string contains 8 bits, which
1189 specify the next 8 elements of the bool-vector (1 stands for @code{t},
1190 and 0 for @code{nil}). The least significant bits of the character
1191 correspond to the lowest indices in the bool-vector.
1194 (make-bool-vector 3 t)
1196 (make-bool-vector 3 nil)
1201 These results make sense, because the binary code for @samp{C-g} is
1202 111 and @samp{C-@@} is the character with code 0.
1204 If the length is not a multiple of 8, the printed representation
1205 shows extra elements, but these extras really make no difference. For
1206 instance, in the next example, the two bool-vectors are equal, because
1207 only the first 3 bits are used:
1210 (equal #&3"\377" #&3"\007")
1214 @node Hash Table Type
1215 @subsection Hash Table Type
1217 A hash table is a very fast kind of lookup table, somewhat like an
1218 alist in that it maps keys to corresponding values, but much faster.
1219 Hash tables have no read syntax, and print using hash notation.
1220 @xref{Hash Tables}, for functions that operate on hash tables.
1224 @result{} #<hash-table 'eql nil 0/65 0x83af980>
1228 @subsection Function Type
1230 Lisp functions are executable code, just like functions in other
1231 programming languages. In Lisp, unlike most languages, functions are
1232 also Lisp objects. A non-compiled function in Lisp is a lambda
1233 expression: that is, a list whose first element is the symbol
1234 @code{lambda} (@pxref{Lambda Expressions}).
1236 In most programming languages, it is impossible to have a function
1237 without a name. In Lisp, a function has no intrinsic name. A lambda
1238 expression can be called as a function even though it has no name; to
1239 emphasize this, we also call it an @dfn{anonymous function}
1240 (@pxref{Anonymous Functions}). A named function in Lisp is just a
1241 symbol with a valid function in its function cell (@pxref{Defining
1244 Most of the time, functions are called when their names are written in
1245 Lisp expressions in Lisp programs. However, you can construct or obtain
1246 a function object at run time and then call it with the primitive
1247 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
1250 @subsection Macro Type
1252 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
1253 language. It is represented as an object much like a function, but with
1254 different argument-passing semantics. A Lisp macro has the form of a
1255 list whose first element is the symbol @code{macro} and whose @sc{cdr}
1256 is a Lisp function object, including the @code{lambda} symbol.
1258 Lisp macro objects are usually defined with the built-in
1259 @code{defmacro} function, but any list that begins with @code{macro} is
1260 a macro as far as Emacs is concerned. @xref{Macros}, for an explanation
1261 of how to write a macro.
1263 @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard
1264 Macros}) are entirely different things. When we use the word ``macro''
1265 without qualification, we mean a Lisp macro, not a keyboard macro.
1267 @node Primitive Function Type
1268 @subsection Primitive Function Type
1269 @cindex primitive function
1271 A @dfn{primitive function} is a function callable from Lisp but
1272 written in the C programming language. Primitive functions are also
1273 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
1274 derived from ``subroutine.'') Most primitive functions evaluate all
1275 their arguments when they are called. A primitive function that does
1276 not evaluate all its arguments is called a @dfn{special form}
1277 (@pxref{Special Forms}).@refill
1279 It does not matter to the caller of a function whether the function is
1280 primitive. However, this does matter if you try to redefine a primitive
1281 with a function written in Lisp. The reason is that the primitive
1282 function may be called directly from C code. Calls to the redefined
1283 function from Lisp will use the new definition, but calls from C code
1284 may still use the built-in definition. Therefore, @strong{we discourage
1285 redefinition of primitive functions}.
1287 The term @dfn{function} refers to all Emacs functions, whether written
1288 in Lisp or C. @xref{Function Type}, for information about the
1289 functions written in Lisp.
1291 Primitive functions have no read syntax and print in hash notation
1292 with the name of the subroutine.
1296 (symbol-function 'car) ; @r{Access the function cell}
1297 ; @r{of the symbol.}
1298 @result{} #<subr car>
1299 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
1300 @result{} t ; @r{Yes.}
1304 @node Byte-Code Type
1305 @subsection Byte-Code Function Type
1307 The byte compiler produces @dfn{byte-code function objects}.
1308 Internally, a byte-code function object is much like a vector; however,
1309 the evaluator handles this data type specially when it appears as a
1310 function to be called. @xref{Byte Compilation}, for information about
1313 The printed representation and read syntax for a byte-code function
1314 object is like that for a vector, with an additional @samp{#} before the
1318 @subsection Autoload Type
1320 An @dfn{autoload object} is a list whose first element is the symbol
1321 @code{autoload}. It is stored as the function definition of a symbol,
1322 where it serves as a placeholder for the real definition. The autoload
1323 object says that the real definition is found in a file of Lisp code
1324 that should be loaded when necessary. It contains the name of the file,
1325 plus some other information about the real definition.
1327 After the file has been loaded, the symbol should have a new function
1328 definition that is not an autoload object. The new definition is then
1329 called as if it had been there to begin with. From the user's point of
1330 view, the function call works as expected, using the function definition
1333 An autoload object is usually created with the function
1334 @code{autoload}, which stores the object in the function cell of a
1335 symbol. @xref{Autoload}, for more details.
1338 @section Editing Types
1339 @cindex editing types
1341 The types in the previous section are used for general programming
1342 purposes, and most of them are common to most Lisp dialects. Emacs Lisp
1343 provides several additional data types for purposes connected with
1347 * Buffer Type:: The basic object of editing.
1348 * Marker Type:: A position in a buffer.
1349 * Window Type:: Buffers are displayed in windows.
1350 * Frame Type:: Windows subdivide frames.
1351 * Terminal Type:: A terminal device displays frames.
1352 * Window Configuration Type:: Recording the way a frame is subdivided.
1353 * Frame Configuration Type:: Recording the status of all frames.
1354 * Process Type:: A subprocess of Emacs running on the underlying OS.
1355 * Stream Type:: Receive or send characters.
1356 * Keymap Type:: What function a keystroke invokes.
1357 * Overlay Type:: How an overlay is represented.
1361 @subsection Buffer Type
1363 A @dfn{buffer} is an object that holds text that can be edited
1364 (@pxref{Buffers}). Most buffers hold the contents of a disk file
1365 (@pxref{Files}) so they can be edited, but some are used for other
1366 purposes. Most buffers are also meant to be seen by the user, and
1367 therefore displayed, at some time, in a window (@pxref{Windows}). But a
1368 buffer need not be displayed in any window.
1370 The contents of a buffer are much like a string, but buffers are not
1371 used like strings in Emacs Lisp, and the available operations are
1372 different. For example, you can insert text efficiently into an
1373 existing buffer, altering the buffer's contents, whereas ``inserting''
1374 text into a string requires concatenating substrings, and the result is
1375 an entirely new string object.
1377 Each buffer has a designated position called @dfn{point}
1378 (@pxref{Positions}). At any time, one buffer is the @dfn{current
1379 buffer}. Most editing commands act on the contents of the current
1380 buffer in the neighborhood of point. Many of the standard Emacs
1381 functions manipulate or test the characters in the current buffer; a
1382 whole chapter in this manual is devoted to describing these functions
1385 Several other data structures are associated with each buffer:
1389 a local syntax table (@pxref{Syntax Tables});
1392 a local keymap (@pxref{Keymaps}); and,
1395 a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
1398 overlays (@pxref{Overlays}).
1401 text properties for the text in the buffer (@pxref{Text Properties}).
1405 The local keymap and variable list contain entries that individually
1406 override global bindings or values. These are used to customize the
1407 behavior of programs in different buffers, without actually changing the
1410 A buffer may be @dfn{indirect}, which means it shares the text
1411 of another buffer, but presents it differently. @xref{Indirect Buffers}.
1413 Buffers have no read syntax. They print in hash notation, showing the
1419 @result{} #<buffer objects.texi>
1424 @subsection Marker Type
1426 A @dfn{marker} denotes a position in a specific buffer. Markers
1427 therefore have two components: one for the buffer, and one for the
1428 position. Changes in the buffer's text automatically relocate the
1429 position value as necessary to ensure that the marker always points
1430 between the same two characters in the buffer.
1432 Markers have no read syntax. They print in hash notation, giving the
1433 current character position and the name of the buffer.
1438 @result{} #<marker at 10779 in objects.texi>
1442 @xref{Markers}, for information on how to test, create, copy, and move
1446 @subsection Window Type
1448 A @dfn{window} describes the portion of the terminal screen that Emacs
1449 uses to display a buffer. Every window has one associated buffer, whose
1450 contents appear in the window. By contrast, a given buffer may appear
1451 in one window, no window, or several windows.
1453 Though many windows may exist simultaneously, at any time one window
1454 is designated the @dfn{selected window}. This is the window where the
1455 cursor is (usually) displayed when Emacs is ready for a command. The
1456 selected window usually displays the current buffer, but this is not
1457 necessarily the case.
1459 Windows are grouped on the screen into frames; each window belongs to
1460 one and only one frame. @xref{Frame Type}.
1462 Windows have no read syntax. They print in hash notation, giving the
1463 window number and the name of the buffer being displayed. The window
1464 numbers exist to identify windows uniquely, since the buffer displayed
1465 in any given window can change frequently.
1470 @result{} #<window 1 on objects.texi>
1474 @xref{Windows}, for a description of the functions that work on windows.
1477 @subsection Frame Type
1479 A @dfn{frame} is a screen area that contains one or more Emacs
1480 windows; we also use the term ``frame'' to refer to the Lisp object
1481 that Emacs uses to refer to the screen area.
1483 Frames have no read syntax. They print in hash notation, giving the
1484 frame's title, plus its address in core (useful to identify the frame
1490 @result{} #<frame emacs@@psilocin.gnu.org 0xdac80>
1494 @xref{Frames}, for a description of the functions that work on frames.
1497 @subsection Terminal Type
1498 @cindex terminal type
1500 A @dfn{terminal} is a device capable of displaying one or more
1501 Emacs frames (@pxref{Frame Type}).
1503 Terminals have no read syntax. They print in hash notation giving
1504 the terminal's ordinal number and its TTY device file name.
1508 (get-device-terminal nil)
1509 @result{} #<terminal 1 on /dev/tty>
1513 @c FIXME: add an xref to where terminal-related primitives are described.
1515 @node Window Configuration Type
1516 @subsection Window Configuration Type
1517 @cindex window layout in a frame
1519 A @dfn{window configuration} stores information about the positions,
1520 sizes, and contents of the windows in a frame, so you can recreate the
1521 same arrangement of windows later.
1523 Window configurations do not have a read syntax; their print syntax
1524 looks like @samp{#<window-configuration>}. @xref{Window
1525 Configurations}, for a description of several functions related to
1526 window configurations.
1528 @node Frame Configuration Type
1529 @subsection Frame Configuration Type
1530 @cindex screen layout
1531 @cindex window layout, all frames
1533 A @dfn{frame configuration} stores information about the positions,
1534 sizes, and contents of the windows in all frames. It is actually
1535 a list whose @sc{car} is @code{frame-configuration} and whose
1536 @sc{cdr} is an alist. Each alist element describes one frame,
1537 which appears as the @sc{car} of that element.
1539 @xref{Frame Configurations}, for a description of several functions
1540 related to frame configurations.
1543 @subsection Process Type
1545 The word @dfn{process} usually means a running program. Emacs itself
1546 runs in a process of this sort. However, in Emacs Lisp, a process is a
1547 Lisp object that designates a subprocess created by the Emacs process.
1548 Programs such as shells, GDB, ftp, and compilers, running in
1549 subprocesses of Emacs, extend the capabilities of Emacs.
1551 An Emacs subprocess takes textual input from Emacs and returns textual
1552 output to Emacs for further manipulation. Emacs can also send signals
1555 Process objects have no read syntax. They print in hash notation,
1556 giving the name of the process:
1561 @result{} (#<process shell>)
1565 @xref{Processes}, for information about functions that create, delete,
1566 return information about, send input or signals to, and receive output
1570 @subsection Stream Type
1572 A @dfn{stream} is an object that can be used as a source or sink for
1573 characters---either to supply characters for input or to accept them as
1574 output. Many different types can be used this way: markers, buffers,
1575 strings, and functions. Most often, input streams (character sources)
1576 obtain characters from the keyboard, a buffer, or a file, and output
1577 streams (character sinks) send characters to a buffer, such as a
1578 @file{*Help*} buffer, or to the echo area.
1580 The object @code{nil}, in addition to its other meanings, may be used
1581 as a stream. It stands for the value of the variable
1582 @code{standard-input} or @code{standard-output}. Also, the object
1583 @code{t} as a stream specifies input using the minibuffer
1584 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
1587 Streams have no special printed representation or read syntax, and
1588 print as whatever primitive type they are.
1590 @xref{Read and Print}, for a description of functions
1591 related to streams, including parsing and printing functions.
1594 @subsection Keymap Type
1596 A @dfn{keymap} maps keys typed by the user to commands. This mapping
1597 controls how the user's command input is executed. A keymap is actually
1598 a list whose @sc{car} is the symbol @code{keymap}.
1600 @xref{Keymaps}, for information about creating keymaps, handling prefix
1601 keys, local as well as global keymaps, and changing key bindings.
1604 @subsection Overlay Type
1606 An @dfn{overlay} specifies properties that apply to a part of a
1607 buffer. Each overlay applies to a specified range of the buffer, and
1608 contains a property list (a list whose elements are alternating property
1609 names and values). Overlay properties are used to present parts of the
1610 buffer temporarily in a different display style. Overlays have no read
1611 syntax, and print in hash notation, giving the buffer name and range of
1614 @xref{Overlays}, for how to create and use overlays.
1616 @node Circular Objects
1617 @section Read Syntax for Circular Objects
1618 @cindex circular structure, read syntax
1619 @cindex shared structure, read syntax
1620 @cindex @samp{#@var{n}=} read syntax
1621 @cindex @samp{#@var{n}#} read syntax
1623 To represent shared or circular structures within a complex of Lisp
1624 objects, you can use the reader constructs @samp{#@var{n}=} and
1627 Use @code{#@var{n}=} before an object to label it for later reference;
1628 subsequently, you can use @code{#@var{n}#} to refer the same object in
1629 another place. Here, @var{n} is some integer. For example, here is how
1630 to make a list in which the first element recurs as the third element:
1637 This differs from ordinary syntax such as this
1644 which would result in a list whose first and third elements
1645 look alike but are not the same Lisp object. This shows the difference:
1649 (setq x '(#1=(a) b #1#)))
1650 (eq (nth 0 x) (nth 2 x))
1652 (setq x '((a) b (a)))
1653 (eq (nth 0 x) (nth 2 x))
1657 You can also use the same syntax to make a circular structure, which
1658 appears as an ``element'' within itself. Here is an example:
1665 This makes a list whose second element is the list itself.
1666 Here's how you can see that it really works:
1670 (setq x '#1=(a #1#)))
1675 The Lisp printer can produce this syntax to record circular and shared
1676 structure in a Lisp object, if you bind the variable @code{print-circle}
1677 to a non-@code{nil} value. @xref{Output Variables}.
1679 @node Type Predicates
1680 @section Type Predicates
1681 @cindex type checking
1682 @kindex wrong-type-argument
1684 The Emacs Lisp interpreter itself does not perform type checking on
1685 the actual arguments passed to functions when they are called. It could
1686 not do so, since function arguments in Lisp do not have declared data
1687 types, as they do in other programming languages. It is therefore up to
1688 the individual function to test whether each actual argument belongs to
1689 a type that the function can use.
1691 All built-in functions do check the types of their actual arguments
1692 when appropriate, and signal a @code{wrong-type-argument} error if an
1693 argument is of the wrong type. For example, here is what happens if you
1694 pass an argument to @code{+} that it cannot handle:
1699 @error{} Wrong type argument: number-or-marker-p, a
1703 @cindex type predicates
1704 @cindex testing types
1705 If you want your program to handle different types differently, you
1706 must do explicit type checking. The most common way to check the type
1707 of an object is to call a @dfn{type predicate} function. Emacs has a
1708 type predicate for each type, as well as some predicates for
1709 combinations of types.
1711 A type predicate function takes one argument; it returns @code{t} if
1712 the argument belongs to the appropriate type, and @code{nil} otherwise.
1713 Following a general Lisp convention for predicate functions, most type
1714 predicates' names end with @samp{p}.
1716 Here is an example which uses the predicates @code{listp} to check for
1717 a list and @code{symbolp} to check for a symbol.
1722 ;; If X is a symbol, put it on LIST.
1723 (setq list (cons x list)))
1725 ;; If X is a list, add its elements to LIST.
1726 (setq list (append x list)))
1728 ;; We handle only symbols and lists.
1729 (error "Invalid argument %s in add-on" x))))
1732 Here is a table of predefined type predicates, in alphabetical order,
1733 with references to further information.
1737 @xref{List-related Predicates, atom}.
1740 @xref{Array Functions, arrayp}.
1743 @xref{Bool-Vectors, bool-vector-p}.
1746 @xref{Buffer Basics, bufferp}.
1748 @item byte-code-function-p
1749 @xref{Byte-Code Type, byte-code-function-p}.
1752 @xref{Case Tables, case-table-p}.
1754 @item char-or-string-p
1755 @xref{Predicates for Strings, char-or-string-p}.
1758 @xref{Char-Tables, char-table-p}.
1761 @xref{Interactive Call, commandp}.
1764 @xref{List-related Predicates, consp}.
1766 @item display-table-p
1767 @xref{Display Tables, display-table-p}.
1770 @xref{Predicates on Numbers, floatp}.
1772 @item frame-configuration-p
1773 @xref{Frame Configurations, frame-configuration-p}.
1776 @xref{Deleting Frames, frame-live-p}.
1779 @xref{Frames, framep}.
1782 @xref{Functions, functionp}.
1785 @xref{Other Hash, hash-table-p}.
1787 @item integer-or-marker-p
1788 @xref{Predicates on Markers, integer-or-marker-p}.
1791 @xref{Predicates on Numbers, integerp}.
1794 @xref{Creating Keymaps, keymapp}.
1797 @xref{Constant Variables}.
1800 @xref{List-related Predicates, listp}.
1803 @xref{Predicates on Markers, markerp}.
1806 @xref{Predicates on Numbers, wholenump}.
1809 @xref{List-related Predicates, nlistp}.
1812 @xref{Predicates on Numbers, numberp}.
1814 @item number-or-marker-p
1815 @xref{Predicates on Markers, number-or-marker-p}.
1818 @xref{Overlays, overlayp}.
1821 @xref{Processes, processp}.
1824 @xref{Sequence Functions, sequencep}.
1827 @xref{Predicates for Strings, stringp}.
1830 @xref{Function Cells, subrp}.
1833 @xref{Symbols, symbolp}.
1835 @item syntax-table-p
1836 @xref{Syntax Tables, syntax-table-p}.
1838 @item user-variable-p
1839 @xref{Defining Variables, user-variable-p}.
1842 @xref{Vectors, vectorp}.
1844 @item window-configuration-p
1845 @xref{Window Configurations, window-configuration-p}.
1848 @xref{Deleting Windows, window-live-p}.
1851 @xref{Basic Windows, windowp}.
1854 @xref{nil and t, booleanp}.
1856 @item string-or-null-p
1857 @xref{Predicates for Strings, string-or-null-p}.
1860 The most general way to check the type of an object is to call the
1861 function @code{type-of}. Recall that each object belongs to one and
1862 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
1863 Data Types}). But @code{type-of} knows nothing about non-primitive
1864 types. In most cases, it is more convenient to use type predicates than
1867 @defun type-of object
1868 This function returns a symbol naming the primitive type of
1869 @var{object}. The value is one of the symbols @code{symbol},
1870 @code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector},
1871 @code{char-table}, @code{bool-vector}, @code{hash-table}, @code{subr},
1872 @code{compiled-function}, @code{marker}, @code{overlay}, @code{window},
1873 @code{buffer}, @code{frame}, @code{process}, or
1874 @code{window-configuration}.
1882 (type-of '()) ; @r{@code{()} is @code{nil}.}
1890 @node Equality Predicates
1891 @section Equality Predicates
1894 Here we describe functions that test for equality between any two
1895 objects. Other functions test equality of contents between objects of specific
1896 types, e.g., strings. For these predicates, see the appropriate chapter
1897 describing the data type.
1899 @defun eq object1 object2
1900 This function returns @code{t} if @var{object1} and @var{object2} are
1901 the same object, @code{nil} otherwise.
1903 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
1904 integers with the same value. Also, since symbol names are normally
1905 unique, if the arguments are symbols with the same name, they are
1906 @code{eq}. For other types (e.g., lists, vectors, strings), two
1907 arguments with the same contents or elements are not necessarily
1908 @code{eq} to each other: they are @code{eq} only if they are the same
1909 object, meaning that a change in the contents of one will be reflected
1910 by the same change in the contents of the other.
1931 ;; @r{This exception occurs because Emacs Lisp}
1932 ;; @r{makes just one multibyte empty string, to save space.}
1936 (eq '(1 (2 (3))) '(1 (2 (3))))
1941 (setq foo '(1 (2 (3))))
1942 @result{} (1 (2 (3)))
1945 (eq foo '(1 (2 (3))))
1950 (eq [(1 2) 3] [(1 2) 3])
1955 (eq (point-marker) (point-marker))
1960 The @code{make-symbol} function returns an uninterned symbol, distinct
1961 from the symbol that is used if you write the name in a Lisp expression.
1962 Distinct symbols with the same name are not @code{eq}. @xref{Creating
1967 (eq (make-symbol "foo") 'foo)
1973 @defun equal object1 object2
1974 This function returns @code{t} if @var{object1} and @var{object2} have
1975 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
1976 arguments are the same object, @code{equal} looks inside nonidentical
1977 arguments to see if their elements or contents are the same. So, if two
1978 objects are @code{eq}, they are @code{equal}, but the converse is not
1993 (equal "asdf" "asdf")
2002 (equal '(1 (2 (3))) '(1 (2 (3))))
2006 (eq '(1 (2 (3))) '(1 (2 (3))))
2011 (equal [(1 2) 3] [(1 2) 3])
2015 (eq [(1 2) 3] [(1 2) 3])
2020 (equal (point-marker) (point-marker))
2025 (eq (point-marker) (point-marker))
2030 Comparison of strings is case-sensitive, but does not take account of
2031 text properties---it compares only the characters in the strings. Use
2032 @code{equal-including-properties} to also compare text properties. For
2033 technical reasons, a unibyte string and a multibyte string are
2034 @code{equal} if and only if they contain the same sequence of
2035 character codes and all these codes are either in the range 0 through
2036 127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}).
2037 (@pxref{Text Representations}).
2041 (equal "asdf" "ASDF")
2046 However, two distinct buffers are never considered @code{equal}, even if
2047 their textual contents are the same.
2050 The test for equality is implemented recursively; for example, given
2051 two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})}
2052 returns @code{t} if and only if both the expressions below return
2056 (equal (car @var{x}) (car @var{y}))
2057 (equal (cdr @var{x}) (cdr @var{y}))
2060 Because of this recursive method, circular lists may therefore cause
2061 infinite recursion (leading to an error).
2063 @defun equal-including-properties object1 object2
2064 This function behaves like @code{equal} in all cases but also requires
2065 that for two strings to be equal, they have the same text properties.
2069 (equal "asdf" (propertize "asdf" '(asdf t)))
2073 (equal-including-properties "asdf"
2074 (propertize "asdf" '(asdf t)))
2081 arch-tag: 9711a66e-4749-4265-9e8c-972d55b67096