2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
4 @c 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.
47 This chapter describes the purpose, printed representation, and read
48 syntax of each of the standard types in GNU Emacs Lisp. Details on how
49 to use these types can be found in later chapters.
52 * Printed Representation:: How Lisp objects are represented as text.
53 * Comments:: Comments and their formatting conventions.
54 * Programming Types:: Types found in all Lisp systems.
55 * Editing Types:: Types specific to Emacs.
56 * Circular Objects:: Read syntax for circular structure.
57 * Type Predicates:: Tests related to types.
58 * Equality Predicates:: Tests of equality between any two objects.
61 @node Printed Representation
62 @comment node-name, next, previous, up
63 @section Printed Representation and Read Syntax
64 @cindex printed representation
67 The @dfn{printed representation} of an object is the format of the
68 output generated by the Lisp printer (the function @code{prin1}) for
69 that object. The @dfn{read syntax} of an object is the format of the
70 input accepted by the Lisp reader (the function @code{read}) for that
71 object. @xref{Read and Print}.
73 Most objects have more than one possible read syntax. Some types of
74 object have no read syntax, since it may not make sense to enter objects
75 of these types directly in a Lisp program. Except for these cases, the
76 printed representation of an object is also a read syntax for it.
78 In other languages, an expression is text; it has no other form. In
79 Lisp, an expression is primarily a Lisp object and only secondarily the
80 text that is the object's read syntax. Often there is no need to
81 emphasize this distinction, but you must keep it in the back of your
82 mind, or you will occasionally be very confused.
85 Every type has a printed representation. Some types have no read
86 syntax---for example, the buffer type has none. Objects of these types
87 are printed in @dfn{hash notation}: the characters @samp{#<} followed by
88 a descriptive string (typically the type name followed by the name of
89 the object), and closed with a matching @samp{>}. Hash notation cannot
90 be read at all, so the Lisp reader signals the error
91 @code{invalid-read-syntax} whenever it encounters @samp{#<}.
92 @kindex invalid-read-syntax
96 @result{} #<buffer objects.texi>
99 When you evaluate an expression interactively, the Lisp interpreter
100 first reads the textual representation of it, producing a Lisp object,
101 and then evaluates that object (@pxref{Evaluation}). However,
102 evaluation and reading are separate activities. Reading returns the
103 Lisp object represented by the text that is read; the object may or may
104 not be evaluated later. @xref{Input Functions}, for a description of
105 @code{read}, the basic function for reading objects.
108 @comment node-name, next, previous, up
111 @cindex @samp{;} in comment
113 A @dfn{comment} is text that is written in a program only for the sake
114 of humans that read the program, and that has no effect on the meaning
115 of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
116 is not within a string or character constant. The comment continues to
117 the end of line. The Lisp reader discards comments; they do not become
118 part of the Lisp objects which represent the program within the Lisp
121 The @samp{#@@@var{count}} construct, which skips the next @var{count}
122 characters, is useful for program-generated comments containing binary
123 data. The Emacs Lisp byte compiler uses this in its output files
124 (@pxref{Byte Compilation}). It isn't meant for source files, however.
126 @xref{Comment Tips}, for conventions for formatting comments.
128 @node Programming Types
129 @section Programming Types
130 @cindex programming types
132 There are two general categories of types in Emacs Lisp: those having
133 to do with Lisp programming, and those having to do with editing. The
134 former exist in many Lisp implementations, in one form or another. The
135 latter are unique to Emacs Lisp.
138 * Integer Type:: Numbers without fractional parts.
139 * Floating Point Type:: Numbers with fractional parts and with a large range.
140 * Character Type:: The representation of letters, numbers and
142 * Symbol Type:: A multi-use object that refers to a function,
143 variable, or property list, and has a unique identity.
144 * Sequence Type:: Both lists and arrays are classified as sequences.
145 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
146 * Array Type:: Arrays include strings and vectors.
147 * String Type:: An (efficient) array of characters.
148 * Vector Type:: One-dimensional arrays.
149 * Char-Table Type:: One-dimensional sparse arrays indexed by characters.
150 * Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}.
151 * Hash Table Type:: Super-fast lookup tables.
152 * Function Type:: A piece of executable code you can call from elsewhere.
153 * Macro Type:: A method of expanding an expression into another
154 expression, more fundamental but less pretty.
155 * Primitive Function Type:: A function written in C, callable from Lisp.
156 * Byte-Code Type:: A function written in Lisp, then compiled.
157 * Autoload Type:: A type used for automatically loading seldom-used
162 @subsection Integer Type
164 The range of values for integers in Emacs Lisp is @minus{}134217728 to
165 134217727 (28 bits; i.e.,
179 on most machines. (Some machines may provide a wider range.) It is
180 important to note that the Emacs Lisp arithmetic functions do not check
181 for overflow. Thus @code{(1+ 134217727)} is @minus{}134217728 on most
184 The read syntax for integers is a sequence of (base ten) digits with an
185 optional sign at the beginning and an optional period at the end. The
186 printed representation produced by the Lisp interpreter never has a
187 leading @samp{+} or a final @samp{.}.
191 -1 ; @r{The integer -1.}
192 1 ; @r{The integer 1.}
193 1. ; @r{Also the integer 1.}
194 +1 ; @r{Also the integer 1.}
195 268435457 ; @r{Also the integer 1 on a 28-bit implementation.}
199 @xref{Numbers}, for more information.
201 @node Floating Point Type
202 @subsection Floating Point Type
204 Floating point numbers are the computer equivalent of scientific
205 notation. The precise number of significant figures and the range of
206 possible exponents is machine-specific; Emacs always uses the C data
207 type @code{double} to store the value.
209 The printed representation for floating point numbers requires either
210 a decimal point (with at least one digit following), an exponent, or
211 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
212 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
213 number whose value is 1500. They are all equivalent.
215 @xref{Numbers}, for more information.
218 @subsection Character Type
219 @cindex @sc{ascii} character codes
221 A @dfn{character} in Emacs Lisp is nothing more than an integer. In
222 other words, characters are represented by their character codes. For
223 example, the character @kbd{A} is represented as the @w{integer 65}.
225 Individual characters are not often used in programs. It is far more
226 common to work with @emph{strings}, which are sequences composed of
227 characters. @xref{String Type}.
229 Characters in strings, buffers, and files are currently limited to the
230 range of 0 to 524287---nineteen bits. But not all values in that range
231 are valid character codes. Codes 0 through 127 are @sc{ascii} codes; the
232 rest are non-@sc{ascii} (@pxref{Non-ASCII Characters}). Characters that represent
233 keyboard input have a much wider range, to encode modifier keys such as
234 Control, Meta and Shift.
236 @cindex read syntax for characters
237 @cindex printed representation for characters
238 @cindex syntax for characters
239 @cindex @samp{?} in character constant
240 @cindex question mark in character constant
241 Since characters are really integers, the printed representation of a
242 character is a decimal number. This is also a possible read syntax for
243 a character, but writing characters that way in Lisp programs is a very
244 bad idea. You should @emph{always} use the special read syntax formats
245 that Emacs Lisp provides for characters. These syntax formats start
246 with a question mark.
248 The usual read syntax for alphanumeric characters is a question mark
249 followed by the character; thus, @samp{?A} for the character
250 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
256 ?Q @result{} 81 ?q @result{} 113
259 You can use the same syntax for punctuation characters, but it is
260 often a good idea to add a @samp{\} so that the Emacs commands for
261 editing Lisp code don't get confused. For example, @samp{?\(} is the
262 way to write the open-paren character. If the character is @samp{\},
263 you @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
266 @cindex bell character
284 You can express the characters control-g, backspace, tab, newline,
285 vertical tab, formfeed, space, return, del, and escape as @samp{?\a},
286 @samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f},
287 @samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively.
291 ?\a @result{} 7 ; @r{control-g, @kbd{C-g}}
292 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
293 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
294 ?\n @result{} 10 ; @r{newline, @kbd{C-j}}
295 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
296 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
297 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
298 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
299 ?\s @result{} 32 ; @r{space character, @key{SPC}}
300 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
301 ?\d @result{} 127 ; @r{delete character, @key{DEL}}
304 @cindex escape sequence
305 These sequences which start with backslash are also known as
306 @dfn{escape sequences}, because backslash plays the role of an
307 ``escape character''; this terminology has nothing to do with the
308 character @key{ESC}. @samp{\s} is meant for use only in character
309 constants; in string constants, just write the space.
311 @cindex control characters
312 Control characters may be represented using yet another read syntax.
313 This consists of a question mark followed by a backslash, caret, and the
314 corresponding non-control character, in either upper or lower case. For
315 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
316 character @kbd{C-i}, the character whose value is 9.
318 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
319 equivalent to @samp{?\^I} and to @samp{?\^i}:
322 ?\^I @result{} 9 ?\C-I @result{} 9
325 In strings and buffers, the only control characters allowed are those
326 that exist in @sc{ascii}; but for keyboard input purposes, you can turn
327 any character into a control character with @samp{C-}. The character
328 codes for these non-@sc{ascii} control characters include the
335 bit as well as the code for the corresponding non-control
336 character. Ordinary terminals have no way of generating non-@sc{ascii}
337 control characters, but you can generate them straightforwardly using X
338 and other window systems.
340 For historical reasons, Emacs treats the @key{DEL} character as
341 the control equivalent of @kbd{?}:
344 ?\^? @result{} 127 ?\C-? @result{} 127
348 As a result, it is currently not possible to represent the character
349 @kbd{Control-?}, which is a meaningful input character under X, using
350 @samp{\C-}. It is not easy to change this, as various Lisp files refer
351 to @key{DEL} in this way.
353 For representing control characters to be found in files or strings,
354 we recommend the @samp{^} syntax; for control characters in keyboard
355 input, we prefer the @samp{C-} syntax. Which one you use does not
356 affect the meaning of the program, but may guide the understanding of
359 @cindex meta characters
360 A @dfn{meta character} is a character typed with the @key{META}
361 modifier key. The integer that represents such a character has the
368 bit set (which on most machines makes it a negative number). We
369 use high bits for this and other modifiers to make possible a wide range
370 of basic character codes.
379 bit attached to an @sc{ascii} character indicates a meta character; thus, the
380 meta characters that can fit in a string have codes in the range from
381 128 to 255, and are the meta versions of the ordinary @sc{ascii}
382 characters. (In Emacs versions 18 and older, this convention was used
383 for characters outside of strings as well.)
385 The read syntax for meta characters uses @samp{\M-}. For example,
386 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
387 octal character codes (see below), with @samp{\C-}, or with any other
388 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
389 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
390 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
392 The case of a graphic character is indicated by its character code;
393 for example, @sc{ascii} distinguishes between the characters @samp{a}
394 and @samp{A}. But @sc{ascii} has no way to represent whether a control
395 character is upper case or lower case. Emacs uses the
402 bit to indicate that the shift key was used in typing a control
403 character. This distinction is possible only when you use X terminals
404 or other special terminals; ordinary terminals do not report the
405 distinction to the computer in any way. The Lisp syntax for
406 the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O}
407 represents the shifted-control-o character.
409 @cindex hyper characters
410 @cindex super characters
411 @cindex alt characters
412 The X Window System defines three other @anchor{modifier bits}
413 modifier bits that can be set
414 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
415 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is
416 significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents
417 @kbd{Alt-Hyper-Meta-x}. (Note that @samp{\s} with no following @samp{-}
418 represents the space character.)
421 bit values are @math{2^{22}} for alt, @math{2^{23}} for super and @math{2^{24}} for hyper.
425 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
428 @cindex @samp{\} in character constant
429 @cindex backslash in character constant
430 @cindex octal character code
431 Finally, the most general read syntax for a character represents the
432 character code in either octal or hex. To use octal, write a question
433 mark followed by a backslash and the octal character code (up to three
434 octal digits); thus, @samp{?\101} for the character @kbd{A},
435 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
436 character @kbd{C-b}. Although this syntax can represent any @sc{ascii}
437 character, it is preferred only when the precise octal value is more
438 important than the @sc{ascii} representation.
442 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
443 ?\101 @result{} 65 ?A @result{} 65
447 To use hex, write a question mark followed by a backslash, @samp{x},
448 and the hexadecimal character code. You can use any number of hex
449 digits, so you can represent any character code in this way.
450 Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
451 character @kbd{C-a}, and @code{?\x8e0} for the Latin-1 character
456 @samp{a} with grave accent.
459 A backslash is allowed, and harmless, preceding any character without
460 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
461 There is no reason to add a backslash before most characters. However,
462 you should add a backslash before any of the characters
463 @samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
464 Lisp code. You can also add a backslash before whitespace characters such as
465 space, tab, newline and formfeed. However, it is cleaner to use one of
466 the easily readable escape sequences, such as @samp{\t} or @samp{\s},
467 instead of an actual whitespace character such as a tab or a space.
468 (If you do write backslash followed by a space, you should write
469 an extra space after the character constant to separate it from the
473 @subsection Symbol Type
475 A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The symbol
476 name serves as the printed representation of the symbol. In ordinary
477 use, the name is unique---no two symbols have the same name.
479 A symbol can serve as a variable, as a function name, or to hold a
480 property list. Or it may serve only to be distinct from all other Lisp
481 objects, so that its presence in a data structure may be recognized
482 reliably. In a given context, usually only one of these uses is
483 intended. But you can use one symbol in all of these ways,
486 A symbol whose name starts with a colon (@samp{:}) is called a
487 @dfn{keyword symbol}. These symbols automatically act as constants, and
488 are normally used only by comparing an unknown symbol with a few
489 specific alternatives.
491 @cindex @samp{\} in symbols
492 @cindex backslash in symbols
493 A symbol name can contain any characters whatever. Most symbol names
494 are written with letters, digits, and the punctuation characters
495 @samp{-+=*/}. Such names require no special punctuation; the characters
496 of the name suffice as long as the name does not look like a number.
497 (If it does, write a @samp{\} at the beginning of the name to force
498 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}?} are
499 less often used but also require no special punctuation. Any other
500 characters may be included in a symbol's name by escaping them with a
501 backslash. In contrast to its use in strings, however, a backslash in
502 the name of a symbol simply quotes the single character that follows the
503 backslash. For example, in a string, @samp{\t} represents a tab
504 character; in the name of a symbol, however, @samp{\t} merely quotes the
505 letter @samp{t}. To have a symbol with a tab character in its name, you
506 must actually use a tab (preceded with a backslash). But it's rare to
509 @cindex CL note---case of letters
511 @b{Common Lisp note:} In Common Lisp, lower case letters are always
512 ``folded'' to upper case, unless they are explicitly escaped. In Emacs
513 Lisp, upper case and lower case letters are distinct.
516 Here are several examples of symbol names. Note that the @samp{+} in
517 the fifth example is escaped to prevent it from being read as a number.
518 This is not necessary in the seventh example because the rest of the name
519 makes it invalid as a number.
523 foo ; @r{A symbol named @samp{foo}.}
524 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
525 char-to-string ; @r{A symbol named @samp{char-to-string}.}
528 1+ ; @r{A symbol named @samp{1+}}
529 ; @r{(not @samp{+1}, which is an integer).}
532 \+1 ; @r{A symbol named @samp{+1}}
533 ; @r{(not a very readable name).}
536 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
537 @c the @'s in this next line use up three characters, hence the
538 @c apparent misalignment of the comment.
539 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
540 ; @r{These characters need not be escaped.}
545 @c This uses ``colon'' instead of a literal `:' because Info cannot
546 @c cope with a `:' in a menu
547 @cindex @samp{#@var{colon}} read syntax
550 @cindex @samp{#:} read syntax
552 Normally the Lisp reader interns all symbols (@pxref{Creating
553 Symbols}). To prevent interning, you can write @samp{#:} before the
557 @subsection Sequence Types
559 A @dfn{sequence} is a Lisp object that represents an ordered set of
560 elements. There are two kinds of sequence in Emacs Lisp, lists and
561 arrays. Thus, an object of type list or of type array is also
562 considered a sequence.
564 Arrays are further subdivided into strings, vectors, char-tables and
565 bool-vectors. Vectors can hold elements of any type, but string
566 elements must be characters, and bool-vector elements must be @code{t}
567 or @code{nil}. Char-tables are like vectors except that they are
568 indexed by any valid character code. The characters in a string can
569 have text properties like characters in a buffer (@pxref{Text
570 Properties}), but vectors do not support text properties, even when
571 their elements happen to be characters.
573 Lists, strings and the other array types are different, but they have
574 important similarities. For example, all have a length @var{l}, and all
575 have elements which can be indexed from zero to @var{l} minus one.
576 Several functions, called sequence functions, accept any kind of
577 sequence. For example, the function @code{elt} can be used to extract
578 an element of a sequence, given its index. @xref{Sequences Arrays
581 It is generally impossible to read the same sequence twice, since
582 sequences are always created anew upon reading. If you read the read
583 syntax for a sequence twice, you get two sequences with equal contents.
584 There is one exception: the empty list @code{()} always stands for the
585 same object, @code{nil}.
588 @subsection Cons Cell and List Types
589 @cindex address field of register
590 @cindex decrement field of register
593 A @dfn{cons cell} is an object that consists of two slots, called the
594 @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or
595 @dfn{refer to} any Lisp object. We also say that ``the @sc{car} of
596 this cons cell is'' whatever object its @sc{car} slot currently holds,
597 and likewise for the @sc{cdr}.
600 A note to C programmers: in Lisp, we do not distinguish between
601 ``holding'' a value and ``pointing to'' the value, because pointers in
605 A @dfn{list} is a series of cons cells, linked together so that the
606 @sc{cdr} slot of each cons cell holds either the next cons cell or the
607 empty list. @xref{Lists}, for functions that work on lists. Because
608 most cons cells are used as part of lists, the phrase @dfn{list
609 structure} has come to refer to any structure made out of cons cells.
611 The names @sc{car} and @sc{cdr} derive from the history of Lisp. The
612 original Lisp implementation ran on an @w{IBM 704} computer which
613 divided words into two parts, called the ``address'' part and the
614 ``decrement''; @sc{car} was an instruction to extract the contents of
615 the address part of a register, and @sc{cdr} an instruction to extract
616 the contents of the decrement. By contrast, ``cons cells'' are named
617 for the function @code{cons} that creates them, which in turn was named
618 for its purpose, the construction of cells.
621 Because cons cells are so central to Lisp, we also have a word for
622 ``an object which is not a cons cell''. These objects are called
626 The read syntax and printed representation for lists are identical, and
627 consist of a left parenthesis, an arbitrary number of elements, and a
630 Upon reading, each object inside the parentheses becomes an element
631 of the list. That is, a cons cell is made for each element. The
632 @sc{car} slot of the cons cell holds the element, and its @sc{cdr}
633 slot refers to the next cons cell of the list, which holds the next
634 element in the list. The @sc{cdr} slot of the last cons cell is set to
637 @cindex box diagrams, for lists
638 @cindex diagrams, boxed, for lists
639 A list can be illustrated by a diagram in which the cons cells are
640 shown as pairs of boxes, like dominoes. (The Lisp reader cannot read
641 such an illustration; unlike the textual notation, which can be
642 understood by both humans and computers, the box illustrations can be
643 understood only by humans.) This picture represents the three-element
644 list @code{(rose violet buttercup)}:
648 --- --- --- --- --- ---
649 | | |--> | | |--> | | |--> nil
650 --- --- --- --- --- ---
653 --> rose --> violet --> buttercup
657 In this diagram, each box represents a slot that can hold or refer to
658 any Lisp object. Each pair of boxes represents a cons cell. Each arrow
659 represents a reference to a Lisp object, either an atom or another cons
662 In this example, the first box, which holds the @sc{car} of the first
663 cons cell, refers to or ``holds'' @code{rose} (a symbol). The second
664 box, holding the @sc{cdr} of the first cons cell, refers to the next
665 pair of boxes, the second cons cell. The @sc{car} of the second cons
666 cell is @code{violet}, and its @sc{cdr} is the third cons cell. The
667 @sc{cdr} of the third (and last) cons cell is @code{nil}.
669 Here is another diagram of the same list, @code{(rose violet
670 buttercup)}, sketched in a different manner:
674 --------------- ---------------- -------------------
675 | car | cdr | | car | cdr | | car | cdr |
676 | rose | o-------->| violet | o-------->| buttercup | nil |
678 --------------- ---------------- -------------------
682 @cindex @samp{(@dots{})} in lists
683 @cindex @code{nil} in lists
685 A list with no elements in it is the @dfn{empty list}; it is identical
686 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
689 Here are examples of lists written in Lisp syntax:
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 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
703 depicted with boxes and arrows:
708 | | |--> | | |--> nil
717 * Dotted Pair Notation:: An alternative syntax for lists.
718 * Association List Type:: A specially constructed list.
721 @node Dotted Pair Notation
722 @comment node-name, next, previous, up
723 @subsubsection Dotted Pair Notation
724 @cindex dotted pair notation
725 @cindex @samp{.} in lists
727 @dfn{Dotted pair notation} is an alternative syntax for cons cells
728 that represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
729 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
730 the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted
731 pair notation is therefore more general than list syntax. In the dotted
732 pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
733 . nil)))}. For @code{nil}-terminated lists, you can use either
734 notation, but list notation is usually clearer and more convenient.
735 When printing a list, the dotted pair notation is only used if the
736 @sc{cdr} of a cons cell is not a list.
738 Here's an example using boxes to illustrate dotted pair notation.
739 This example shows the pair @code{(rose . violet)}:
752 You can combine dotted pair notation with list notation to represent
753 conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}.
754 You write a dot after the last element of the list, followed by the
755 @sc{cdr} of the final cons cell. For example, @code{(rose violet
756 . buttercup)} is equivalent to @code{(rose . (violet . buttercup))}.
757 The object looks like this:
762 | | |--> | | |--> buttercup
770 The syntax @code{(rose .@: violet .@: buttercup)} is invalid because
771 there is nothing that it could mean. If anything, it would say to put
772 @code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already
773 used for @code{violet}.
775 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))},
781 | | |--> | | |--> nil
789 Similarly, the three-element list @code{(rose violet buttercup)}
790 is equivalent to @code{(rose . (violet . (buttercup)))}.
796 --- --- --- --- --- ---
797 | | |--> | | |--> | | |--> nil
798 --- --- --- --- --- ---
801 --> rose --> violet --> buttercup
806 @node Association List Type
807 @comment node-name, next, previous, up
808 @subsubsection Association List Type
810 An @dfn{association list} or @dfn{alist} is a specially-constructed
811 list whose elements are cons cells. In each element, the @sc{car} is
812 considered a @dfn{key}, and the @sc{cdr} is considered an
813 @dfn{associated value}. (In some cases, the associated value is stored
814 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
815 stacks, since it is easy to add or remove associations at the front of
821 (setq alist-of-colors
822 '((rose . red) (lily . white) (buttercup . yellow)))
826 sets the variable @code{alist-of-colors} to an alist of three elements. In the
827 first element, @code{rose} is the key and @code{red} is the value.
829 @xref{Association Lists}, for a further explanation of alists and for
830 functions that work on alists. @xref{Hash Tables}, for another kind of
831 lookup table, which is much faster for handling a large number of keys.
834 @subsection Array Type
836 An @dfn{array} is composed of an arbitrary number of slots for
837 holding or referring to other Lisp objects, arranged in a contiguous block of
838 memory. Accessing any element of an array takes approximately the same
839 amount of time. In contrast, accessing an element of a list requires
840 time proportional to the position of the element in the list. (Elements
841 at the end of a list take longer to access than elements at the
842 beginning of a list.)
844 Emacs defines four types of array: strings, vectors, bool-vectors, and
847 A string is an array of characters and a vector is an array of
848 arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}.
849 These kinds of array may have any length up to the largest integer.
850 Char-tables are sparse arrays indexed by any valid character code; they
851 can hold arbitrary objects.
853 The first element of an array has index zero, the second element has
854 index 1, and so on. This is called @dfn{zero-origin} indexing. For
855 example, an array of four elements has indices 0, 1, 2, @w{and 3}. The
856 largest possible index value is one less than the length of the array.
857 Once an array is created, its length is fixed.
859 All Emacs Lisp arrays are one-dimensional. (Most other programming
860 languages support multidimensional arrays, but they are not essential;
861 you can get the same effect with an array of arrays.) Each type of
862 array has its own read syntax; see the following sections for details.
864 The array type is contained in the sequence type and
865 contains the string type, the vector type, the bool-vector type, and the
869 @subsection String Type
871 A @dfn{string} is an array of characters. Strings are used for many
872 purposes in Emacs, as can be expected in a text editor; for example, as
873 the names of Lisp symbols, as messages for the user, and to represent
874 text extracted from buffers. Strings in Lisp are constants: evaluation
875 of a string returns the same string.
877 @xref{Strings and Characters}, for functions that operate on strings.
880 * Syntax for Strings::
881 * Non-ASCII in Strings::
882 * Nonprinting Characters::
883 * Text Props and Strings::
886 @node Syntax for Strings
887 @subsubsection Syntax for Strings
889 @cindex @samp{"} in strings
890 @cindex double-quote in strings
891 @cindex @samp{\} in strings
892 @cindex backslash in strings
893 The read syntax for strings is a double-quote, an arbitrary number of
894 characters, and another double-quote, @code{"like this"}. To include a
895 double-quote in a string, precede it with a backslash; thus, @code{"\""}
896 is a string containing just a single double-quote character. Likewise,
897 you can include a backslash by preceding it with another backslash, like
898 this: @code{"this \\ is a single embedded backslash"}.
900 @cindex newline in strings
901 The newline character is not special in the read syntax for strings;
902 if you write a new line between the double-quotes, it becomes a
903 character in the string. But an escaped newline---one that is preceded
904 by @samp{\}---does not become part of the string; i.e., the Lisp reader
905 ignores an escaped newline while reading a string. An escaped space
906 @w{@samp{\ }} is likewise ignored.
909 "It is useful to include newlines
910 in documentation strings,
913 @result{} "It is useful to include newlines
914 in documentation strings,
915 but the newline is ignored if escaped."
918 @node Non-ASCII in Strings
919 @subsubsection Non-@sc{ascii} Characters in Strings
921 You can include a non-@sc{ascii} international character in a string
922 constant by writing it literally. There are two text representations
923 for non-@sc{ascii} characters in Emacs strings (and in buffers): unibyte
924 and multibyte. If the string constant is read from a multibyte source,
925 such as a multibyte buffer or string, or a file that would be visited as
926 multibyte, then the character is read as a multibyte character, and that
927 makes the string multibyte. If the string constant is read from a
928 unibyte source, then the character is read as unibyte and that makes the
931 You can also represent a multibyte non-@sc{ascii} character with its
932 character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
933 digits as necessary. (Multibyte non-@sc{ascii} character codes are all
934 greater than 256.) Any character which is not a valid hex digit
935 terminates this construct. If the next character in the string could be
936 interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
937 terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents
938 one character, @samp{a} with grave accent. @w{@samp{\ }} in a string
939 constant is just like backslash-newline; it does not contribute any
940 character to the string, but it does terminate the preceding hex escape.
942 Using a multibyte hex escape forces the string to multibyte. You can
943 represent a unibyte non-@sc{ascii} character with its character code,
944 which must be in the range from 128 (0200 octal) to 255 (0377 octal).
945 This forces a unibyte string.
947 @xref{Text Representations}, for more information about the two
948 text representations.
950 @node Nonprinting Characters
951 @subsubsection Nonprinting Characters in Strings
953 You can use the same backslash escape-sequences in a string constant
954 as in character literals (but do not use the question mark that begins a
955 character constant). For example, you can write a string containing the
956 nonprinting characters tab and @kbd{C-a}, with commas and spaces between
957 them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a
958 description of the read syntax for characters.
960 However, not all of the characters you can write with backslash
961 escape-sequences are valid in strings. The only control characters that
962 a string can hold are the @sc{ascii} control characters. Strings do not
963 distinguish case in @sc{ascii} control characters.
965 Properly speaking, strings cannot hold meta characters; but when a
966 string is to be used as a key sequence, there is a special convention
967 that provides a way to represent meta versions of @sc{ascii} characters in a
968 string. If you use the @samp{\M-} syntax to indicate a meta character
969 in a string constant, this sets the
976 bit of the character in the string. If the string is used in
977 @code{define-key} or @code{lookup-key}, this numeric code is translated
978 into the equivalent meta character. @xref{Character Type}.
980 Strings cannot hold characters that have the hyper, super, or alt
983 @node Text Props and Strings
984 @subsubsection Text Properties in Strings
986 A string can hold properties for the characters it contains, in
987 addition to the characters themselves. This enables programs that copy
988 text between strings and buffers to copy the text's properties with no
989 special effort. @xref{Text Properties}, for an explanation of what text
990 properties mean. Strings with text properties use a special read and
994 #("@var{characters}" @var{property-data}...)
998 where @var{property-data} consists of zero or more elements, in groups
1002 @var{beg} @var{end} @var{plist}
1006 The elements @var{beg} and @var{end} are integers, and together specify
1007 a range of indices in the string; @var{plist} is the property list for
1008 that range. For example,
1011 #("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
1015 represents a string whose textual contents are @samp{foo bar}, in which
1016 the first three characters have a @code{face} property with value
1017 @code{bold}, and the last three have a @code{face} property with value
1018 @code{italic}. (The fourth character has no text properties, so its
1019 property list is @code{nil}. It is not actually necessary to mention
1020 ranges with @code{nil} as the property list, since any characters not
1021 mentioned in any range will default to having no properties.)
1024 @subsection Vector Type
1026 A @dfn{vector} is a one-dimensional array of elements of any type. It
1027 takes a constant amount of time to access any element of a vector. (In
1028 a list, the access time of an element is proportional to the distance of
1029 the element from the beginning of the list.)
1031 The printed representation of a vector consists of a left square
1032 bracket, the elements, and a right square bracket. This is also the
1033 read syntax. Like numbers and strings, vectors are considered constants
1037 [1 "two" (three)] ; @r{A vector of three elements.}
1038 @result{} [1 "two" (three)]
1041 @xref{Vectors}, for functions that work with vectors.
1043 @node Char-Table Type
1044 @subsection Char-Table Type
1046 A @dfn{char-table} is a one-dimensional array of elements of any type,
1047 indexed by character codes. Char-tables have certain extra features to
1048 make them more useful for many jobs that involve assigning information
1049 to character codes---for example, a char-table can have a parent to
1050 inherit from, a default value, and a small number of extra slots to use for
1051 special purposes. A char-table can also specify a single value for
1052 a whole character set.
1054 The printed representation of a char-table is like a vector
1055 except that there is an extra @samp{#^} at the beginning.
1057 @xref{Char-Tables}, for special functions to operate on char-tables.
1058 Uses of char-tables include:
1062 Case tables (@pxref{Case Tables}).
1065 Character category tables (@pxref{Categories}).
1068 Display tables (@pxref{Display Tables}).
1071 Syntax tables (@pxref{Syntax Tables}).
1074 @node Bool-Vector Type
1075 @subsection Bool-Vector Type
1077 A @dfn{bool-vector} is a one-dimensional array of elements that
1078 must be @code{t} or @code{nil}.
1080 The printed representation of a bool-vector is like a string, except
1081 that it begins with @samp{#&} followed by the length. The string
1082 constant that follows actually specifies the contents of the bool-vector
1083 as a bitmap---each ``character'' in the string contains 8 bits, which
1084 specify the next 8 elements of the bool-vector (1 stands for @code{t},
1085 and 0 for @code{nil}). The least significant bits of the character
1086 correspond to the lowest indices in the bool-vector. If the length is not a
1087 multiple of 8, the printed representation shows extra elements, but
1088 these extras really make no difference.
1091 (make-bool-vector 3 t)
1093 (make-bool-vector 3 nil)
1095 ;; @r{These are equal since only the first 3 bits are used.}
1096 (equal #&3"\377" #&3"\007")
1100 @node Hash Table Type
1101 @subsection Hash Table Type
1103 A hash table is a very fast kind of lookup table, somewhat like an
1104 alist in that it maps keys to corresponding values, but much faster.
1105 Hash tables are a new feature in Emacs 21; they have no read syntax, and
1106 print using hash notation. @xref{Hash Tables}.
1110 @result{} #<hash-table 'eql nil 0/65 0x83af980>
1114 @subsection Function Type
1116 Just as functions in other programming languages are executable,
1117 @dfn{Lisp function} objects are pieces of executable code. However,
1118 functions in Lisp are primarily Lisp objects, and only secondarily the
1119 text which represents them. These Lisp objects are lambda expressions:
1120 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
1123 In most programming languages, it is impossible to have a function
1124 without a name. In Lisp, a function has no intrinsic name. A lambda
1125 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
1126 Functions}). A named function in Lisp is actually a symbol with a valid
1127 function in its function cell (@pxref{Defining Functions}).
1129 Most of the time, functions are called when their names are written in
1130 Lisp expressions in Lisp programs. However, you can construct or obtain
1131 a function object at run time and then call it with the primitive
1132 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
1135 @subsection Macro Type
1137 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
1138 language. It is represented as an object much like a function, but with
1139 different argument-passing semantics. A Lisp macro has the form of a
1140 list whose first element is the symbol @code{macro} and whose @sc{cdr}
1141 is a Lisp function object, including the @code{lambda} symbol.
1143 Lisp macro objects are usually defined with the built-in
1144 @code{defmacro} function, but any list that begins with @code{macro} is
1145 a macro as far as Emacs is concerned. @xref{Macros}, for an explanation
1146 of how to write a macro.
1148 @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard
1149 Macros}) are entirely different things. When we use the word ``macro''
1150 without qualification, we mean a Lisp macro, not a keyboard macro.
1152 @node Primitive Function Type
1153 @subsection Primitive Function Type
1154 @cindex special forms
1156 A @dfn{primitive function} is a function callable from Lisp but
1157 written in the C programming language. Primitive functions are also
1158 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
1159 derived from ``subroutine''.) Most primitive functions evaluate all
1160 their arguments when they are called. A primitive function that does
1161 not evaluate all its arguments is called a @dfn{special form}
1162 (@pxref{Special Forms}).@refill
1164 It does not matter to the caller of a function whether the function is
1165 primitive. However, this does matter if you try to redefine a primitive
1166 with a function written in Lisp. The reason is that the primitive
1167 function may be called directly from C code. Calls to the redefined
1168 function from Lisp will use the new definition, but calls from C code
1169 may still use the built-in definition. Therefore, @strong{we discourage
1170 redefinition of primitive functions}.
1172 The term @dfn{function} refers to all Emacs functions, whether written
1173 in Lisp or C. @xref{Function Type}, for information about the
1174 functions written in Lisp.
1176 Primitive functions have no read syntax and print in hash notation
1177 with the name of the subroutine.
1181 (symbol-function 'car) ; @r{Access the function cell}
1182 ; @r{of the symbol.}
1183 @result{} #<subr car>
1184 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
1185 @result{} t ; @r{Yes.}
1189 @node Byte-Code Type
1190 @subsection Byte-Code Function Type
1192 The byte compiler produces @dfn{byte-code function objects}.
1193 Internally, a byte-code function object is much like a vector; however,
1194 the evaluator handles this data type specially when it appears as a
1195 function to be called. @xref{Byte Compilation}, for information about
1198 The printed representation and read syntax for a byte-code function
1199 object is like that for a vector, with an additional @samp{#} before the
1203 @subsection Autoload Type
1205 An @dfn{autoload object} is a list whose first element is the symbol
1206 @code{autoload}. It is stored as the function definition of a symbol,
1207 where it serves as a placeholder for the real definition. The autoload
1208 object says that the real definition is found in a file of Lisp code
1209 that should be loaded when necessary. It contains the name of the file,
1210 plus some other information about the real definition.
1212 After the file has been loaded, the symbol should have a new function
1213 definition that is not an autoload object. The new definition is then
1214 called as if it had been there to begin with. From the user's point of
1215 view, the function call works as expected, using the function definition
1218 An autoload object is usually created with the function
1219 @code{autoload}, which stores the object in the function cell of a
1220 symbol. @xref{Autoload}, for more details.
1223 @section Editing Types
1224 @cindex editing types
1226 The types in the previous section are used for general programming
1227 purposes, and most of them are common to most Lisp dialects. Emacs Lisp
1228 provides several additional data types for purposes connected with
1232 * Buffer Type:: The basic object of editing.
1233 * Marker Type:: A position in a buffer.
1234 * Window Type:: Buffers are displayed in windows.
1235 * Frame Type:: Windows subdivide frames.
1236 * Window Configuration Type:: Recording the way a frame is subdivided.
1237 * Frame Configuration Type:: Recording the status of all frames.
1238 * Process Type:: A process running on the underlying OS.
1239 * Stream Type:: Receive or send characters.
1240 * Keymap Type:: What function a keystroke invokes.
1241 * Overlay Type:: How an overlay is represented.
1245 @subsection Buffer Type
1247 A @dfn{buffer} is an object that holds text that can be edited
1248 (@pxref{Buffers}). Most buffers hold the contents of a disk file
1249 (@pxref{Files}) so they can be edited, but some are used for other
1250 purposes. Most buffers are also meant to be seen by the user, and
1251 therefore displayed, at some time, in a window (@pxref{Windows}). But a
1252 buffer need not be displayed in any window.
1254 The contents of a buffer are much like a string, but buffers are not
1255 used like strings in Emacs Lisp, and the available operations are
1256 different. For example, you can insert text efficiently into an
1257 existing buffer, altering the buffer's contents, whereas ``inserting''
1258 text into a string requires concatenating substrings, and the result is
1259 an entirely new string object.
1261 Each buffer has a designated position called @dfn{point}
1262 (@pxref{Positions}). At any time, one buffer is the @dfn{current
1263 buffer}. Most editing commands act on the contents of the current
1264 buffer in the neighborhood of point. Many of the standard Emacs
1265 functions manipulate or test the characters in the current buffer; a
1266 whole chapter in this manual is devoted to describing these functions
1269 Several other data structures are associated with each buffer:
1273 a local syntax table (@pxref{Syntax Tables});
1276 a local keymap (@pxref{Keymaps}); and,
1279 a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
1282 overlays (@pxref{Overlays}).
1285 text properties for the text in the buffer (@pxref{Text Properties}).
1289 The local keymap and variable list contain entries that individually
1290 override global bindings or values. These are used to customize the
1291 behavior of programs in different buffers, without actually changing the
1294 A buffer may be @dfn{indirect}, which means it shares the text
1295 of another buffer, but presents it differently. @xref{Indirect Buffers}.
1297 Buffers have no read syntax. They print in hash notation, showing the
1303 @result{} #<buffer objects.texi>
1308 @subsection Marker Type
1310 A @dfn{marker} denotes a position in a specific buffer. Markers
1311 therefore have two components: one for the buffer, and one for the
1312 position. Changes in the buffer's text automatically relocate the
1313 position value as necessary to ensure that the marker always points
1314 between the same two characters in the buffer.
1316 Markers have no read syntax. They print in hash notation, giving the
1317 current character position and the name of the buffer.
1322 @result{} #<marker at 10779 in objects.texi>
1326 @xref{Markers}, for information on how to test, create, copy, and move
1330 @subsection Window Type
1332 A @dfn{window} describes the portion of the terminal screen that Emacs
1333 uses to display a buffer. Every window has one associated buffer, whose
1334 contents appear in the window. By contrast, a given buffer may appear
1335 in one window, no window, or several windows.
1337 Though many windows may exist simultaneously, at any time one window
1338 is designated the @dfn{selected window}. This is the window where the
1339 cursor is (usually) displayed when Emacs is ready for a command. The
1340 selected window usually displays the current buffer, but this is not
1341 necessarily the case.
1343 Windows are grouped on the screen into frames; each window belongs to
1344 one and only one frame. @xref{Frame Type}.
1346 Windows have no read syntax. They print in hash notation, giving the
1347 window number and the name of the buffer being displayed. The window
1348 numbers exist to identify windows uniquely, since the buffer displayed
1349 in any given window can change frequently.
1354 @result{} #<window 1 on objects.texi>
1358 @xref{Windows}, for a description of the functions that work on windows.
1361 @subsection Frame Type
1363 A @dfn{frame} is a rectangle on the screen that contains one or more
1364 Emacs windows. A frame initially contains a single main window (plus
1365 perhaps a minibuffer window) which you can subdivide vertically or
1366 horizontally into smaller windows.
1368 Frames have no read syntax. They print in hash notation, giving the
1369 frame's title, plus its address in core (useful to identify the frame
1375 @result{} #<frame emacs@@psilocin.gnu.org 0xdac80>
1379 @xref{Frames}, for a description of the functions that work on frames.
1381 @node Window Configuration Type
1382 @subsection Window Configuration Type
1383 @cindex screen layout
1385 A @dfn{window configuration} stores information about the positions,
1386 sizes, and contents of the windows in a frame, so you can recreate the
1387 same arrangement of windows later.
1389 Window configurations do not have a read syntax; their print syntax
1390 looks like @samp{#<window-configuration>}. @xref{Window
1391 Configurations}, for a description of several functions related to
1392 window configurations.
1394 @node Frame Configuration Type
1395 @subsection Frame Configuration Type
1396 @cindex screen layout
1398 A @dfn{frame configuration} stores information about the positions,
1399 sizes, and contents of the windows in all frames. It is actually
1400 a list whose @sc{car} is @code{frame-configuration} and whose
1401 @sc{cdr} is an alist. Each alist element describes one frame,
1402 which appears as the @sc{car} of that element.
1404 @xref{Frame Configurations}, for a description of several functions
1405 related to frame configurations.
1408 @subsection Process Type
1410 The word @dfn{process} usually means a running program. Emacs itself
1411 runs in a process of this sort. However, in Emacs Lisp, a process is a
1412 Lisp object that designates a subprocess created by the Emacs process.
1413 Programs such as shells, GDB, ftp, and compilers, running in
1414 subprocesses of Emacs, extend the capabilities of Emacs.
1416 An Emacs subprocess takes textual input from Emacs and returns textual
1417 output to Emacs for further manipulation. Emacs can also send signals
1420 Process objects have no read syntax. They print in hash notation,
1421 giving the name of the process:
1426 @result{} (#<process shell>)
1430 @xref{Processes}, for information about functions that create, delete,
1431 return information about, send input or signals to, and receive output
1435 @subsection Stream Type
1437 A @dfn{stream} is an object that can be used as a source or sink for
1438 characters---either to supply characters for input or to accept them as
1439 output. Many different types can be used this way: markers, buffers,
1440 strings, and functions. Most often, input streams (character sources)
1441 obtain characters from the keyboard, a buffer, or a file, and output
1442 streams (character sinks) send characters to a buffer, such as a
1443 @file{*Help*} buffer, or to the echo area.
1445 The object @code{nil}, in addition to its other meanings, may be used
1446 as a stream. It stands for the value of the variable
1447 @code{standard-input} or @code{standard-output}. Also, the object
1448 @code{t} as a stream specifies input using the minibuffer
1449 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
1452 Streams have no special printed representation or read syntax, and
1453 print as whatever primitive type they are.
1455 @xref{Read and Print}, for a description of functions
1456 related to streams, including parsing and printing functions.
1459 @subsection Keymap Type
1461 A @dfn{keymap} maps keys typed by the user to commands. This mapping
1462 controls how the user's command input is executed. A keymap is actually
1463 a list whose @sc{car} is the symbol @code{keymap}.
1465 @xref{Keymaps}, for information about creating keymaps, handling prefix
1466 keys, local as well as global keymaps, and changing key bindings.
1469 @subsection Overlay Type
1471 An @dfn{overlay} specifies properties that apply to a part of a
1472 buffer. Each overlay applies to a specified range of the buffer, and
1473 contains a property list (a list whose elements are alternating property
1474 names and values). Overlay properties are used to present parts of the
1475 buffer temporarily in a different display style. Overlays have no read
1476 syntax, and print in hash notation, giving the buffer name and range of
1479 @xref{Overlays}, for how to create and use overlays.
1481 @node Circular Objects
1482 @section Read Syntax for Circular Objects
1483 @cindex circular structure, read syntax
1484 @cindex shared structure, read syntax
1485 @cindex @samp{#@var{n}=} read syntax
1486 @cindex @samp{#@var{n}#} read syntax
1488 In Emacs 21, to represent shared or circular structure within a
1489 complex of Lisp objects, you can use the reader constructs
1490 @samp{#@var{n}=} and @samp{#@var{n}#}.
1492 Use @code{#@var{n}=} before an object to label it for later reference;
1493 subsequently, you can use @code{#@var{n}#} to refer the same object in
1494 another place. Here, @var{n} is some integer. For example, here is how
1495 to make a list in which the first element recurs as the third element:
1502 This differs from ordinary syntax such as this
1509 which would result in a list whose first and third elements
1510 look alike but are not the same Lisp object. This shows the difference:
1514 (setq x '(#1=(a) b #1#)))
1515 (eq (nth 0 x) (nth 2 x))
1517 (setq x '((a) b (a)))
1518 (eq (nth 0 x) (nth 2 x))
1522 You can also use the same syntax to make a circular structure, which
1523 appears as an ``element'' within itself. Here is an example:
1530 This makes a list whose second element is the list itself.
1531 Here's how you can see that it really works:
1535 (setq x '#1=(a #1#)))
1540 The Lisp printer can produce this syntax to record circular and shared
1541 structure in a Lisp object, if you bind the variable @code{print-circle}
1542 to a non-@code{nil} value. @xref{Output Variables}.
1544 @node Type Predicates
1545 @section Type Predicates
1547 @cindex type checking
1548 @kindex wrong-type-argument
1550 The Emacs Lisp interpreter itself does not perform type checking on
1551 the actual arguments passed to functions when they are called. It could
1552 not do so, since function arguments in Lisp do not have declared data
1553 types, as they do in other programming languages. It is therefore up to
1554 the individual function to test whether each actual argument belongs to
1555 a type that the function can use.
1557 All built-in functions do check the types of their actual arguments
1558 when appropriate, and signal a @code{wrong-type-argument} error if an
1559 argument is of the wrong type. For example, here is what happens if you
1560 pass an argument to @code{+} that it cannot handle:
1565 @error{} Wrong type argument: number-or-marker-p, a
1569 @cindex type predicates
1570 @cindex testing types
1571 If you want your program to handle different types differently, you
1572 must do explicit type checking. The most common way to check the type
1573 of an object is to call a @dfn{type predicate} function. Emacs has a
1574 type predicate for each type, as well as some predicates for
1575 combinations of types.
1577 A type predicate function takes one argument; it returns @code{t} if
1578 the argument belongs to the appropriate type, and @code{nil} otherwise.
1579 Following a general Lisp convention for predicate functions, most type
1580 predicates' names end with @samp{p}.
1582 Here is an example which uses the predicates @code{listp} to check for
1583 a list and @code{symbolp} to check for a symbol.
1588 ;; If X is a symbol, put it on LIST.
1589 (setq list (cons x list)))
1591 ;; If X is a list, add its elements to LIST.
1592 (setq list (append x list)))
1594 ;; We handle only symbols and lists.
1595 (error "Invalid argument %s in add-on" x))))
1598 Here is a table of predefined type predicates, in alphabetical order,
1599 with references to further information.
1603 @xref{List-related Predicates, atom}.
1606 @xref{Array Functions, arrayp}.
1609 @xref{Bool-Vectors, bool-vector-p}.
1612 @xref{Buffer Basics, bufferp}.
1614 @item byte-code-function-p
1615 @xref{Byte-Code Type, byte-code-function-p}.
1618 @xref{Case Tables, case-table-p}.
1620 @item char-or-string-p
1621 @xref{Predicates for Strings, char-or-string-p}.
1624 @xref{Char-Tables, char-table-p}.
1627 @xref{Interactive Call, commandp}.
1630 @xref{List-related Predicates, consp}.
1632 @item display-table-p
1633 @xref{Display Tables, display-table-p}.
1636 @xref{Predicates on Numbers, floatp}.
1638 @item frame-configuration-p
1639 @xref{Frame Configurations, frame-configuration-p}.
1642 @xref{Deleting Frames, frame-live-p}.
1645 @xref{Frames, framep}.
1648 @xref{Functions, functionp}.
1650 @item integer-or-marker-p
1651 @xref{Predicates on Markers, integer-or-marker-p}.
1654 @xref{Predicates on Numbers, integerp}.
1657 @xref{Creating Keymaps, keymapp}.
1660 @xref{Constant Variables}.
1663 @xref{List-related Predicates, listp}.
1666 @xref{Predicates on Markers, markerp}.
1669 @xref{Predicates on Numbers, wholenump}.
1672 @xref{List-related Predicates, nlistp}.
1675 @xref{Predicates on Numbers, numberp}.
1677 @item number-or-marker-p
1678 @xref{Predicates on Markers, number-or-marker-p}.
1681 @xref{Overlays, overlayp}.
1684 @xref{Processes, processp}.
1687 @xref{Sequence Functions, sequencep}.
1690 @xref{Predicates for Strings, stringp}.
1693 @xref{Function Cells, subrp}.
1696 @xref{Symbols, symbolp}.
1698 @item syntax-table-p
1699 @xref{Syntax Tables, syntax-table-p}.
1701 @item user-variable-p
1702 @xref{Defining Variables, user-variable-p}.
1705 @xref{Vectors, vectorp}.
1707 @item window-configuration-p
1708 @xref{Window Configurations, window-configuration-p}.
1711 @xref{Deleting Windows, window-live-p}.
1714 @xref{Basic Windows, windowp}.
1717 The most general way to check the type of an object is to call the
1718 function @code{type-of}. Recall that each object belongs to one and
1719 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
1720 Data Types}). But @code{type-of} knows nothing about non-primitive
1721 types. In most cases, it is more convenient to use type predicates than
1724 @defun type-of object
1725 This function returns a symbol naming the primitive type of
1726 @var{object}. The value is one of the symbols @code{symbol},
1727 @code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector},
1728 @code{char-table}, @code{bool-vector}, @code{hash-table}, @code{subr},
1729 @code{compiled-function}, @code{marker}, @code{overlay}, @code{window},
1730 @code{buffer}, @code{frame}, @code{process}, or
1731 @code{window-configuration}.
1738 (type-of '()) ; @r{@code{()} is @code{nil}.}
1745 @node Equality Predicates
1746 @section Equality Predicates
1749 Here we describe two functions that test for equality between any two
1750 objects. Other functions test equality between objects of specific
1751 types, e.g., strings. For these predicates, see the appropriate chapter
1752 describing the data type.
1754 @defun eq object1 object2
1755 This function returns @code{t} if @var{object1} and @var{object2} are
1756 the same object, @code{nil} otherwise. The ``same object'' means that a
1757 change in one will be reflected by the same change in the other.
1759 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
1760 integers with the same value. Also, since symbol names are normally
1761 unique, if the arguments are symbols with the same name, they are
1762 @code{eq}. For other types (e.g., lists, vectors, strings), two
1763 arguments with the same contents or elements are not necessarily
1764 @code{eq} to each other: they are @code{eq} only if they are the same
1784 (eq '(1 (2 (3))) '(1 (2 (3))))
1789 (setq foo '(1 (2 (3))))
1790 @result{} (1 (2 (3)))
1793 (eq foo '(1 (2 (3))))
1798 (eq [(1 2) 3] [(1 2) 3])
1803 (eq (point-marker) (point-marker))
1808 The @code{make-symbol} function returns an uninterned symbol, distinct
1809 from the symbol that is used if you write the name in a Lisp expression.
1810 Distinct symbols with the same name are not @code{eq}. @xref{Creating
1815 (eq (make-symbol "foo") 'foo)
1821 @defun equal object1 object2
1822 This function returns @code{t} if @var{object1} and @var{object2} have
1823 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
1824 arguments are the same object, @code{equal} looks inside nonidentical
1825 arguments to see if their elements or contents are the same. So, if two
1826 objects are @code{eq}, they are @code{equal}, but the converse is not
1841 (equal "asdf" "asdf")
1850 (equal '(1 (2 (3))) '(1 (2 (3))))
1854 (eq '(1 (2 (3))) '(1 (2 (3))))
1859 (equal [(1 2) 3] [(1 2) 3])
1863 (eq [(1 2) 3] [(1 2) 3])
1868 (equal (point-marker) (point-marker))
1873 (eq (point-marker) (point-marker))
1878 Comparison of strings is case-sensitive, but does not take account of
1879 text properties---it compares only the characters in the strings.
1880 A unibyte string never equals a multibyte string unless the
1881 contents are entirely @sc{ascii} (@pxref{Text Representations}).
1885 (equal "asdf" "ASDF")
1890 However, two distinct buffers are never considered @code{equal}, even if
1891 their textual contents are the same.
1894 The test for equality is implemented recursively; for example, given
1895 two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})}
1896 returns @code{t} if and only if both the expressions below return
1900 (equal (car @var{x}) (car @var{y}))
1901 (equal (cdr @var{x}) (cdr @var{y}))
1904 Because of this recursive method, circular lists may therefore cause
1905 infinite recursion (leading to an error).
1908 arch-tag: 9711a66e-4749-4265-9e8c-972d55b67096