2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/objects
6 @node Lisp Data Types, Numbers, Introduction, Top
7 @chapter Lisp Data Types
13 A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
14 programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of
17 Every object belongs to at least one type. Objects of the same type
18 have similar structures and may usually be used in the same contexts.
19 Types can overlap, and objects can belong to two or more types.
20 Consequently, we can ask whether an object belongs to a particular type,
21 but not for ``the'' type of an object.
23 @cindex primitive type
24 A few fundamental object types are built into Emacs. These, from
25 which all other types are constructed, are called @dfn{primitive
26 types}. Each object belongs to one and only one primitive type. These
27 types include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
28 @dfn{string}, @dfn{vector}, @dfn{subr}, @dfn{byte-code function}, and
29 several special types, such as @dfn{buffer}, that are related to
30 editing. (@xref{Editing Types}.)
32 Each primitive type has a corresponding Lisp function that checks
33 whether an object is a member of that type.
35 Note that Lisp is unlike many other languages in that Lisp objects are
36 @dfn{self-typing}: the primitive type of the object is implicit in the
37 object itself. For example, if an object is a vector, nothing can treat
38 it as a number; Lisp knows it is a vector, not a number.
40 In most languages, the programmer must declare the data type of each
41 variable, and the type is known by the compiler but not represented in
42 the data. Such type declarations do not exist in Emacs Lisp. A Lisp
43 variable can have any type of value, and it remembers whatever value
44 you store in it, type and all.
46 This chapter describes the purpose, printed representation, and read
47 syntax of each of the standard types in GNU Emacs Lisp. Details on how
48 to use these types can be found in later chapters.
51 * Printed Representation:: How Lisp objects are represented as text.
52 * Comments:: Comments and their formatting conventions.
53 * Programming Types:: Types found in all Lisp systems.
54 * Editing Types:: Types specific to Emacs.
55 * Type Predicates:: Tests related to types.
56 * Equality Predicates:: Tests of equality between any two objects.
59 @node Printed Representation
60 @comment node-name, next, previous, up
61 @section Printed Representation and Read Syntax
62 @cindex printed representation
65 The @dfn{printed representation} of an object is the format of the
66 output generated by the Lisp printer (the function @code{prin1}) for
67 that object. The @dfn{read syntax} of an object is the format of the
68 input accepted by the Lisp reader (the function @code{read}) for that
69 object. Most objects have more than one possible read syntax. Some
70 types of object have no read syntax; except for these cases, the printed
71 representation of an object is also a read syntax for it.
73 In other languages, an expression is text; it has no other form. In
74 Lisp, an expression is primarily a Lisp object and only secondarily the
75 text that is the object's read syntax. Often there is no need to
76 emphasize this distinction, but you must keep it in the back of your
77 mind, or you will occasionally be very confused.
80 Every type has a printed representation. Some types have no read
81 syntax, since it may not make sense to enter objects of these types
82 directly in a Lisp program. For example, the buffer type does not have
83 a read syntax. Objects of these types are printed in @dfn{hash
84 notation}: the characters @samp{#<} followed by a descriptive string
85 (typically the type name followed by the name of the object), and closed
86 with a matching @samp{>}. Hash notation cannot be read at all, so the
87 Lisp reader signals the error @code{invalid-read-syntax} whenever it
89 @kindex invalid-read-syntax
93 @result{} #<buffer objects.texi>
96 When you evaluate an expression interactively, the Lisp interpreter
97 first reads the textual representation of it, producing a Lisp object,
98 and then evaluates that object (@pxref{Evaluation}). However,
99 evaluation and reading are separate activities. Reading returns the
100 Lisp object represented by the text that is read; the object may or may
101 not be evaluated later. @xref{Input Functions}, for a description of
102 @code{read}, the basic function for reading objects.
105 @comment node-name, next, previous, up
108 @cindex @samp{;} in comment
110 A @dfn{comment} is text that is written in a program only for the sake
111 of humans that read the program, and that has no effect on the meaning
112 of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
113 is not within a string or character constant. The comment continues to
114 the end of line. The Lisp reader discards comments; they do not become
115 part of the Lisp objects which represent the program within the Lisp
118 @xref{Comment Tips}, for conventions for formatting comments.
120 @node Programming Types
121 @section Programming Types
122 @cindex programming types
124 There are two general categories of types in Emacs Lisp: those having
125 to do with Lisp programming, and those having to do with editing. The
126 former exist in many Lisp implementations, in one form or another. The
127 latter are unique to Emacs Lisp.
130 * Integer Type:: Numbers without fractional parts.
131 * Floating Point Type:: Numbers with fractional parts and with a large range.
132 * Character Type:: The representation of letters, numbers and
134 * Symbol Type:: A multi-use object that refers to a function,
135 variable, or property list, and has a unique identity.
136 * Sequence Type:: Both lists and arrays are classified as sequences.
137 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
138 * Array Type:: Arrays include strings and vectors.
139 * String Type:: An (efficient) array of characters.
140 * Vector Type:: One-dimensional arrays.
141 * Function Type:: A piece of executable code you can call from elsewhere.
142 * Macro Type:: A method of expanding an expression into another
143 expression, more fundamental but less pretty.
144 * Primitive Function Type:: A function written in C, callable from Lisp.
145 * Byte-Code Type:: A function written in Lisp, then compiled.
146 * Autoload Type:: A type used for automatically loading seldom-used
151 @subsection Integer Type
153 The range of values for integers in Emacs Lisp is @minus{}134217728 to
154 134217727 (28 bits; i.e.,
168 on most machines. (Some machines may provide a wider range.) It is
169 important to note that the Emacs Lisp arithmetic functions do not check
170 for overflow. Thus @code{(1+ 134217727)} is @minus{}134217728 on most
173 The read syntax for integers is a sequence of (base ten) digits with an
174 optional sign at the beginning and an optional period at the end. The
175 printed representation produced by the Lisp interpreter never has a
176 leading @samp{+} or a final @samp{.}.
180 -1 ; @r{The integer -1.}
181 1 ; @r{The integer 1.}
182 1. ; @r{Also The integer 1.}
183 +1 ; @r{Also the integer 1.}
184 268435457 ; @r{Also the integer 1!}
185 ; @r{ (on a 28-bit implementation)}
189 @xref{Numbers}, for more information.
191 @node Floating Point Type
192 @subsection Floating Point Type
194 Emacs version 19 supports floating point numbers (though there is a
195 compilation option to disable them). The precise range of floating
196 point numbers is machine-specific.
198 The printed representation for floating point numbers requires either
199 a decimal point (with at least one digit following), an exponent, or
200 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
201 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
202 number whose value is 1500. They are all equivalent.
204 @xref{Numbers}, for more information.
207 @subsection Character Type
208 @cindex @sc{ASCII} character codes
210 A @dfn{character} in Emacs Lisp is nothing more than an integer. In
211 other words, characters are represented by their character codes. For
212 example, the character @kbd{A} is represented as the @w{integer 65}.
214 Individual characters are not often used in programs. It is far more
215 common to work with @emph{strings}, which are sequences composed of
216 characters. @xref{String Type}.
218 Characters in strings, buffers, and files are currently limited to the
219 range of 0 to 255---eight bits. If you store a larger integer into a
220 string, buffer or file, it is truncated to that range. Characters that
221 represent keyboard input have a much wider range.
223 @cindex read syntax for characters
224 @cindex printed representation for characters
225 @cindex syntax for characters
226 Since characters are really integers, the printed representation of a
227 character is a decimal number. This is also a possible read syntax for
228 a character, but writing characters that way in Lisp programs is a very
229 bad idea. You should @emph{always} use the special read syntax formats
230 that Emacs Lisp provides for characters. These syntax formats start
231 with a question mark.
233 The usual read syntax for alphanumeric characters is a question mark
234 followed by the character; thus, @samp{?A} for the character
235 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
241 ?Q @result{} 81 ?q @result{} 113
244 You can use the same syntax for punctuation characters, but it is
245 often a good idea to add a @samp{\} so that the Emacs commands for
246 editing Lisp code don't get confused. For example, @samp{?\ } is the
247 way to write the space character. If the character is @samp{\}, you
248 @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
251 @cindex bell character
267 You can express the characters Control-g, backspace, tab, newline,
268 vertical tab, formfeed, return, and escape as @samp{?\a}, @samp{?\b},
269 @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e},
270 respectively. Those values are 7, 8, 9, 10, 11, 12, 13, and 27 in
274 ?\a @result{} 7 ; @r{@kbd{C-g}}
275 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
276 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
277 ?\n @result{} 10 ; @r{newline, @key{LFD}, @kbd{C-j}}
278 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
279 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
280 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
281 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
282 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
285 @cindex escape sequence
286 These sequences which start with backslash are also known as
287 @dfn{escape sequences}, because backslash plays the role of an escape
288 character; this usage has nothing to do with the character @key{ESC}.
290 @cindex control characters
291 Control characters may be represented using yet another read syntax.
292 This consists of a question mark followed by a backslash, caret, and the
293 corresponding non-control character, in either upper or lower case. For
294 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
295 character @kbd{C-i}, the character whose value is 9.
297 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
298 equivalent to @samp{?\^I} and to @samp{?\^i}:
301 ?\^I @result{} 9 ?\C-I @result{} 9
304 For use in strings and buffers, you are limited to the control
305 characters that exist in @sc{ASCII}, but for keyboard input purposes,
306 you can turn any character into a control character with @samp{C-}. The
307 character codes for these non-@sc{ASCII} control characters include the
308 2**22 bit as well as the code for the corresponding non-control
309 character. Ordinary terminals have no way of generating non-@sc{ASCII}
310 control characters, but you can generate them straightforwardly using an
313 You can think of the @key{DEL} character as @kbd{Control-?}:
316 ?\^? @result{} 127 ?\C-? @result{} 127
319 For representing control characters to be found in files or strings,
320 we recommend the @samp{^} syntax; for control characters in keyboard
321 input, we prefer the @samp{C-} syntax. This does not affect the meaning
322 of the program, but may guide the understanding of people who read it.
324 @cindex meta characters
325 A @dfn{meta character} is a character typed with the @key{META}
326 modifier key. The integer that represents such a character has the
327 2**23 bit set (which on most machines makes it a negative number). We
328 use high bits for this and other modifiers to make possible a wide range
329 of basic character codes.
331 In a string, the 2**7 bit indicates a meta character, so the meta
332 characters that can fit in a string have codes in the range from 128 to
333 255, and are the meta versions of the ordinary @sc{ASCII} characters.
334 (In Emacs versions 18 and older, this convention was used for characters
335 outside of strings as well.)
337 The read syntax for meta characters uses @samp{\M-}. For example,
338 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
339 octal character codes (see below), with @samp{\C-}, or with any other
340 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
341 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
342 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
344 The case of an ordinary letter is indicated by its character code as
345 part of @sc{ASCII}, but @sc{ASCII} has no way to represent whether a
346 control character is upper case or lower case. Emacs uses the 2**21 bit
347 to indicate that the shift key was used for typing a control character.
348 This distinction is possible only when you use X terminals or other
349 special terminals; ordinary terminals do not indicate the distinction to
350 the computer in any way.
352 @cindex hyper characters
353 @cindex super characters
354 @cindex alt characters
355 The X Window System defines three other modifier bits that can be set
356 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
357 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus,
358 @samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}. Numerically, the
359 bit values are 2**18 for alt, 2**19 for super and 2**20 for hyper.
361 @cindex @samp{?} in character constant
362 @cindex question mark in character constant
363 @cindex @samp{\} in character constant
364 @cindex backslash in character constant
365 @cindex octal character code
366 Finally, the most general read syntax consists of a question mark
367 followed by a backslash and the character code in octal (up to three
368 octal digits); thus, @samp{?\101} for the character @kbd{A},
369 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
370 character @kbd{C-b}. Although this syntax can represent any @sc{ASCII}
371 character, it is preferred only when the precise octal value is more
372 important than the @sc{ASCII} representation.
376 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
377 ?\101 @result{} 65 ?A @result{} 65
381 A backslash is allowed, and harmless, preceding any character without
382 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
383 There is no reason to add a backslash before most characters. However,
384 you should add a backslash before any of the characters
385 @samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
386 Lisp code. Also add a backslash before whitespace characters such as
387 space, tab, newline and formfeed. However, it is cleaner to use one of
388 the easily readable escape sequences, such as @samp{\t}, instead of an
389 actual whitespace character such as a tab.
392 @subsection Symbol Type
394 A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The symbol
395 name serves as the printed representation of the symbol. In ordinary
396 use, the name is unique---no two symbols have the same name.
398 A symbol can serve as a variable, as a function name, or to hold a
399 property list. Or it may serve only to be distinct from all other Lisp
400 objects, so that its presence in a data structure may be recognized
401 reliably. In a given context, usually only one of these uses is
402 intended. But you can use one symbol in all of these ways,
405 @cindex @samp{\} in symbols
406 @cindex backslash in symbols
407 A symbol name can contain any characters whatever. Most symbol names
408 are written with letters, digits, and the punctuation characters
409 @samp{-+=*/}. Such names require no special punctuation; the characters
410 of the name suffice as long as the name does not look like a number.
411 (If it does, write a @samp{\} at the beginning of the name to force
412 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}} are
413 less often used but also require no special punctuation. Any other
414 characters may be included in a symbol's name by escaping them with a
415 backslash. In contrast to its use in strings, however, a backslash in
416 the name of a symbol simply quotes the single character that follows the
417 backslash. For example, in a string, @samp{\t} represents a tab
418 character; in the name of a symbol, however, @samp{\t} merely quotes the
419 letter @kbd{t}. To have a symbol with a tab character in its name, you
420 must actually use a tab (preceded with a backslash). But it's rare to
423 @cindex CL note---case of letters
425 @b{Common Lisp note:} In Common Lisp, lower case letters are always
426 ``folded'' to upper case, unless they are explicitly escaped. This is
427 in contrast to Emacs Lisp, in which upper case and lower case letters
431 Here are several examples of symbol names. Note that the @samp{+} in
432 the fifth example is escaped to prevent it from being read as a number.
433 This is not necessary in the last example because the rest of the name
434 makes it invalid as a number.
438 foo ; @r{A symbol named @samp{foo}.}
439 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
440 char-to-string ; @r{A symbol named @samp{char-to-string}.}
443 1+ ; @r{A symbol named @samp{1+}}
444 ; @r{(not @samp{+1}, which is an integer).}
447 \+1 ; @r{A symbol named @samp{+1}}
448 ; @r{(not a very readable name).}
451 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
452 @c the @'s in this next line use up three characters, hence the
453 @c apparent misalignment of the comment.
454 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
455 ; @r{These characters need not be escaped.}
460 @subsection Sequence Types
462 A @dfn{sequence} is a Lisp object that represents an ordered set of
463 elements. There are two kinds of sequence in Emacs Lisp, lists and
464 arrays. Thus, an object of type list or of type array is also
465 considered a sequence.
467 Arrays are further subdivided into strings and vectors. Vectors can
468 hold elements of any type, but string elements must be characters in the
469 range from 0 to 255. However, the characters in a string can have text
470 properties like characters in a buffer (@pxref{Text Properties});
471 vectors do not support text properties even when their elements happen
474 Lists, strings and vectors are different, but they have important
475 similarities. For example, all have a length @var{l}, and all have
476 elements which can be indexed from zero to @var{l} minus one. Also,
477 several functions, called sequence functions, accept any kind of
478 sequence. For example, the function @code{elt} can be used to extract
479 an element of a sequence, given its index. @xref{Sequences Arrays
482 It is impossible to read the same sequence twice, since sequences are
483 always created anew upon reading. If you read the read syntax for a
484 sequence twice, you get two sequences with equal contents. There is one
485 exception: the empty list @code{()} always stands for the same object,
489 @subsection Cons Cell and List Types
490 @cindex address field of register
491 @cindex decrement field of register
493 A @dfn{cons cell} is an object comprising two pointers named the
494 @sc{car} and the @sc{cdr}. Each of them can point to any Lisp object.
496 A @dfn{list} is a series of cons cells, linked together so that the
497 @sc{cdr} of each cons cell points either to another cons cell or to the
498 empty list. @xref{Lists}, for functions that work on lists. Because
499 most cons cells are used as part of lists, the phrase @dfn{list
500 structure} has come to refer to any structure made out of cons cells.
502 The names @sc{car} and @sc{cdr} have only historical meaning now. The
503 original Lisp implementation ran on an @w{IBM 704} computer which
504 divided words into two parts, called the ``address'' part and the
505 ``decrement''; @sc{car} was an instruction to extract the contents of
506 the address part of a register, and @sc{cdr} an instruction to extract
507 the contents of the decrement. By contrast, ``cons cells'' are named
508 for the function @code{cons} that creates them, which in turn is named
509 for its purpose, the construction of cells.
512 Because cons cells are so central to Lisp, we also have a word for
513 ``an object which is not a cons cell''. These objects are called
517 The read syntax and printed representation for lists are identical, and
518 consist of a left parenthesis, an arbitrary number of elements, and a
521 Upon reading, each object inside the parentheses becomes an element
522 of the list. That is, a cons cell is made for each element. The
523 @sc{car} of the cons cell points to the element, and its @sc{cdr} points
524 to the next cons cell of the list, which holds the next element in the
525 list. The @sc{cdr} of the last cons cell is set to point to @code{nil}.
527 @cindex box diagrams, for lists
528 @cindex diagrams, boxed, for lists
529 A list can be illustrated by a diagram in which the cons cells are
530 shown as pairs of boxes. (The Lisp reader cannot read such an
531 illustration; unlike the textual notation, which can be understood by
532 both humans and computers, the box illustrations can be understood only
533 by humans.) The following represents the three-element list @code{(rose
538 ___ ___ ___ ___ ___ ___
539 |___|___|--> |___|___|--> |___|___|--> nil
542 --> rose --> violet --> buttercup
546 In this diagram, each box represents a slot that can refer to any Lisp
547 object. Each pair of boxes represents a cons cell. Each arrow is a
548 reference to a Lisp object, either an atom or another cons cell.
550 In this example, the first box, the @sc{car} of the first cons cell,
551 refers to or ``contains'' @code{rose} (a symbol). The second box, the
552 @sc{cdr} of the first cons cell, refers to the next pair of boxes, the
553 second cons cell. The @sc{car} of the second cons cell refers to
554 @code{violet} and the @sc{cdr} refers to the third cons cell. The
555 @sc{cdr} of the third (and last) cons cell refers to @code{nil}.
557 Here is another diagram of the same list, @code{(rose violet
558 buttercup)}, sketched in a different manner:
562 --------------- ---------------- -------------------
563 | car | cdr | | car | cdr | | car | cdr |
564 | rose | o-------->| violet | o-------->| buttercup | nil |
566 --------------- ---------------- -------------------
570 @cindex @samp{(@dots{})} in lists
571 @cindex @code{nil} in lists
573 A list with no elements in it is the @dfn{empty list}; it is identical
574 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
577 Here are examples of lists written in Lisp syntax:
580 (A 2 "A") ; @r{A list of three elements.}
581 () ; @r{A list of no elements (the empty list).}
582 nil ; @r{A list of no elements (the empty list).}
583 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
584 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
585 (A nil) ; @r{Equivalent to the previous.}
586 ((A B C)) ; @r{A list of one element}
587 ; @r{(which is a list of three elements).}
590 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
591 depicted with boxes and arrows:
596 |___|___|--> |___|___|--> nil
604 * Dotted Pair Notation:: An alternative syntax for lists.
605 * Association List Type:: A specially constructed list.
608 @node Dotted Pair Notation
609 @comment node-name, next, previous, up
610 @subsubsection Dotted Pair Notation
611 @cindex dotted pair notation
612 @cindex @samp{.} in lists
614 @dfn{Dotted pair notation} is an alternative syntax for cons cells
615 that represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
616 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
617 the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted
618 pair notation is therefore more general than list syntax. In the dotted
619 pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
620 . nil)))}. For @code{nil}-terminated lists, the two notations produce
621 the same result, but list notation is usually clearer and more
622 convenient when it is applicable. When printing a list, the dotted pair
623 notation is only used if the @sc{cdr} of a cell is not a list.
625 Here's how box notation can illustrate dotted pairs. This example
626 shows the pair @code{(rose . violet)}:
638 Dotted pair notation can be combined with list notation to represent a
639 chain of cons cells with a non-@code{nil} final @sc{cdr}. For example,
640 @code{(rose violet . buttercup)} is equivalent to @code{(rose . (violet
641 . buttercup))}. The object looks like this:
646 |___|___|--> |___|___|--> buttercup
653 These diagrams make it evident why @w{@code{(rose .@: violet .@:
654 buttercup)}} is invalid syntax; it would require a cons cell that has
655 three parts rather than two.
657 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}
663 |___|___|--> |___|___|--> nil
670 Similarly, the three-element list @code{(rose violet buttercup)}
671 is equivalent to @code{(rose . (violet . (buttercup)))}.
677 ___ ___ ___ ___ ___ ___
678 |___|___|--> |___|___|--> |___|___|--> nil
681 --> rose --> violet --> buttercup
686 @node Association List Type
687 @comment node-name, next, previous, up
688 @subsubsection Association List Type
690 An @dfn{association list} or @dfn{alist} is a specially-constructed
691 list whose elements are cons cells. In each element, the @sc{car} is
692 considered a @dfn{key}, and the @sc{cdr} is considered an
693 @dfn{associated value}. (In some cases, the associated value is stored
694 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
695 stacks, since it is easy to add or remove associations at the front of
701 (setq alist-of-colors
702 '((rose . red) (lily . white) (buttercup . yellow)))
706 sets the variable @code{alist-of-colors} to an alist of three elements. In the
707 first element, @code{rose} is the key and @code{red} is the value.
709 @xref{Association Lists}, for a further explanation of alists and for
710 functions that work on alists.
713 @subsection Array Type
715 An @dfn{array} is composed of an arbitrary number of slots for
716 referring to other Lisp objects, arranged in a contiguous block of
717 memory. Accessing any element of an array takes the same amount of
718 time. In contrast, accessing an element of a list requires time
719 proportional to the position of the element in the list. (Elements at
720 the end of a list take longer to access than elements at the beginning
723 Emacs defines two types of array, strings and vectors. A string is an
724 array of characters and a vector is an array of arbitrary objects. Both
725 are one-dimensional. (Most other programming languages support
726 multidimensional arrays, but they are not essential; you can get the
727 same effect with an array of arrays.) Each type of array has its own
728 read syntax; see @ref{String Type}, and @ref{Vector Type}.
730 An array may have any length up to the largest integer; but once
731 created, it has a fixed size. The first element of an array has index
732 zero, the second element has index 1, and so on. This is called
733 @dfn{zero-origin} indexing. For example, an array of four elements has
734 indices 0, 1, 2, @w{and 3}.
736 The array type is contained in the sequence type and contains both the
737 string type and the vector type.
740 @subsection String Type
742 A @dfn{string} is an array of characters. Strings are used for many
743 purposes in Emacs, as can be expected in a text editor; for example, as
744 the names of Lisp symbols, as messages for the user, and to represent
745 text extracted from buffers. Strings in Lisp are constants: evaluation
746 of a string returns the same string.
748 @cindex @samp{"} in strings
749 @cindex double-quote in strings
750 @cindex @samp{\} in strings
751 @cindex backslash in strings
752 The read syntax for strings is a double-quote, an arbitrary number of
753 characters, and another double-quote, @code{"like this"}. The Lisp
754 reader accepts the same formats for reading the characters of a string
755 as it does for reading single characters (without the question mark that
756 begins a character literal). You can enter a nonprinting character such
757 as tab, @kbd{C-a} or @kbd{M-C-A} using the convenient escape sequences,
758 like this: @code{"\t, \C-a, \M-\C-a"}. You can include a double-quote
759 in a string by preceding it with a backslash; thus, @code{"\""} is a
760 string containing just a single double-quote character.
761 (@xref{Character Type}, for a description of the read syntax for
764 If you use the @samp{\M-} syntax to indicate a meta character in a
765 string constant, this sets the 2**7 bit of the character in the string.
766 This is not the same representation that the meta modifier has in a
767 character on its own (not inside a string). @xref{Character Type}.
769 Strings cannot hold characters that have the hyper, super, or alt
770 modifiers; they can hold @sc{ASCII} control characters, but no others.
771 They do not distinguish case in @sc{ASCII} control characters.
773 The printed representation of a string consists of a double-quote, the
774 characters it contains, and another double-quote. However, you must
775 escape any backslash or double-quote characters in the string with a
776 backslash, like this: @code{"this \" is an embedded quote"}.
778 The newline character is not special in the read syntax for strings;
779 if you write a new line between the double-quotes, it becomes a
780 character in the string. But an escaped newline---one that is preceded
781 by @samp{\}---does not become part of the string; i.e., the Lisp reader
782 ignores an escaped newline while reading a string.
783 @cindex newline in strings
786 "It is useful to include newlines
787 in documentation strings,
790 @result{} "It is useful to include newlines
791 in documentation strings,
792 but the newline is ignored if escaped."
795 A string can hold properties of the text it contains, in addition to
796 the characters themselves. This enables programs that copy text between
797 strings and buffers to preserve the properties with no special effort.
798 @xref{Text Properties}. Strings with text properties have a special
799 read and print syntax:
802 #("@var{characters}" @var{property-data}...)
806 where @var{property-data} consists of zero or more elements, in groups
810 @var{beg} @var{end} @var{plist}
814 The elements @var{beg} and @var{end} are integers, and together specify
815 a range of indices in the string; @var{plist} is the property list for
818 @xref{Strings and Characters}, for functions that work on strings.
821 @subsection Vector Type
823 A @dfn{vector} is a one-dimensional array of elements of any type. It
824 takes a constant amount of time to access any element of a vector. (In
825 a list, the access time of an element is proportional to the distance of
826 the element from the beginning of the list.)
828 The printed representation of a vector consists of a left square
829 bracket, the elements, and a right square bracket. This is also the
830 read syntax. Like numbers and strings, vectors are considered constants
834 [1 "two" (three)] ; @r{A vector of three elements.}
835 @result{} [1 "two" (three)]
838 @xref{Vectors}, for functions that work with vectors.
841 @subsection Function Type
843 Just as functions in other programming languages are executable,
844 @dfn{Lisp function} objects are pieces of executable code. However,
845 functions in Lisp are primarily Lisp objects, and only secondarily the
846 text which represents them. These Lisp objects are lambda expressions:
847 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
850 In most programming languages, it is impossible to have a function
851 without a name. In Lisp, a function has no intrinsic name. A lambda
852 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
853 Functions}). A named function in Lisp is actually a symbol with a valid
854 function in its function cell (@pxref{Defining Functions}).
856 Most of the time, functions are called when their names are written in
857 Lisp expressions in Lisp programs. However, you can construct or obtain
858 a function object at run time and then call it with the primitive
859 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
862 @subsection Macro Type
864 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
865 language. It is represented as an object much like a function, but with
866 different parameter-passing semantics. A Lisp macro has the form of a
867 list whose first element is the symbol @code{macro} and whose @sc{cdr}
868 is a Lisp function object, including the @code{lambda} symbol.
870 Lisp macro objects are usually defined with the built-in
871 @code{defmacro} function, but any list that begins with @code{macro} is
872 a macro as far as Emacs is concerned. @xref{Macros}, for an explanation
873 of how to write a macro.
875 @node Primitive Function Type
876 @subsection Primitive Function Type
877 @cindex special forms
879 A @dfn{primitive function} is a function callable from Lisp but
880 written in the C programming language. Primitive functions are also
881 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
882 derived from ``subroutine''.) Most primitive functions evaluate all
883 their arguments when they are called. A primitive function that does
884 not evaluate all its arguments is called a @dfn{special form}
885 (@pxref{Special Forms}).@refill
887 It does not matter to the caller of a function whether the function is
888 primitive. However, this does matter if you try to substitute a
889 function written in Lisp for a primitive of the same name. The reason
890 is that the primitive function may be called directly from C code.
891 Calls to the redefined function from Lisp will use the new definition,
892 but calls from C code may still use the built-in definition.
894 The term @dfn{function} refers to all Emacs functions, whether written
895 in Lisp or C. @xref{Function Type}, for information about the
896 functions written in Lisp.
898 Primitive functions have no read syntax and print in hash notation
899 with the name of the subroutine.
903 (symbol-function 'car) ; @r{Access the function cell}
905 @result{} #<subr car>
906 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
907 @result{} t ; @r{Yes.}
912 @subsection Byte-Code Function Type
914 The byte compiler produces @dfn{byte-code function objects}.
915 Internally, a byte-code function object is much like a vector; however,
916 the evaluator handles this data type specially when it appears as a
917 function to be called. @xref{Byte Compilation}, for information about
920 The printed representation for a byte-code function object is like that
921 for a vector, with an additional @samp{#} before the opening @samp{[}.
924 @subsection Autoload Type
926 An @dfn{autoload object} is a list whose first element is the symbol
927 @code{autoload}. It is stored as the function definition of a symbol as
928 a placeholder for the real definition; it says that the real definition
929 is found in a file of Lisp code that should be loaded when necessary.
930 The autoload object contains the name of the file, plus some other
931 information about the real definition.
933 After the file has been loaded, the symbol should have a new function
934 definition that is not an autoload object. The new definition is then
935 called as if it had been there to begin with. From the user's point of
936 view, the function call works as expected, using the function definition
939 An autoload object is usually created with the function
940 @code{autoload}, which stores the object in the function cell of a
941 symbol. @xref{Autoload}, for more details.
944 @section Editing Types
945 @cindex editing types
947 The types in the previous section are common to many Lisp dialects.
948 Emacs Lisp provides several additional data types for purposes connected
952 * Buffer Type:: The basic object of editing.
953 * Marker Type:: A position in a buffer.
954 * Window Type:: Buffers are displayed in windows.
955 * Frame Type:: Windows subdivide frames.
956 * Window Configuration Type:: Recording the way a frame is subdivided.
957 * Process Type:: A process running on the underlying OS.
958 * Stream Type:: Receive or send characters.
959 * Keymap Type:: What function a keystroke invokes.
960 * Syntax Table Type:: What a character means.
961 * Display Table Type:: How display tables are represented.
962 * Overlay Type:: How an overlay is represented.
966 @subsection Buffer Type
968 A @dfn{buffer} is an object that holds text that can be edited
969 (@pxref{Buffers}). Most buffers hold the contents of a disk file
970 (@pxref{Files}) so they can be edited, but some are used for other
971 purposes. Most buffers are also meant to be seen by the user, and
972 therefore displayed, at some time, in a window (@pxref{Windows}). But a
973 buffer need not be displayed in any window.
975 The contents of a buffer are much like a string, but buffers are not
976 used like strings in Emacs Lisp, and the available operations are
977 different. For example, insertion of text into a buffer is very
978 efficient, whereas ``inserting'' text into a string requires
979 concatenating substrings, and the result is an entirely new string
982 Each buffer has a designated position called @dfn{point}
983 (@pxref{Positions}). At any time, one buffer is the @dfn{current
984 buffer}. Most editing commands act on the contents of the current
985 buffer in the neighborhood of point. Many of the standard Emacs
986 functions manipulate or test the characters in the current buffer; a
987 whole chapter in this manual is devoted to describing these functions
990 Several other data structures are associated with each buffer:
994 a local syntax table (@pxref{Syntax Tables});
997 a local keymap (@pxref{Keymaps}); and,
1000 a local variable binding list (@pxref{Buffer-Local Variables}).
1004 The local keymap and variable list contain entries that individually
1005 override global bindings or values. These are used to customize the
1006 behavior of programs in different buffers, without actually changing the
1009 Buffers have no read syntax. They print in hash notation with the
1015 @result{} #<buffer objects.texi>
1020 @subsection Marker Type
1022 A @dfn{marker} denotes a position in a specific buffer. Markers
1023 therefore have two components: one for the buffer, and one for the
1024 position. Changes in the buffer's text automatically relocate the
1025 position value as necessary to ensure that the marker always points
1026 between the same two characters in the buffer.
1028 Markers have no read syntax. They print in hash notation, giving the
1029 current character position and the name of the buffer.
1034 @result{} #<marker at 10779 in objects.texi>
1038 @xref{Markers}, for information on how to test, create, copy, and move
1042 @subsection Window Type
1044 A @dfn{window} describes the portion of the terminal screen that Emacs
1045 uses to display a buffer. Every window has one associated buffer, whose
1046 contents appear in the window. By contrast, a given buffer may appear
1047 in one window, no window, or several windows.
1049 Though many windows may exist simultaneously, at any time one window
1050 is designated the @dfn{selected window}. This is the window where the
1051 cursor is (usually) displayed when Emacs is ready for a command. The
1052 selected window usually displays the current buffer, but this is not
1053 necessarily the case.
1055 Windows are grouped on the screen into frames; each window belongs to
1056 one and only one frame. @xref{Frame Type}.
1058 Windows have no read syntax. They print in hash notation, giving the
1059 window number and the name of the buffer being displayed. The window
1060 numbers exist to identify windows uniquely, since the buffer displayed
1061 in any given window can change frequently.
1066 @result{} #<window 1 on objects.texi>
1070 @xref{Windows}, for a description of the functions that work on windows.
1073 @subsection Frame Type
1075 A @var{frame} is a rectangle on the screen that contains one or more
1076 Emacs windows. A frame initially contains a single main window (plus
1077 perhaps a minibuffer window) which you can subdivide vertically or
1078 horizontally into smaller windows.
1080 Frames have no read syntax. They print in hash notation, giving the
1081 frame's title, plus its address in core (useful to identify the frame
1087 @result{} #<frame xemacs@@mole.gnu.ai.mit.edu 0xdac80>
1091 @xref{Frames}, for a description of the functions that work on frames.
1093 @node Window Configuration Type
1094 @subsection Window Configuration Type
1095 @cindex screen layout
1097 A @dfn{window configuration} stores information about the positions,
1098 sizes, and contents of the windows in a frame, so you can recreate the
1099 same arrangement of windows later.
1101 Window configurations do not have a read syntax. They print as
1102 @samp{#<window-configuration>}. @xref{Window Configurations}, for a
1103 description of several functions related to window configurations.
1106 @subsection Process Type
1108 The word @dfn{process} usually means a running program. Emacs itself
1109 runs in a process of this sort. However, in Emacs Lisp, a process is a
1110 Lisp object that designates a subprocess created by the Emacs process.
1111 Programs such as shells, GDB, ftp, and compilers, running in
1112 subprocesses of Emacs, extend the capabilities of Emacs.
1114 An Emacs subprocess takes textual input from Emacs and returns textual
1115 output to Emacs for further manipulation. Emacs can also send signals
1118 Process objects have no read syntax. They print in hash notation,
1119 giving the name of the process:
1124 @result{} (#<process shell>)
1128 @xref{Processes}, for information about functions that create, delete,
1129 return information about, send input or signals to, and receive output
1133 @subsection Stream Type
1135 A @dfn{stream} is an object that can be used as a source or sink for
1136 characters---either to supply characters for input or to accept them as
1137 output. Many different types can be used this way: markers, buffers,
1138 strings, and functions. Most often, input streams (character sources)
1139 obtain characters from the keyboard, a buffer, or a file, and output
1140 streams (character sinks) send characters to a buffer, such as a
1141 @file{*Help*} buffer, or to the echo area.
1143 The object @code{nil}, in addition to its other meanings, may be used
1144 as a stream. It stands for the value of the variable
1145 @code{standard-input} or @code{standard-output}. Also, the object
1146 @code{t} as a stream specifies input using the minibuffer
1147 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
1150 Streams have no special printed representation or read syntax, and
1151 print as whatever primitive type they are.
1153 @xref{Read and Print}, for a description of functions
1154 related to streams, including parsing and printing functions.
1157 @subsection Keymap Type
1159 A @dfn{keymap} maps keys typed by the user to commands. This mapping
1160 controls how the user's command input is executed. A keymap is actually
1161 a list whose @sc{car} is the symbol @code{keymap}.
1163 @xref{Keymaps}, for information about creating keymaps, handling prefix
1164 keys, local as well as global keymaps, and changing key bindings.
1166 @node Syntax Table Type
1167 @subsection Syntax Table Type
1169 A @dfn{syntax table} is a vector of 256 integers. Each element of the
1170 vector defines how one character is interpreted when it appears in a
1171 buffer. For example, in C mode (@pxref{Major Modes}), the @samp{+}
1172 character is punctuation, but in Lisp mode it is a valid character in a
1173 symbol. These modes specify different interpretations by changing the
1174 syntax table entry for @samp{+}, at index 43 in the syntax table.
1176 Syntax tables are used only for scanning text in buffers, not for
1177 reading Lisp expressions. The table the Lisp interpreter uses to read
1178 expressions is built into the Emacs source code and cannot be changed;
1179 thus, to change the list delimiters to be @samp{@{} and @samp{@}}
1180 instead of @samp{(} and @samp{)} would be impossible.
1182 @xref{Syntax Tables}, for details about syntax classes and how to make
1183 and modify syntax tables.
1185 @node Display Table Type
1186 @subsection Display Table Type
1188 A @dfn{display table} specifies how to display each character code.
1189 Each buffer and each window can have its own display table. A display
1190 table is actually a vector of length 261. @xref{Display Tables}.
1193 @subsection Overlay Type
1195 An @dfn{overlay} specifies temporary alteration of the display
1196 appearance of a part of a buffer. It contains markers delimiting a
1197 range of the buffer, plus a property list (a list whose elements are
1198 alternating property names and values). Overlays are used to present
1199 parts of the buffer temporarily in a different display style.
1201 @xref{Overlays}, for how to create and use overlays. They have no
1202 read syntax, and print in hash notation, giving the buffer name and
1205 @node Type Predicates
1206 @section Type Predicates
1208 @cindex type checking
1209 @kindex wrong-type-argument
1211 The Emacs Lisp interpreter itself does not perform type checking on
1212 the actual arguments passed to functions when they are called. It could
1213 not do so, since function arguments in Lisp do not have declared data
1214 types, as they do in other programming languages. It is therefore up to
1215 the individual function to test whether each actual argument belongs to
1216 a type that the function can use.
1218 All built-in functions do check the types of their actual arguments
1219 when appropriate, and signal a @code{wrong-type-argument} error if an
1220 argument is of the wrong type. For example, here is what happens if you
1221 pass an argument to @code{+} that it cannot handle:
1226 @error{} Wrong type argument: integer-or-marker-p, a
1230 @cindex type predicates
1231 @cindex testing types
1232 Lisp provides functions, called @dfn{type predicates}, to test whether
1233 an object is a member of a given type. (Following a convention of long
1234 standing, the names of most Emacs Lisp predicates end in @samp{p}.)
1236 Here is a table of predefined type predicates, in alphabetical order,
1237 with references to further information.
1241 @xref{List-related Predicates, atom}.
1244 @xref{Array Functions, arrayp}.
1247 @xref{Buffer Basics, bufferp}.
1249 @item byte-code-function-p
1250 @xref{Byte-Code Type, byte-code-function-p}.
1253 @xref{Case Table, case-table-p}.
1255 @item char-or-string-p
1256 @xref{Predicates for Strings, char-or-string-p}.
1259 @xref{Interactive Call, commandp}.
1262 @xref{List-related Predicates, consp}.
1265 @xref{Predicates on Numbers, floatp}.
1268 @xref{Deleting Frames, frame-live-p}.
1271 @xref{Frames, framep}.
1273 @item integer-or-marker-p
1274 @xref{Predicates on Markers, integer-or-marker-p}.
1277 @xref{Predicates on Numbers, integerp}.
1280 @xref{Creating Keymaps, keymapp}.
1283 @xref{List-related Predicates, listp}.
1286 @xref{Predicates on Markers, markerp}.
1289 @xref{Predicates on Numbers, wholenump}.
1292 @xref{List-related Predicates, nlistp}.
1295 @xref{Predicates on Numbers, numberp}.
1297 @item number-or-marker-p
1298 @xref{Predicates on Markers, number-or-marker-p}.
1301 @xref{Overlays, overlayp}.
1304 @xref{Processes, processp}.
1307 @xref{Sequence Functions, sequencep}.
1310 @xref{Predicates for Strings, stringp}.
1313 @xref{Function Cells, subrp}.
1316 @xref{Symbols, symbolp}.
1318 @item syntax-table-p
1319 @xref{Syntax Tables, syntax-table-p}.
1321 @item user-variable-p
1322 @xref{Defining Variables, user-variable-p}.
1325 @xref{Vectors, vectorp}.
1327 @item window-configuration-p
1328 @xref{Window Configurations, window-configuration-p}.
1331 @xref{Deleting Windows, window-live-p}.
1334 @xref{Basic Windows, windowp}.
1337 @node Equality Predicates
1338 @section Equality Predicates
1341 Here we describe two functions that test for equality between any two
1342 objects. Other functions test equality between objects of specific
1343 types, e.g., strings. For these predicates, see the appropriate chapter
1344 describing the data type.
1346 @defun eq object1 object2
1347 This function returns @code{t} if @var{object1} and @var{object2} are
1348 the same object, @code{nil} otherwise. The ``same object'' means that a
1349 change in one will be reflected by the same change in the other.
1351 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
1352 integers with the same value. Also, since symbol names are normally
1353 unique, if the arguments are symbols with the same name, they are
1354 @code{eq}. For other types (e.g., lists, vectors, strings), two
1355 arguments with the same contents or elements are not necessarily
1356 @code{eq} to each other: they are @code{eq} only if they are the same
1359 (The @code{make-symbol} function returns an uninterned symbol that is
1360 not interned in the standard @code{obarray}. When uninterned symbols
1361 are in use, symbol names are no longer unique. Distinct symbols with
1362 the same name are not @code{eq}. @xref{Creating Symbols}.)
1381 (eq '(1 (2 (3))) '(1 (2 (3))))
1386 (setq foo '(1 (2 (3))))
1387 @result{} (1 (2 (3)))
1390 (eq foo '(1 (2 (3))))
1395 (eq [(1 2) 3] [(1 2) 3])
1400 (eq (point-marker) (point-marker))
1407 @defun equal object1 object2
1408 This function returns @code{t} if @var{object1} and @var{object2} have
1409 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
1410 arguments are the same object, @code{equal} looks inside nonidentical
1411 arguments to see if their elements are the same. So, if two objects are
1412 @code{eq}, they are @code{equal}, but the converse is not always true.
1426 (equal "asdf" "asdf")
1435 (equal '(1 (2 (3))) '(1 (2 (3))))
1439 (eq '(1 (2 (3))) '(1 (2 (3))))
1444 (equal [(1 2) 3] [(1 2) 3])
1448 (eq [(1 2) 3] [(1 2) 3])
1453 (equal (point-marker) (point-marker))
1458 (eq (point-marker) (point-marker))
1463 Comparison of strings uses @code{string=}, and is case-sensitive.
1467 (equal "asdf" "ASDF")
1473 The test for equality is implemented recursively, and circular lists may
1474 therefore cause infinite recursion (leading to an error).