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 Types of Lisp Object, 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 remembers the type of any value
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 * Sequence Type:: Both lists and arrays are classified as sequences.
135 * List Type:: Lists gave Lisp its name (not to mention reputation).
136 * Array Type:: Arrays include strings and vectors.
137 * String Type:: An (efficient) array of characters.
138 * Vector Type:: One-dimensional arrays.
139 * Symbol Type:: A multi-use object that refers to a function,
140 variable, property list, or itself.
141 * Lisp Function Type:: A piece of executable code you can call from elsewhere.
142 * Lisp 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 Integers were the only kind of number in Emacs version 18. The range
154 of values for integers is @minus{}8388608 to 8388607 (24 bits; i.e.,
168 on most machines, but is 25 or 26 bits on some systems. It is important
169 to note that the Emacs Lisp arithmetic functions do not check for
170 overflow. Thus @code{(1+ 8388607)} is @minus{}8388608 on 24-bit
171 implementations.@refill
173 The read syntax for numbers 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 16777217 ; @r{Also the integer 1!}
185 ; @r{ (on a 24-bit or 25-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{\} to prevent Lisp mode from getting
246 confused. For example, @samp{?\ } is the way to write the space
247 character. If the character is @samp{\}, you @emph{must} use a second
248 @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 codes, @samp{\C-}, or any other syntax for a character. Thus, you
340 can write @kbd{M-A} as @samp{?\M-A}, or as @samp{?\M-\101}. Likewise,
341 you can write @kbd{C-M-b} as @samp{?\M-\C-b}, @samp{?\C-\M-b}, or
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 Sequence Types
394 A @dfn{sequence} is a Lisp object that represents an ordered set of
395 elements. There are two kinds of sequence in Emacs Lisp, lists and
396 arrays. Thus, an object of type list or of type array is also
397 considered a sequence.
399 Arrays are further subdivided into strings and vectors. Vectors can
400 hold elements of any type, but string elements must be characters in the
401 range from 0 to 255. However, the characters in a string can have text
402 properties; vectors do not support text properties even when their
403 elements happen to be characters.
405 Lists, strings and vectors are different, but they have important
406 similarities. For example, all have a length @var{l}, and all have
407 elements which can be indexed from zero to @var{l} minus one. Also,
408 several functions, called sequence functions, accept any kind of
409 sequence. For example, the function @code{elt} can be used to extract
410 an element of a sequence, given its index. @xref{Sequences Arrays
413 It is impossible to read the same sequence twice, since sequences are
414 always created anew upon reading. If you read the read syntax for a
415 sequence twice, you get two sequences with equal contents. There is one
416 exception: the empty list @code{()} always stands for the same object,
420 @subsection List Type
421 @cindex address field of register
422 @cindex decrement field of register
424 A @dfn{list} is a series of cons cells, linked together. A @dfn{cons
425 cell} is an object comprising two pointers named the @sc{car} and the
426 @sc{cdr}. Each of them can point to any Lisp object, but when the cons
427 cell is part of a list, the @sc{cdr} points either to another cons cell
428 or to the empty list. @xref{Lists}, for functions that work on lists.
430 The names @sc{car} and @sc{cdr} have only historical meaning now. The
431 original Lisp implementation ran on an @w{IBM 704} computer which
432 divided words into two parts, called the ``address'' part and the
433 ``decrement''; @sc{car} was an instruction to extract the contents of
434 the address part of a register, and @sc{cdr} an instruction to extract
435 the contents of the decrement. By contrast, ``cons cells'' are named
436 for the function @code{cons} that creates them, which in turn is named
437 for its purpose, the construction of cells.
440 Because cons cells are so central to Lisp, we also have a word for
441 ``an object which is not a cons cell''. These objects are called
445 The read syntax and printed representation for lists are identical, and
446 consist of a left parenthesis, an arbitrary number of elements, and a
449 Upon reading, each object inside the parentheses becomes an element
450 of the list. That is, a cons cell is made for each element. The
451 @sc{car} of the cons cell points to the element, and its @sc{cdr} points
452 to the next cons cell which holds the next element in the list. The
453 @sc{cdr} of the last cons cell is set to point to @code{nil}.
455 @cindex box diagrams, for lists
456 @cindex diagrams, boxed, for lists
457 A list can be illustrated by a diagram in which the cons cells are
458 shown as pairs of boxes. (The Lisp reader cannot read such an
459 illustration; unlike the textual notation, which can be understood both
460 humans and computers, the box illustrations can only be understood by
461 humans.) The following represents the three-element list @code{(rose
466 ___ ___ ___ ___ ___ ___
467 |___|___|--> |___|___|--> |___|___|--> nil
470 --> rose --> violet --> buttercup
474 In this diagram, each box represents a slot that can refer to any Lisp
475 object. Each pair of boxes represents a cons cell. Each arrow is a
476 reference to a Lisp object, either an atom or another cons cell.
478 In this example, the first box, the @sc{car} of the first cons cell,
479 refers to or ``contains'' @code{rose} (a symbol). The second box, the
480 @sc{cdr} of the first cons cell, refers to the next pair of boxes, the
481 second cons cell. The @sc{car} of the second cons cell refers to
482 @code{violet} and the @sc{cdr} refers to the third cons cell. The
483 @sc{cdr} of the third (and last) cons cell refers to @code{nil}.
485 Here is another diagram of the same list, @code{(rose violet
486 buttercup)}, sketched in a different manner:
490 --------------- ---------------- -------------------
491 | car | cdr | | car | cdr | | car | cdr |
492 | rose | o-------->| violet | o-------->| buttercup | nil |
494 --------------- ---------------- -------------------
498 @cindex @samp{(@dots{})} in lists
499 @cindex @code{nil} in lists
501 A list with no elements in it is the @dfn{empty list}; it is identical
502 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
505 Here are examples of lists written in Lisp syntax:
508 (A 2 "A") ; @r{A list of three elements.}
509 () ; @r{A list of no elements (the empty list).}
510 nil ; @r{A list of no elements (the empty list).}
511 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
512 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
513 (A nil) ; @r{Equivalent to the previous.}
514 ((A B C)) ; @r{A list of one element}
515 ; @r{(which is a list of three elements).}
518 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
519 depicted with boxes and arrows:
524 |___|___|--> |___|___|--> nil
532 * Dotted Pair Notation:: An alternative syntax for lists.
533 * Association List Type:: A specially constructed list.
536 @node Dotted Pair Notation
537 @comment node-name, next, previous, up
538 @subsubsection Dotted Pair Notation
539 @cindex dotted pair notation
540 @cindex @samp{.} in lists
542 @dfn{Dotted pair notation} is an alternative syntax for cons cells
543 that represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
544 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
545 the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted
546 pair notation is therefore more general than list syntax. In the dotted
547 pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
548 . nil)))}. For @code{nil}-terminated lists, the two notations produce
549 the same result, but list notation is usually clearer and more
550 convenient when it is applicable. When printing a list, the dotted pair
551 notation is only used if the @sc{cdr} of a cell is not a list.
553 Here's how box notation can illustrate dotted pairs. This example
554 shows the pair @code{(rose . violet)}:
566 Dotted pair notation can be combined with list notation to represent a
567 chain of cons cells with a non-@code{nil} final @sc{cdr}. For example,
568 @code{(rose violet . buttercup)} is equivalent to @code{(rose . (violet
569 . buttercup))}. The object looks like this:
574 |___|___|--> |___|___|--> buttercup
581 These diagrams make it evident why @w{@code{(rose .@: violet .@:
582 buttercup)}} is invalid syntax; it would require a cons cell that has
583 three parts rather than two.
585 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}
591 |___|___|--> |___|___|--> nil
598 Similarly, the three-element list @code{(rose violet buttercup)}
599 is equivalent to @code{(rose . (violet . (buttercup)))}.
605 ___ ___ ___ ___ ___ ___
606 |___|___|--> |___|___|--> |___|___|--> nil
609 --> rose --> violet --> buttercup
614 @node Association List Type
615 @comment node-name, next, previous, up
616 @subsubsection Association List Type
618 An @dfn{association list} or @dfn{alist} is a specially-constructed
619 list whose elements are cons cells. In each element, the @sc{car} is
620 considered a @dfn{key}, and the @sc{cdr} is considered an
621 @dfn{associated value}. (In some cases, the associated value is stored
622 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
623 stacks, since it is easy to add or remove associations at the front of
629 (setq alist-of-colors
630 '((rose . red) (lily . white) (buttercup . yellow)))
634 sets the variable @code{alist-of-colors} to an alist of three elements. In the
635 first element, @code{rose} is the key and @code{red} is the value.
637 @xref{Association Lists}, for a further explanation of alists and for
638 functions that work on alists.
641 @subsection Array Type
643 An @dfn{array} is composed of an arbitrary number of slots for
644 referring to other Lisp objects, arranged in a contiguous block of
645 memory. Accessing any element of an array takes a the same amount of
646 time. In contrast, accessing an element of a list requires time
647 proportional to the position of the element in the list. (Elements at
648 the end of a list take longer to access than elements at the beginning
651 Emacs defines two types of array, strings and vectors. A string is an
652 array of characters and a vector is an array of arbitrary objects. Both
653 are one-dimensional. (Most other programming languages support
654 multidimensional arrays, but they are not essential; you can get the
655 same effect with an array of arrays.) Each type of array has its own
656 read syntax; see @ref{String Type}, and @ref{Vector Type}.
658 An array may have any length up to the largest integer; but once
659 created, it has a fixed size. The first element of an array has index
660 zero, the second element has index 1, and so on. This is called
661 @dfn{zero-origin} indexing. For example, an array of four elements has
662 indices 0, 1, 2, @w{and 3}.
664 The array type is contained in the sequence type and contains both the
665 string type and the vector type.
668 @subsection String Type
670 A @dfn{string} is an array of characters. Strings are used for many
671 purposes in Emacs, as can be expected in a text editor; for example, as
672 the names of Lisp symbols, as messages for the user, and to represent
673 text extracted from buffers. Strings in Lisp are constants: evaluation
674 of a string returns the same string.
676 @cindex @samp{"} in strings
677 @cindex double-quote in strings
678 @cindex @samp{\} in strings
679 @cindex backslash in strings
680 The read syntax for strings is a double-quote, an arbitrary number of
681 characters, and another double-quote, @code{"like this"}. The Lisp
682 reader accepts the same formats for reading the characters of a string
683 as it does for reading single characters (without the question mark that
684 begins a character literal). You can enter a nonprinting character such
685 as tab, @kbd{C-a} or @kbd{M-C-A} using the convenient escape sequences,
686 like this: @code{"\t, \C-a, \M-\C-a"}. You can include a double-quote
687 in a string by preceding it with a backslash; thus, @code{"\""} is a
688 string containing just a single double-quote character.
689 (@xref{Character Type}, for a description of the read syntax for
692 If you use the @samp{\M-} syntax to indicate a meta character in a
693 string constant, this sets the 2**7 bit of the character in the string.
694 This is not the same representation that the meta modifier has in a
695 character on its own (not inside a string). @xref{Character Type}.
697 Strings cannot hold characters that have the hyper, super or alt
698 modifiers; they can hold @sc{ASCII} control characters, but no others.
699 They do not distinguish case in @sc{ASCII} control characters.
701 In contrast with the C programming language, Emacs Lisp allows
702 newlines in string literals. But an escaped newline---one that is
703 preceded by @samp{\}---does not become part of the string; i.e., the
704 Lisp reader ignores an escaped newline in a string literal.
705 @cindex newline in strings
708 "It is useful to include newlines
709 in documentation strings,
712 @result{} "It is useful to include newlines
713 in documentation strings,
714 but the newline is ignored if escaped."
717 The printed representation of a string consists of a double-quote, the
718 characters it contains, and another double-quote. However, any
719 backslash or double-quote characters in the string are preceded with a
720 backslash like this: @code{"this \" is an embedded quote"}.
722 A string can hold properties of the text it contains, in addition to
723 the characters themselves. This enables programs that copy text between
724 strings and buffers to preserve the properties with no special effort.
725 @xref{Text Properties}. Strings with text properties have a special
726 read and print syntax:
729 #("@var{characters}" @var{property-data}...)
733 where @var{property-data} consists of zero or more elements, in groups
737 @var{beg} @var{end} @var{plist}
741 The elements @var{beg} and @var{end} are integers, and together specify
742 a range of indices in the string; @var{plist} is the property list for
745 @xref{Strings and Characters}, for functions that work on strings.
748 @subsection Vector Type
750 A @dfn{vector} is a one-dimensional array of elements of any type. It
751 takes a constant amount of time to access any element of a vector. (In
752 a list, the access time of an element is proportional to the distance of
753 the element from the beginning of the list.)
755 The printed representation of a vector consists of a left square
756 bracket, the elements, and a right square bracket. This is also the
757 read syntax. Like numbers and strings, vectors are considered constants
761 [1 "two" (three)] ; @r{A vector of three elements.}
762 @result{} [1 "two" (three)]
765 @xref{Vectors}, for functions that work with vectors.
768 @subsection Symbol Type
770 A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The symbol
771 name serves as the printed representation of the symbol. In ordinary
772 use, the name is unique---no two symbols have the same name.
774 A symbol can serve as a variable, as a function name, or to hold a
775 property list. Or it may serve only to be distinct from all other Lisp
776 objects, so that its presence in a data structure may be recognized
777 reliably. In a given context, usually only one of these uses is
778 intended. But you can use one symbol in all of these ways,
781 @cindex @samp{\} in symbols
782 @cindex backslash in symbols
783 A symbol name can contain any characters whatever. Most symbol names
784 are written with letters, digits, and the punctuation characters
785 @samp{-+=*/}. Such names require no special punctuation; the characters
786 of the name suffice as long as the name does not look like a number.
787 (If it does, write a @samp{\} at the beginning of the name to force
788 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}} are
789 less often used but also require no special punctuation. Any other
790 characters may be included in a symbol's name by escaping them with a
791 backslash. In contrast to its use in strings, however, a backslash in
792 the name of a symbol quotes the single character that follows the
793 backslash, without conversion. For example, in a string, @samp{\t}
794 represents a tab character; in the name of a symbol, however, @samp{\t}
795 merely quotes the letter @kbd{t}. To have a symbol with a tab character
796 in its name, you must actually use a tab (preceded with a backslash).
797 But it's rare to do such a thing.
799 @cindex CL note---case of letters
801 @b{Common Lisp note:} in Common Lisp, lower case letters are always
802 ``folded'' to upper case, unless they are explicitly escaped. This is
803 in contrast to Emacs Lisp, in which upper case and lower case letters
807 Here are several examples of symbol names. Note that the @samp{+} in
808 the fifth example is escaped to prevent it from being read as a number.
809 This is not necessary in the last example because the rest of the name
810 makes it invalid as a number.
814 foo ; @r{A symbol named @samp{foo}.}
815 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
816 char-to-string ; @r{A symbol named @samp{char-to-string}.}
819 1+ ; @r{A symbol named @samp{1+}}
820 ; @r{(not @samp{+1}, which is an integer).}
823 \+1 ; @r{A symbol named @samp{+1}}
824 ; @r{(not a very readable name).}
827 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
828 @c the @'s in this next line use up three characters, hence the
829 @c apparent misalignment of the comment.
830 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
831 ; @r{These characters need not be escaped.}
835 @node Lisp Function Type
836 @subsection Lisp Function Type
838 Just as functions in other programming languages are executable,
839 @dfn{Lisp function} objects are pieces of executable code. However,
840 functions in Lisp are primarily Lisp objects, and only secondarily the
841 text which represents them. These Lisp objects are lambda expressions:
842 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
845 In most programming languages, it is impossible to have a function
846 without a name. In Lisp, a function has no intrinsic name. A lambda
847 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
848 Functions}). A named function in Lisp is actually a symbol with a valid
849 function in its function cell (@pxref{Defining Functions}).
851 Most of the time, functions are called when their names are written in
852 Lisp expressions in Lisp programs. However, you can construct or obtain
853 a function object at run time and then call it with the primitive
854 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
856 @node Lisp Macro Type
857 @subsection Lisp Macro Type
859 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
860 language. It is represented as an object much like a function, but with
861 different parameter-passing semantics. A Lisp macro has the form of a
862 list whose first element is the symbol @code{macro} and whose @sc{cdr}
863 is a Lisp function object, including the @code{lambda} symbol.
865 Lisp macro objects are usually defined with the built-in
866 @code{defmacro} function, but any list that begins with @code{macro} is
867 a macro as far as Emacs is concerned. @xref{Macros}, for an explanation
868 of how to write a macro.
870 @node Primitive Function Type
871 @subsection Primitive Function Type
872 @cindex special forms
874 A @dfn{primitive function} is a function callable from Lisp but
875 written in the C programming language. Primitive functions are also
876 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
877 derived from ``subroutine''.) Most primitive functions evaluate all
878 their arguments when they are called. A primitive function that does
879 not evaluate all its arguments is called a @dfn{special form}
880 (@pxref{Special Forms}).@refill
882 It does not matter to the caller of a function whether the function is
883 primitive. However, this does matter if you try to substitute a
884 function written in Lisp for a primitive of the same name. The reason
885 is that the primitive function may be called directly from C code.
886 Calls to the redefined function from Lisp will use the new definition,
887 but calls from C code may still use the built-in definition.
889 The term @dfn{function} refers to all Emacs functions, whether written
890 in Lisp or C. @xref{Lisp Function Type}, for information about the
891 functions written in Lisp.@refill
893 Primitive functions have no read syntax and print in hash notation
894 with the name of the subroutine.
898 (symbol-function 'car) ; @r{Access the function cell}
900 @result{} #<subr car>
901 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
902 @result{} t ; @r{Yes.}
907 @subsection Byte-Code Function Type
909 The byte compiler produces @dfn{byte-code function objects}.
910 Internally, a byte-code function object is much like a vector; however,
911 the evaluator handles this data type specially when it appears as a
912 function to be called. @xref{Byte Compilation}, for information about
915 The printed representation for a byte-code function object is like that
916 for a vector, with an additional @samp{#} before the opening @samp{[}.
919 @subsection Autoload Type
921 An @dfn{autoload object} is a list whose first element is the symbol
922 @code{autoload}. It is stored as the function definition of a symbol as
923 a placeholder for the real definition; it says that the real definition
924 is found in a file of Lisp code that should be loaded when necessary.
925 The autoload object contains the name of the file, plus some other
926 information about the real definition.
928 After the file has been loaded, the symbol should have a new function
929 definition that is not an autoload object. The new definition is then
930 called as if it had been there to begin with. From the user's point of
931 view, the function call works as expected, using the function definition
934 An autoload object is usually created with the function
935 @code{autoload}, which stores the object in the function cell of a
936 symbol. @xref{Autoload}, for more details.
939 @section Editing Types
940 @cindex editing types
942 The types in the previous section are common to many Lisp dialects.
943 Emacs Lisp provides several additional data types for purposes connected
947 * Buffer Type:: The basic object of editing.
948 * Marker Type:: A position in a buffer.
949 * Window Type:: Buffers are displayed in windows.
950 * Frame Type:: Windows subdivide frames.
951 * Window Configuration Type:: Recording the way a frame is subdivided.
952 * Process Type:: A process running on the underlying OS.
953 * Stream Type:: Receive or send characters.
954 * Keymap Type:: What function a keystroke invokes.
955 * Syntax Table Type:: What a character means.
956 * Display Table Type:: How display tables are represented.
957 * Overlay Type:: How an overlay is represented.
961 @subsection Buffer Type
963 A @dfn{buffer} is an object that holds text that can be edited
964 (@pxref{Buffers}). Most buffers hold the contents of a disk file
965 (@pxref{Files}) so they can be edited, but some are used for other
966 purposes. Most buffers are also meant to be seen by the user, and
967 therefore displayed, at some time, in a window (@pxref{Windows}). But a
968 buffer need not be displayed in any window.
970 The contents of a buffer are much like a string, but buffers are not
971 used like strings in Emacs Lisp, and the available operations are
972 different. For example, insertion of text into a buffer is very
973 efficient, whereas ``inserting'' text into a string requires
974 concatenating substrings, and the result is an entirely new string
977 Each buffer has a designated position called @dfn{point}
978 (@pxref{Positions}). At any time, one buffer is the @dfn{current
979 buffer}. Most editing commands act on the contents of the current
980 buffer in the neighborhood of point. Many other functions manipulate or
981 test the characters in the current buffer; a whole chapter in this
982 manual is devoted to describing these functions (@pxref{Text}).
984 Several other data structures are associated with each buffer:
988 a local syntax table (@pxref{Syntax Tables});
991 a local keymap (@pxref{Keymaps}); and,
994 a local variable binding list (@pxref{Buffer-Local Variables}).
998 The local keymap and variable list contain entries which individually
999 override global bindings or values. These are used to customize the
1000 behavior of programs in different buffers, without actually changing the
1003 Buffers have no read syntax. They print in hash notation with the
1009 @result{} #<buffer objects.texi>
1014 @subsection Marker Type
1016 A @dfn{marker} denotes a position in a specific buffer. Markers
1017 therefore have two components: one for the buffer, and one for the
1018 position. Changes in the buffer's text automatically relocate the
1019 position value as necessary to ensure that the marker always points
1020 between the same two characters in the buffer.
1022 Markers have no read syntax. They print in hash notation, giving the
1023 current character position and the name of the buffer.
1028 @result{} #<marker at 10779 in objects.texi>
1032 @xref{Markers}, for information on how to test, create, copy, and move
1036 @subsection Window Type
1038 A @dfn{window} describes the portion of the terminal screen that Emacs
1039 uses to display a buffer. Every window has one associated buffer, whose
1040 contents appear in the window. By contrast, a given buffer may appear
1041 in one window, no window, or several windows.
1043 Though many windows may exist simultaneously, at any time one window
1044 is designated the @dfn{selected window}. This is the window where the
1045 cursor is (usually) displayed when Emacs is ready for a command. The
1046 selected window usually displays the current buffer, but this is not
1047 necessarily the case.
1049 Windows are grouped on the screen into frames; each window belongs to
1050 one and only one frame. @xref{Frame Type}.
1052 Windows have no read syntax. They print in hash notation, giving the
1053 window number and the name of the buffer being displayed. The window
1054 numbers exist to identify windows uniquely, since the buffer displayed
1055 in any given window can change frequently.
1060 @result{} #<window 1 on objects.texi>
1064 @xref{Windows}, for a description of the functions that work on windows.
1067 @subsection Frame Type
1069 A @var{frame} is a rectangle on the screen that contains one or more
1070 Emacs windows. A frame initially contains a single main window (plus
1071 perhaps a minibuffer window) which you can subdivide vertically or
1072 horizontally into smaller windows.
1074 Frames have no read syntax. They print in hash notation, giving the
1075 frame's title, plus its address in core (useful to identify the frame
1081 @result{} #<frame xemacs@@mole.gnu.ai.mit.edu 0xdac80>
1085 @xref{Frames}, for a description of the functions that work on frames.
1087 @node Window Configuration Type
1088 @subsection Window Configuration Type
1089 @cindex screen layout
1091 A @dfn{window configuration} stores information about the positions,
1092 sizes, and contents of the windows in a frame, so you can recreate the
1093 same arrangement of windows later.
1095 Window configurations do not have a read syntax. They print as
1096 @samp{#<window-configuration>}. @xref{Window Configurations}, for a
1097 description of several functions related to window configurations.
1100 @subsection Process Type
1102 The word @dfn{process} usually means a running program. Emacs itself
1103 runs in a process of this sort. However, in Emacs Lisp, a process is a
1104 Lisp object that designates a subprocess created by the Emacs process.
1105 Programs such as shells, GDB, ftp, and compilers, running in
1106 subprocesses of Emacs, extend the capabilities of Emacs.
1108 An Emacs subprocess takes textual input from Emacs and returns textual
1109 output to Emacs for further manipulation. Emacs can also send signals
1112 Process objects have no read syntax. They print in hash notation,
1113 giving the name of the process:
1118 @result{} (#<process shell>)
1122 @xref{Processes}, for information about functions that create, delete,
1123 return information about, send input or signals to, and receive output
1127 @subsection Stream Type
1129 A @dfn{stream} is an object that can be used as a source or sink for
1130 characters---either to supply characters for input or to accept them as
1131 output. Many different types can be used this way: markers, buffers,
1132 strings, and functions. Most often, input streams (character sources)
1133 obtain characters from the keyboard, a buffer, or a file, and output
1134 streams (character sinks) send characters to a buffer, such as a
1135 @file{*Help*} buffer, or to the echo area.
1137 The object @code{nil}, in addition to its other meanings, may be used
1138 as a stream. It stands for the value of the variable
1139 @code{standard-input} or @code{standard-output}. Also, the object
1140 @code{t} as a stream specifies input using the minibuffer
1141 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
1144 Streams have no special printed representation or read syntax, and
1145 print as whatever primitive type they are.
1147 @xref{Streams}, for a description of various functions related to
1148 streams, including various parsing and printing functions.
1151 @subsection Keymap Type
1153 A @dfn{keymap} maps keys typed by the user to commands. This mapping
1154 controls how the user's command input is executed. A keymap is actually
1155 a list whose @sc{car} is the symbol @code{keymap}.
1157 @xref{Keymaps}, for information about creating keymaps, handling prefix
1158 keys, local as well as global keymaps, and changing key bindings.
1160 @node Syntax Table Type
1161 @subsection Syntax Table Type
1163 A @dfn{syntax table} is a vector of 256 integers. Each element of the
1164 vector defines how one character is interpreted when it appears in a
1165 buffer. For example, in C mode (@pxref{Major Modes}), the @samp{+}
1166 character is punctuation, but in Lisp mode it is a valid character in a
1167 symbol. These modes specify different interpretations by changing the
1168 syntax table entry for @samp{+}, at index 43 in the syntax table.
1170 Syntax tables are only used for scanning text in buffers, not for
1171 reading Lisp expressions. The table the Lisp interpreter uses to read
1172 expressions is built into the Emacs source code and cannot be changed;
1173 thus, to change the list delimiters to be @samp{@{} and @samp{@}}
1174 instead of @samp{(} and @samp{)} would be impossible.
1176 @xref{Syntax Tables}, for details about syntax classes and how to make
1177 and modify syntax tables.
1179 @node Display Table Type
1180 @subsection Display Table Type
1182 A @dfn{display table} specifies how to display each character code.
1183 Each buffer and each window can have its own display table. A display
1184 table is actually a vector of length 261. @xref{Display Tables}.
1187 @subsection Overlay Type
1189 An @dfn{overlay} specifies temporary alteration of the display
1190 appearance of a part of a buffer. It contains markers delimiting a
1191 range of the buffer, plus a property list (a list whose elements are
1192 alternating property names and values). Overlays are used to present
1193 parts of the buffer temporarily in a different display style.
1195 @xref{Overlays}, for how to create and use overlays. They have no
1196 read syntax, and print in hash notation, giving the buffer name and
1199 @node Type Predicates
1200 @section Type Predicates
1202 @cindex type checking
1203 @kindex wrong-type-argument
1205 The Emacs Lisp interpreter itself does not perform type checking on
1206 the actual arguments passed to functions when they are called. It could
1207 not do so, since function arguments in Lisp do not have declared data
1208 types, as they do in other programming languages. It is therefore up to
1209 the individual function to test whether each actual argument belongs to
1210 a type that the function can use.
1212 All built-in functions do check the types of their actual arguments
1213 when appropriate, and signal a @code{wrong-type-argument} error if an
1214 argument is of the wrong type. For example, here is what happens if you
1215 pass an argument to @code{+} which it cannot handle:
1220 @error{} Wrong type argument: integer-or-marker-p, a
1224 @cindex type predicates
1225 @cindex testing types
1226 Lisp provides functions, called @dfn{type predicates}, to test whether
1227 an object is a member of a given type. (Following a convention of long
1228 standing, the names of most Emacs Lisp predicates end in @samp{p}.)
1230 Here is a table of predefined type predicates, in alphabetical order,
1231 with references to further information.
1235 @xref{List-related Predicates, atom}.
1238 @xref{Array Functions, arrayp}.
1241 @xref{Buffer Basics, bufferp}.
1243 @item byte-code-function-p
1244 @xref{Byte-Code Type, byte-code-function-p}.
1247 @xref{Case Table, case-table-p}.
1249 @item char-or-string-p
1250 @xref{Predicates for Strings, char-or-string-p}.
1253 @xref{Interactive Call, commandp}.
1256 @xref{List-related Predicates, consp}.
1259 @xref{Predicates on Numbers, floatp}.
1262 @xref{Deleting Frames, frame-live-p}.
1265 @xref{Frames, framep}.
1267 @item integer-or-marker-p
1268 @xref{Predicates on Markers, integer-or-marker-p}.
1271 @xref{Predicates on Numbers, integerp}.
1274 @xref{Creating Keymaps, keymapp}.
1277 @xref{List-related Predicates, listp}.
1280 @xref{Predicates on Markers, markerp}.
1283 @xref{Predicates on Numbers, natnump}.
1286 @xref{List-related Predicates, nlistp}.
1289 @xref{Predicates on Numbers, numberp}.
1291 @item number-or-marker-p
1292 @xref{Predicates on Markers, number-or-marker-p}.
1295 @xref{Overlays, overlayp}.
1298 @xref{Processes, processp}.
1301 @xref{Sequence Functions, sequencep}.
1304 @xref{Predicates for Strings, stringp}.
1307 @xref{Function Cells, subrp}.
1310 @xref{Symbols, symbolp}.
1312 @item syntax-table-p
1313 @xref{Syntax Tables, syntax-table-p}.
1315 @item user-variable-p
1316 @xref{Defining Variables, user-variable-p}.
1319 @xref{Vectors, vectorp}.
1321 @item window-configuration-p
1322 @xref{Window Configurations, window-configuration-p}.
1325 @xref{Deleting Windows, window-live-p}.
1328 @xref{Basic Windows, windowp}.
1331 @node Equality Predicates
1332 @section Equality Predicates
1335 Here we describe two functions that test for equality between any two
1336 objects. Other functions test equality between objects of specific
1337 types, e.g., strings. See the appropriate chapter describing the data
1338 type for these predicates.
1340 @defun eq object1 object2
1341 This function returns @code{t} if @var{object1} and @var{object2} are
1342 the same object, @code{nil} otherwise. The ``same object'' means that a
1343 change in one will be reflected by the same change in the other.
1345 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
1346 integers with the same value. Also, since symbol names are normally
1347 unique, if the arguments are symbols with the same name, they are
1348 @code{eq}. For other types (e.g., lists, vectors, strings), two
1349 arguments with the same contents or elements are not necessarily
1350 @code{eq} to each other: they are @code{eq} only if they are the same
1353 (The @code{make-symbol} function returns an uninterned symbol that is
1354 not interned in the standard @code{obarray}. When uninterned symbols
1355 are in use, symbol names are no longer unique. Distinct symbols with
1356 the same name are not @code{eq}. @xref{Creating Symbols}.)
1375 (eq '(1 (2 (3))) '(1 (2 (3))))
1380 (setq foo '(1 (2 (3))))
1381 @result{} (1 (2 (3)))
1384 (eq foo '(1 (2 (3))))
1389 (eq [(1 2) 3] [(1 2) 3])
1394 (eq (point-marker) (point-marker))
1401 @defun equal object1 object2
1402 This function returns @code{t} if @var{object1} and @var{object2} have
1403 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
1404 arguments are the same object, @code{equal} looks inside nonidentical
1405 arguments to see if their elements are the same. So, if two objects are
1406 @code{eq}, they are @code{equal}, but the converse is not always true.
1420 (equal "asdf" "asdf")
1429 (equal '(1 (2 (3))) '(1 (2 (3))))
1433 (eq '(1 (2 (3))) '(1 (2 (3))))
1438 (equal [(1 2) 3] [(1 2) 3])
1442 (eq [(1 2) 3] [(1 2) 3])
1447 (equal (point-marker) (point-marker))
1452 (eq (point-marker) (point-marker))
1457 Comparison of strings uses @code{string=}, and is case-sensitive.
1461 (equal "asdf" "ASDF")
1467 The test for equality is implemented recursively, and circular lists may
1468 therefore cause infinite recursion (leading to an error).