*** empty log message ***
[emacs.git] / lispref / objects.texi
blob8904bfba4838672427927254d73e873196ccb64e
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4 @c   Free Software Foundation, Inc. 
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/objects
7 @node Lisp Data Types, Numbers, Introduction, Top
8 @chapter Lisp Data Types
9 @cindex object
10 @cindex Lisp object
11 @cindex type
12 @cindex data type
14   A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
15 programs.  For our purposes, a @dfn{type} or @dfn{data type} is a set of
16 possible objects.
18   Every object belongs to at least one type.  Objects of the same type
19 have similar structures and may usually be used in the same contexts.
20 Types can overlap, and objects can belong to two or more types.
21 Consequently, we can ask whether an object belongs to a particular type,
22 but not for ``the'' type of an object.
24 @cindex primitive type
25   A few fundamental object types are built into Emacs.  These, from
26 which all other types are constructed, are called @dfn{primitive types}.
27 Each object belongs to one and only one primitive type.  These types
28 include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
29 @dfn{string}, @dfn{vector}, @dfn{hash-table}, @dfn{subr}, and
30 @dfn{byte-code function}, plus several special types, such as
31 @dfn{buffer}, that are related to editing.  (@xref{Editing Types}.)
33   Each primitive type has a corresponding Lisp function that checks
34 whether an object is a member of that type.
36   Note that Lisp is unlike many other languages in that Lisp objects are
37 @dfn{self-typing}: the primitive type of the object is implicit in the
38 object itself.  For example, if an object is a vector, nothing can treat
39 it as a number; Lisp knows it is a vector, not a number.
41   In most languages, the programmer must declare the data type of each
42 variable, and the type is known by the compiler but not represented in
43 the data.  Such type declarations do not exist in Emacs Lisp.  A Lisp
44 variable can have any type of value, and it remembers whatever value
45 you store in it, type and all.
47   This chapter describes the purpose, printed representation, and read
48 syntax of each of the standard types in GNU Emacs Lisp.  Details on how
49 to use these types can be found in later chapters.
51 @menu
52 * Printed Representation::      How Lisp objects are represented as text.
53 * Comments::                    Comments and their formatting conventions.
54 * Programming Types::           Types found in all Lisp systems.
55 * Editing Types::               Types specific to Emacs.
56 * Circular Objects::            Read syntax for circular structure.
57 * Type Predicates::             Tests related to types.
58 * Equality Predicates::         Tests of equality between any two objects.
59 @end menu
61 @node Printed Representation
62 @comment  node-name,  next,  previous,  up
63 @section Printed Representation and Read Syntax
64 @cindex printed representation
65 @cindex read syntax
67   The @dfn{printed representation} of an object is the format of the
68 output generated by the Lisp printer (the function @code{prin1}) for
69 that object.  The @dfn{read syntax} of an object is the format of the
70 input accepted by the Lisp reader (the function @code{read}) for that
71 object.  @xref{Read and Print}.
73   Most objects have more than one possible read syntax.  Some types of
74 object have no read syntax, since it may not make sense to enter objects
75 of these types directly in a Lisp program.  Except for these cases, the
76 printed representation of an object is also a read syntax for it.
78   In other languages, an expression is text; it has no other form.  In
79 Lisp, an expression is primarily a Lisp object and only secondarily the
80 text that is the object's read syntax.  Often there is no need to
81 emphasize this distinction, but you must keep it in the back of your
82 mind, or you will occasionally be very confused.
84 @cindex hash notation
85   Every type has a printed representation.  Some types have no read
86 syntax---for example, the buffer type has none.  Objects of these types
87 are printed in @dfn{hash notation}: the characters @samp{#<} followed by
88 a descriptive string (typically the type name followed by the name of
89 the object), and closed with a matching @samp{>}.  Hash notation cannot
90 be read at all, so the Lisp reader signals the error
91 @code{invalid-read-syntax} whenever it encounters @samp{#<}.
92 @kindex invalid-read-syntax
94 @example
95 (current-buffer)
96      @result{} #<buffer objects.texi>
97 @end example
99   When you evaluate an expression interactively, the Lisp interpreter
100 first reads the textual representation of it, producing a Lisp object,
101 and then evaluates that object (@pxref{Evaluation}).  However,
102 evaluation and reading are separate activities.  Reading returns the
103 Lisp object represented by the text that is read; the object may or may
104 not be evaluated later.  @xref{Input Functions}, for a description of
105 @code{read}, the basic function for reading objects.
107 @node Comments
108 @comment  node-name,  next,  previous,  up
109 @section Comments
110 @cindex comments
111 @cindex @samp{;} in comment
113   A @dfn{comment} is text that is written in a program only for the sake
114 of humans that read the program, and that has no effect on the meaning
115 of the program.  In Lisp, a semicolon (@samp{;}) starts a comment if it
116 is not within a string or character constant.  The comment continues to
117 the end of line.  The Lisp reader discards comments; they do not become
118 part of the Lisp objects which represent the program within the Lisp
119 system.
121   The @samp{#@@@var{count}} construct, which skips the next @var{count}
122 characters, is useful for program-generated comments containing binary
123 data.  The Emacs Lisp byte compiler uses this in its output files
124 (@pxref{Byte Compilation}).  It isn't meant for source files, however.
126   @xref{Comment Tips}, for conventions for formatting comments.
128 @node Programming Types
129 @section Programming Types
130 @cindex programming types
132   There are two general categories of types in Emacs Lisp: those having
133 to do with Lisp programming, and those having to do with editing.  The
134 former exist in many Lisp implementations, in one form or another.  The
135 latter are unique to Emacs Lisp.
137 @menu
138 * Integer Type::        Numbers without fractional parts.
139 * Floating Point Type:: Numbers with fractional parts and with a large range.
140 * Character Type::      The representation of letters, numbers and
141                         control characters.
142 * Symbol Type::         A multi-use object that refers to a function,
143                         variable, or property list, and has a unique identity.
144 * Sequence Type::       Both lists and arrays are classified as sequences.
145 * Cons Cell Type::      Cons cells, and lists (which are made from cons cells).
146 * Array Type::          Arrays include strings and vectors.
147 * String Type::         An (efficient) array of characters.
148 * Vector Type::         One-dimensional arrays.
149 * Char-Table Type::     One-dimensional sparse arrays indexed by characters.
150 * Bool-Vector Type::    One-dimensional arrays of @code{t} or @code{nil}.
151 * Hash Table Type::     Super-fast lookup tables.
152 * Function Type::       A piece of executable code you can call from elsewhere.
153 * Macro Type::          A method of expanding an expression into another
154                           expression, more fundamental but less pretty.
155 * Primitive Function Type::     A function written in C, callable from Lisp.
156 * Byte-Code Type::      A function written in Lisp, then compiled.
157 * Autoload Type::       A type used for automatically loading seldom-used
158                         functions.
159 @end menu
161 @node Integer Type
162 @subsection Integer Type
164   The range of values for integers in Emacs Lisp is @minus{}134217728 to
165 134217727 (28 bits; i.e.,
166 @ifnottex
167 -2**27
168 @end ifnottex
169 @tex
170 @math{-2^{27}}
171 @end tex
173 @ifnottex
174 2**27 - 1)
175 @end ifnottex
176 @tex
177 @math{2^{28}-1})
178 @end tex
179 on most machines.  (Some machines may provide a wider range.)  It is
180 important to note that the Emacs Lisp arithmetic functions do not check
181 for overflow.  Thus @code{(1+ 134217727)} is @minus{}134217728 on most
182 machines.
184   The read syntax for integers is a sequence of (base ten) digits with an
185 optional sign at the beginning and an optional period at the end.  The
186 printed representation produced by the Lisp interpreter never has a
187 leading @samp{+} or a final @samp{.}.
189 @example
190 @group
191 -1               ; @r{The integer -1.}
192 1                ; @r{The integer 1.}
193 1.               ; @r{Also the integer 1.}
194 +1               ; @r{Also the integer 1.}
195 268435457        ; @r{Also the integer 1 on a 28-bit implementation.}
196 @end group
197 @end example
199   @xref{Numbers}, for more information.
201 @node Floating Point Type
202 @subsection Floating Point Type
204   Emacs supports floating point numbers (though there is a compilation
205 option to disable them).  The precise range of floating point numbers is
206 machine-specific.
208   The printed representation for floating point numbers requires either
209 a decimal point (with at least one digit following), an exponent, or
210 both.  For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
211 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
212 number whose value is 1500.  They are all equivalent.
214   @xref{Numbers}, for more information.
216 @node Character Type
217 @subsection Character Type
218 @cindex @sc{ascii} character codes
220   A @dfn{character} in Emacs Lisp is nothing more than an integer.  In
221 other words, characters are represented by their character codes.  For
222 example, the character @kbd{A} is represented as the @w{integer 65}.
224   Individual characters are not often used in programs.  It is far more
225 common to work with @emph{strings}, which are sequences composed of
226 characters.  @xref{String Type}.
228   Characters in strings, buffers, and files are currently limited to the
229 range of 0 to 524287---nineteen bits.  But not all values in that range
230 are valid character codes.  Codes 0 through 127 are @sc{ascii} codes; the
231 rest are non-@sc{ascii} (@pxref{Non-ASCII Characters}).  Characters that represent
232 keyboard input have a much wider range, to encode modifier keys such as
233 Control, Meta and Shift.
235 @cindex read syntax for characters
236 @cindex printed representation for characters
237 @cindex syntax for characters
238 @cindex @samp{?} in character constant
239 @cindex question mark in character constant
240   Since characters are really integers, the printed representation of a
241 character is a decimal number.  This is also a possible read syntax for
242 a character, but writing characters that way in Lisp programs is a very
243 bad idea.  You should @emph{always} use the special read syntax formats
244 that Emacs Lisp provides for characters.  These syntax formats start
245 with a question mark.
247   The usual read syntax for alphanumeric characters is a question mark
248 followed by the character; thus, @samp{?A} for the character
249 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
250 character @kbd{a}.  
252   For example:
254 @example
255 ?Q @result{} 81     ?q @result{} 113
256 @end example
258   You can use the same syntax for punctuation characters, but it is
259 often a good idea to add a @samp{\} so that the Emacs commands for
260 editing Lisp code don't get confused.  For example, @samp{?\ } is the
261 way to write the space character.  If the character is @samp{\}, you
262 @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
264 @cindex whitespace
265 @cindex bell character
266 @cindex @samp{\a}
267 @cindex backspace
268 @cindex @samp{\b}
269 @cindex tab
270 @cindex @samp{\t}
271 @cindex vertical tab
272 @cindex @samp{\v}
273 @cindex formfeed
274 @cindex @samp{\f}
275 @cindex newline
276 @cindex @samp{\n}
277 @cindex return
278 @cindex @samp{\r}
279 @cindex escape
280 @cindex @samp{\e}
281   You can express the characters Control-g, backspace, tab, newline,
282 vertical tab, formfeed, return, and escape as @samp{?\a}, @samp{?\b},
283 @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e},
284 respectively.  Thus,
286 @example
287 ?\a @result{} 7                 ; @r{@kbd{C-g}}
288 ?\b @result{} 8                 ; @r{backspace, @key{BS}, @kbd{C-h}}
289 ?\t @result{} 9                 ; @r{tab, @key{TAB}, @kbd{C-i}}
290 ?\n @result{} 10                ; @r{newline, @kbd{C-j}}
291 ?\v @result{} 11                ; @r{vertical tab, @kbd{C-k}}
292 ?\f @result{} 12                ; @r{formfeed character, @kbd{C-l}}
293 ?\r @result{} 13                ; @r{carriage return, @key{RET}, @kbd{C-m}}
294 ?\e @result{} 27                ; @r{escape character, @key{ESC}, @kbd{C-[}}
295 ?\\ @result{} 92                ; @r{backslash character, @kbd{\}}
296 ?\d @result{} 127               ; @r{delete character, @key{DEL}}
297 @end example
299 @cindex escape sequence
300   These sequences which start with backslash are also known as
301 @dfn{escape sequences}, because backslash plays the role of an escape
302 character; this usage has nothing to do with the character @key{ESC}.
304 @cindex control characters
305   Control characters may be represented using yet another read syntax.
306 This consists of a question mark followed by a backslash, caret, and the
307 corresponding non-control character, in either upper or lower case.  For
308 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
309 character @kbd{C-i}, the character whose value is 9.
311   Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
312 equivalent to @samp{?\^I} and to @samp{?\^i}:
314 @example
315 ?\^I @result{} 9     ?\C-I @result{} 9
316 @end example
318   In strings and buffers, the only control characters allowed are those
319 that exist in @sc{ascii}; but for keyboard input purposes, you can turn
320 any character into a control character with @samp{C-}.  The character
321 codes for these non-@sc{ascii} control characters include the
322 @tex
323 @math{2^{26}}
324 @end tex
325 @ifnottex
326 2**26
327 @end ifnottex
328 bit as well as the code for the corresponding non-control
329 character.  Ordinary terminals have no way of generating non-@sc{ascii}
330 control characters, but you can generate them straightforwardly using X
331 and other window systems.
333   For historical reasons, Emacs treats the @key{DEL} character as
334 the control equivalent of @kbd{?}:
336 @example
337 ?\^? @result{} 127     ?\C-? @result{} 127
338 @end example
340 @noindent
341 As a result, it is currently not possible to represent the character
342 @kbd{Control-?}, which is a meaningful input character under X, using
343 @samp{\C-}.  It is not easy to change this, as various Lisp files refer
344 to @key{DEL} in this way.
346   For representing control characters to be found in files or strings,
347 we recommend the @samp{^} syntax; for control characters in keyboard
348 input, we prefer the @samp{C-} syntax.  Which one you use does not
349 affect the meaning of the program, but may guide the understanding of
350 people who read it.
352 @cindex meta characters
353   A @dfn{meta character} is a character typed with the @key{META}
354 modifier key.  The integer that represents such a character has the
355 @tex
356 @math{2^{27}}
357 @end tex
358 @ifnottex
359 2**27
360 @end ifnottex
361 bit set (which on most machines makes it a negative number).  We
362 use high bits for this and other modifiers to make possible a wide range
363 of basic character codes.
365   In a string, the
366 @tex
367 @math{2^{7}}
368 @end tex
369 @ifnottex
370 2**7
371 @end ifnottex
372 bit attached to an @sc{ascii} character indicates a meta character; thus, the
373 meta characters that can fit in a string have codes in the range from
374 128 to 255, and are the meta versions of the ordinary @sc{ascii}
375 characters.  (In Emacs versions 18 and older, this convention was used
376 for characters outside of strings as well.)
378   The read syntax for meta characters uses @samp{\M-}.  For example,
379 @samp{?\M-A} stands for @kbd{M-A}.  You can use @samp{\M-} together with
380 octal character codes (see below), with @samp{\C-}, or with any other
381 syntax for a character.  Thus, you can write @kbd{M-A} as @samp{?\M-A},
382 or as @samp{?\M-\101}.  Likewise, you can write @kbd{C-M-b} as
383 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
385   The case of a graphic character is indicated by its character code;
386 for example, @sc{ascii} distinguishes between the characters @samp{a}
387 and @samp{A}.  But @sc{ascii} has no way to represent whether a control
388 character is upper case or lower case.  Emacs uses the
389 @tex
390 @math{2^{25}}
391 @end tex
392 @ifnottex
393 2**25
394 @end ifnottex
395 bit to indicate that the shift key was used in typing a control
396 character.  This distinction is possible only when you use X terminals
397 or other special terminals; ordinary terminals do not report the
398 distinction to the computer in any way.  The Lisp syntax for
399 the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O} 
400 represents the shifted-control-o character.
402 @cindex hyper characters
403 @cindex super characters
404 @cindex alt characters
405   The X Window System defines three other modifier bits that can be set
406 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}.  The syntaxes
407 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}.  (Case is
408 significant in these prefixes.)  Thus, @samp{?\H-\M-\A-x} represents
409 @kbd{Alt-Hyper-Meta-x}.
410 @tex
411 Numerically, the
412 bit values are @math{2^{22}} for alt, @math{2^{23}} for super and @math{2^{24}} for hyper.
413 @end tex
414 @ifnottex
415 Numerically, the
416 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
417 @end ifnottex
419 @cindex @samp{\} in character constant
420 @cindex backslash in character constant
421 @cindex octal character code
422   Finally, the most general read syntax for a character represents the
423 character code in either octal or hex.  To use octal, write a question
424 mark followed by a backslash and the octal character code (up to three
425 octal digits); thus, @samp{?\101} for the character @kbd{A},
426 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
427 character @kbd{C-b}.  Although this syntax can represent any @sc{ascii}
428 character, it is preferred only when the precise octal value is more
429 important than the @sc{ascii} representation.
431 @example
432 @group
433 ?\012 @result{} 10         ?\n @result{} 10         ?\C-j @result{} 10
434 ?\101 @result{} 65         ?A @result{} 65
435 @end group
436 @end example
438   To use hex, write a question mark followed by a backslash, @samp{x},
439 and the hexadecimal character code.  You can use any number of hex
440 digits, so you can represent any character code in this way.
441 Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
442 character @kbd{C-a}, and @code{?\x8e0} for the character
443 @iftex
444 @samp{@`a}.
445 @end iftex
446 @ifnottex
447 @samp{a} with grave accent.
448 @end ifnottex
450   A backslash is allowed, and harmless, preceding any character without
451 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
452 There is no reason to add a backslash before most characters.  However,
453 you should add a backslash before any of the characters
454 @samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
455 Lisp code.  Also add a backslash before whitespace characters such as
456 space, tab, newline and formfeed.  However, it is cleaner to use one of
457 the easily readable escape sequences, such as @samp{\t}, instead of an
458 actual whitespace character such as a tab.
460 @node Symbol Type
461 @subsection Symbol Type
463   A @dfn{symbol} in GNU Emacs Lisp is an object with a name.  The symbol
464 name serves as the printed representation of the symbol.  In ordinary
465 use, the name is unique---no two symbols have the same name.
467   A symbol can serve as a variable, as a function name, or to hold a
468 property list.  Or it may serve only to be distinct from all other Lisp
469 objects, so that its presence in a data structure may be recognized
470 reliably.  In a given context, usually only one of these uses is
471 intended.  But you can use one symbol in all of these ways,
472 independently.
474   A symbol whose name starts with a colon (@samp{:}) is called a
475 @dfn{keyword symbol}.  These symbols automatically act as constants, and
476 are normally used only by comparing an unknown symbol with a few
477 specific alternatives.
479 @cindex @samp{\} in symbols
480 @cindex backslash in symbols
481   A symbol name can contain any characters whatever.  Most symbol names
482 are written with letters, digits, and the punctuation characters
483 @samp{-+=*/}.  Such names require no special punctuation; the characters
484 of the name suffice as long as the name does not look like a number.
485 (If it does, write a @samp{\} at the beginning of the name to force
486 interpretation as a symbol.)  The characters @samp{_~!@@$%^&:<>@{@}} are
487 less often used but also require no special punctuation.  Any other
488 characters may be included in a symbol's name by escaping them with a
489 backslash.  In contrast to its use in strings, however, a backslash in
490 the name of a symbol simply quotes the single character that follows the
491 backslash.  For example, in a string, @samp{\t} represents a tab
492 character; in the name of a symbol, however, @samp{\t} merely quotes the
493 letter @samp{t}.  To have a symbol with a tab character in its name, you
494 must actually use a tab (preceded with a backslash).  But it's rare to
495 do such a thing.
497 @cindex CL note---case of letters
498 @quotation
499 @b{Common Lisp note:} In Common Lisp, lower case letters are always
500 ``folded'' to upper case, unless they are explicitly escaped.  In Emacs
501 Lisp, upper case and lower case letters are distinct.
502 @end quotation
504   Here are several examples of symbol names.  Note that the @samp{+} in
505 the fifth example is escaped to prevent it from being read as a number.
506 This is not necessary in the sixth example because the rest of the name
507 makes it invalid as a number.
509 @example
510 @group
511 foo                 ; @r{A symbol named @samp{foo}.}
512 FOO                 ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
513 char-to-string      ; @r{A symbol named @samp{char-to-string}.}
514 @end group
515 @group
516 1+                  ; @r{A symbol named @samp{1+}}
517                     ;   @r{(not @samp{+1}, which is an integer).}
518 @end group
519 @group
520 \+1                 ; @r{A symbol named @samp{+1}}
521                     ;   @r{(not a very readable name).}
522 @end group
523 @group
524 \(*\ 1\ 2\)         ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
525 @c the @'s in this next line use up three characters, hence the
526 @c apparent misalignment of the comment.
527 +-*/_~!@@$%^&=:<>@{@}  ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
528                     ;   @r{These characters need not be escaped.}
529 @end group
530 @end example
532 @cindex @samp{#:} read syntax
533   Normally the Lisp reader interns all symbols (@pxref{Creating
534 Symbols}).  To prevent interning, you can write @samp{#:} before the
535 name of the symbol.
537 @node Sequence Type
538 @subsection Sequence Types
540   A @dfn{sequence} is a Lisp object that represents an ordered set of
541 elements.  There are two kinds of sequence in Emacs Lisp, lists and
542 arrays.  Thus, an object of type list or of type array is also
543 considered a sequence.
545   Arrays are further subdivided into strings, vectors, char-tables and
546 bool-vectors.  Vectors can hold elements of any type, but string
547 elements must be characters, and bool-vector elements must be @code{t}
548 or @code{nil}.  The characters in a string can have text properties like
549 characters in a buffer (@pxref{Text Properties}); vectors and
550 bool-vectors do not support text properties even when their elements
551 happen to be characters.  Char-tables are like vectors except that they
552 are indexed by any valid character code.
554   Lists, strings and the other array types are different, but they have
555 important similarities.  For example, all have a length @var{l}, and all
556 have elements which can be indexed from zero to @var{l} minus one.
557 Several functions, called sequence functions, accept any kind of
558 sequence.  For example, the function @code{elt} can be used to extract
559 an element of a sequence, given its index.  @xref{Sequences Arrays
560 Vectors}.
562   It is generally impossible to read the same sequence twice, since
563 sequences are always created anew upon reading.  If you read the read
564 syntax for a sequence twice, you get two sequences with equal contents.
565 There is one exception: the empty list @code{()} always stands for the
566 same object, @code{nil}.
568 @node Cons Cell Type
569 @subsection Cons Cell and List Types
570 @cindex address field of register
571 @cindex decrement field of register
572 @cindex pointers
574   A @dfn{cons cell} is an object that consists of two slots, called the
575 @sc{car} slot and the @sc{cdr} slot.  Each slot can @dfn{hold} or
576 @dfn{refer to} any Lisp object.  We also say that ``the @sc{car} of
577 this cons cell is'' whatever object its @sc{car} slot currently holds,
578 and likewise for the @sc{cdr}.
580 @quotation
581 A note to C programmers: in Lisp, we do not distinguish between
582 ``holding'' a value and ``pointing to'' the value, because pointers in
583 Lisp are implicit.
584 @end quotation
586   A @dfn{list} is a series of cons cells, linked together so that the
587 @sc{cdr} slot of each cons cell holds either the next cons cell or the
588 empty list.  @xref{Lists}, for functions that work on lists.  Because
589 most cons cells are used as part of lists, the phrase @dfn{list
590 structure} has come to refer to any structure made out of cons cells.
592   The names @sc{car} and @sc{cdr} derive from the history of Lisp.  The
593 original Lisp implementation ran on an @w{IBM 704} computer which
594 divided words into two parts, called the ``address'' part and the
595 ``decrement''; @sc{car} was an instruction to extract the contents of
596 the address part of a register, and @sc{cdr} an instruction to extract
597 the contents of the decrement.  By contrast, ``cons cells'' are named
598 for the function @code{cons} that creates them, which in turn was named
599 for its purpose, the construction of cells.
601 @cindex atom
602   Because cons cells are so central to Lisp, we also have a word for
603 ``an object which is not a cons cell''.  These objects are called
604 @dfn{atoms}.
606 @cindex parenthesis
607   The read syntax and printed representation for lists are identical, and
608 consist of a left parenthesis, an arbitrary number of elements, and a
609 right parenthesis.
611    Upon reading, each object inside the parentheses becomes an element
612 of the list.  That is, a cons cell is made for each element.  The
613 @sc{car} slot of the cons cell holds the element, and its @sc{cdr}
614 slot refers to the next cons cell of the list, which holds the next
615 element in the list.  The @sc{cdr} slot of the last cons cell is set to
616 hold @code{nil}.
618 @cindex box diagrams, for lists
619 @cindex diagrams, boxed, for lists
620   A list can be illustrated by a diagram in which the cons cells are
621 shown as pairs of boxes, like dominoes.  (The Lisp reader cannot read
622 such an illustration; unlike the textual notation, which can be
623 understood by both humans and computers, the box illustrations can be
624 understood only by humans.)  This picture represents the three-element
625 list @code{(rose violet buttercup)}:
627 @example
628 @group
629     --- ---      --- ---      --- ---
630    |   |   |--> |   |   |--> |   |   |--> nil
631     --- ---      --- ---      --- ---
632      |            |            |
633      |            |            |
634       --> rose     --> violet   --> buttercup
635 @end group
636 @end example
638   In this diagram, each box represents a slot that can hold or refer to
639 any Lisp object.  Each pair of boxes represents a cons cell.  Each arrow
640 represents a reference to a Lisp object, either an atom or another cons
641 cell.
643   In this example, the first box, which holds the @sc{car} of the first
644 cons cell, refers to or ``holds'' @code{rose} (a symbol).  The second
645 box, holding the @sc{cdr} of the first cons cell, refers to the next
646 pair of boxes, the second cons cell.  The @sc{car} of the second cons
647 cell is @code{violet}, and its @sc{cdr} is the third cons cell.  The
648 @sc{cdr} of the third (and last) cons cell is @code{nil}.
650   Here is another diagram of the same list, @code{(rose violet
651 buttercup)}, sketched in a different manner:
653 @smallexample
654 @group
655  ---------------       ----------------       -------------------
656 | car   | cdr   |     | car    | cdr   |     | car       | cdr   |
657 | rose  |   o-------->| violet |   o-------->| buttercup |  nil  |
658 |       |       |     |        |       |     |           |       |
659  ---------------       ----------------       -------------------
660 @end group
661 @end smallexample
663 @cindex @samp{(@dots{})} in lists
664 @cindex @code{nil} in lists
665 @cindex empty list
666   A list with no elements in it is the @dfn{empty list}; it is identical
667 to the symbol @code{nil}.  In other words, @code{nil} is both a symbol
668 and a list.
670   Here are examples of lists written in Lisp syntax:
672 @example
673 (A 2 "A")            ; @r{A list of three elements.}
674 ()                   ; @r{A list of no elements (the empty list).}
675 nil                  ; @r{A list of no elements (the empty list).}
676 ("A ()")             ; @r{A list of one element: the string @code{"A ()"}.}
677 (A ())               ; @r{A list of two elements: @code{A} and the empty list.}
678 (A nil)              ; @r{Equivalent to the previous.}
679 ((A B C))            ; @r{A list of one element}
680                      ;   @r{(which is a list of three elements).}
681 @end example
683   Here is the list @code{(A ())}, or equivalently @code{(A nil)},
684 depicted with boxes and arrows:
686 @example
687 @group
688     --- ---      --- ---
689    |   |   |--> |   |   |--> nil
690     --- ---      --- ---
691      |            |
692      |            |
693       --> A        --> nil
694 @end group
695 @end example
697 @menu
698 * Dotted Pair Notation::        An alternative syntax for lists.
699 * Association List Type::       A specially constructed list.
700 @end menu
702 @node Dotted Pair Notation
703 @comment  node-name,  next,  previous,  up
704 @subsubsection Dotted Pair Notation
705 @cindex dotted pair notation
706 @cindex @samp{.} in lists
708   @dfn{Dotted pair notation} is an alternative syntax for cons cells
709 that represents the @sc{car} and @sc{cdr} explicitly.  In this syntax,
710 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
711 the object @var{a}, and whose @sc{cdr} is the object @var{b}.  Dotted
712 pair notation is therefore more general than list syntax.  In the dotted
713 pair notation, the list @samp{(1 2 3)} is written as @samp{(1 .  (2 . (3
714 . nil)))}.  For @code{nil}-terminated lists, you can use either
715 notation, but list notation is usually clearer and more convenient.
716 When printing a list, the dotted pair notation is only used if the
717 @sc{cdr} of a cons cell is not a list.
719   Here's an example using boxes to illustrate dotted pair notation.
720 This example shows the pair @code{(rose . violet)}:
722 @example
723 @group
724     --- ---
725    |   |   |--> violet
726     --- ---
727      |
728      |
729       --> rose
730 @end group
731 @end example
733   You can combine dotted pair notation with list notation to represent
734 conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}.
735 You write a dot after the last element of the list, followed by the
736 @sc{cdr} of the final cons cell.  For example, @code{(rose violet
737 . buttercup)} is equivalent to @code{(rose . (violet . buttercup))}.
738 The object looks like this:
740 @example
741 @group
742     --- ---      --- ---
743    |   |   |--> |   |   |--> buttercup
744     --- ---      --- ---
745      |            |
746      |            |
747       --> rose     --> violet
748 @end group
749 @end example
751   The syntax @code{(rose .@: violet .@: buttercup)} is invalid because
752 there is nothing that it could mean.  If anything, it would say to put
753 @code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already
754 used for @code{violet}.
756   The list @code{(rose violet)} is equivalent to @code{(rose . (violet))},
757 and looks like this:
759 @example
760 @group
761     --- ---      --- ---
762    |   |   |--> |   |   |--> nil
763     --- ---      --- ---
764      |            |
765      |            |
766       --> rose     --> violet
767 @end group
768 @end example
770   Similarly, the three-element list @code{(rose violet buttercup)}
771 is equivalent to @code{(rose . (violet . (buttercup)))}.
772 @ifnottex
773 It looks like this:
775 @example
776 @group
777     --- ---      --- ---      --- ---
778    |   |   |--> |   |   |--> |   |   |--> nil
779     --- ---      --- ---      --- ---
780      |            |            |
781      |            |            |
782       --> rose     --> violet   --> buttercup
783 @end group
784 @end example
785 @end ifnottex
787 @node Association List Type
788 @comment  node-name,  next,  previous,  up
789 @subsubsection Association List Type
791   An @dfn{association list} or @dfn{alist} is a specially-constructed
792 list whose elements are cons cells.  In each element, the @sc{car} is
793 considered a @dfn{key}, and the @sc{cdr} is considered an
794 @dfn{associated value}.  (In some cases, the associated value is stored
795 in the @sc{car} of the @sc{cdr}.)  Association lists are often used as
796 stacks, since it is easy to add or remove associations at the front of
797 the list.
799   For example,
801 @example
802 (setq alist-of-colors
803       '((rose . red) (lily . white)  (buttercup . yellow)))
804 @end example
806 @noindent
807 sets the variable @code{alist-of-colors} to an alist of three elements.  In the
808 first element, @code{rose} is the key and @code{red} is the value.
810   @xref{Association Lists}, for a further explanation of alists and for
811 functions that work on alists.  @xref{Hash Tables}, for another kind of
812 lookup table, which is much faster for handling a large number of keys.
814 @node Array Type
815 @subsection Array Type
817   An @dfn{array} is composed of an arbitrary number of slots for
818 holding or referring to other Lisp objects, arranged in a contiguous block of
819 memory.  Accessing any element of an array takes approximately the same
820 amount of time.  In contrast, accessing an element of a list requires
821 time proportional to the position of the element in the list.  (Elements
822 at the end of a list take longer to access than elements at the
823 beginning of a list.)
825   Emacs defines four types of array: strings, vectors, bool-vectors, and
826 char-tables.
828   A string is an array of characters and a vector is an array of
829 arbitrary objects.  A bool-vector can hold only @code{t} or @code{nil}.
830 These kinds of array may have any length up to the largest integer.
831 Char-tables are sparse arrays indexed by any valid character code; they
832 can hold arbitrary objects.
834   The first element of an array has index zero, the second element has
835 index 1, and so on.  This is called @dfn{zero-origin} indexing.  For
836 example, an array of four elements has indices 0, 1, 2, @w{and 3}.  The
837 largest possible index value is one less than the length of the array.
838 Once an array is created, its length is fixed.
840   All Emacs Lisp arrays are one-dimensional.  (Most other programming
841 languages support multidimensional arrays, but they are not essential;
842 you can get the same effect with an array of arrays.)  Each type of
843 array has its own read syntax; see the following sections for details.
845   The array type is contained in the sequence type and
846 contains the string type, the vector type, the bool-vector type, and the
847 char-table type.
849 @node String Type
850 @subsection String Type
852   A @dfn{string} is an array of characters.  Strings are used for many
853 purposes in Emacs, as can be expected in a text editor; for example, as
854 the names of Lisp symbols, as messages for the user, and to represent
855 text extracted from buffers.  Strings in Lisp are constants: evaluation
856 of a string returns the same string.
858   @xref{Strings and Characters}, for functions that operate on strings.
860 @menu
861 * Syntax for Strings::
862 * Non-ASCII in Strings::
863 * Nonprinting Characters::
864 * Text Props and Strings::
865 @end menu
867 @node Syntax for Strings
868 @subsubsection Syntax for Strings
870 @cindex @samp{"} in strings
871 @cindex double-quote in strings
872 @cindex @samp{\} in strings
873 @cindex backslash in strings
874   The read syntax for strings is a double-quote, an arbitrary number of
875 characters, and another double-quote, @code{"like this"}.  To include a
876 double-quote in a string, precede it with a backslash; thus, @code{"\""}
877 is a string containing just a single double-quote character.  Likewise,
878 you can include a backslash by preceding it with another backslash, like
879 this: @code{"this \\ is a single embedded backslash"}.
881 @cindex newline in strings
882   The newline character is not special in the read syntax for strings;
883 if you write a new line between the double-quotes, it becomes a
884 character in the string.  But an escaped newline---one that is preceded
885 by @samp{\}---does not become part of the string; i.e., the Lisp reader
886 ignores an escaped newline while reading a string.  An escaped space
887 @w{@samp{\ }} is likewise ignored.
889 @example
890 "It is useful to include newlines
891 in documentation strings,
892 but the newline is \
893 ignored if escaped."
894      @result{} "It is useful to include newlines 
895 in documentation strings, 
896 but the newline is ignored if escaped."
897 @end example
899 @node Non-ASCII in Strings
900 @subsubsection Non-@sc{ascii} Characters in Strings
902   You can include a non-@sc{ascii} international character in a string
903 constant by writing it literally.  There are two text representations
904 for non-@sc{ascii} characters in Emacs strings (and in buffers): unibyte
905 and multibyte.  If the string constant is read from a multibyte source,
906 such as a multibyte buffer or string, or a file that would be visited as
907 multibyte, then the character is read as a multibyte character, and that
908 makes the string multibyte.  If the string constant is read from a
909 unibyte source, then the character is read as unibyte and that makes the
910 string unibyte.
912   You can also represent a multibyte non-@sc{ascii} character with its
913 character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
914 digits as necessary.  (Multibyte non-@sc{ascii} character codes are all
915 greater than 256.)  Any character which is not a valid hex digit
916 terminates this construct.  If the next character in the string could be
917 interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
918 terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents
919 one character, @samp{a} with grave accent.  @w{@samp{\ }} in a string
920 constant is just like backslash-newline; it does not contribute any
921 character to the string, but it does terminate the preceding hex escape.
923   Using a multibyte hex escape forces the string to multibyte.  You can
924 represent a unibyte non-@sc{ascii} character with its character code,
925 which must be in the range from 128 (0200 octal) to 255 (0377 octal).
926 This forces a unibyte string.
927   
928   @xref{Text Representations}, for more information about the two
929 text representations.
931 @node Nonprinting Characters
932 @subsubsection Nonprinting Characters in Strings
934   You can use the same backslash escape-sequences in a string constant
935 as in character literals (but do not use the question mark that begins a
936 character constant).  For example, you can write a string containing the
937 nonprinting characters tab and @kbd{C-a}, with commas and spaces between
938 them, like this: @code{"\t, \C-a"}.  @xref{Character Type}, for a
939 description of the read syntax for characters.
941   However, not all of the characters you can write with backslash
942 escape-sequences are valid in strings.  The only control characters that
943 a string can hold are the @sc{ascii} control characters.  Strings do not
944 distinguish case in @sc{ascii} control characters.
946   Properly speaking, strings cannot hold meta characters; but when a
947 string is to be used as a key sequence, there is a special convention
948 that provides a way to represent meta versions of @sc{ascii} characters in a
949 string.  If you use the @samp{\M-} syntax to indicate a meta character
950 in a string constant, this sets the
951 @tex
952 @math{2^{7}}
953 @end tex
954 @ifnottex
955 2**7
956 @end ifnottex
957 bit of the character in the string.  If the string is used in
958 @code{define-key} or @code{lookup-key}, this numeric code is translated
959 into the equivalent meta character.  @xref{Character Type}.
961   Strings cannot hold characters that have the hyper, super, or alt
962 modifiers.
964 @node Text Props and Strings
965 @subsubsection Text Properties in Strings
967   A string can hold properties for the characters it contains, in
968 addition to the characters themselves.  This enables programs that copy
969 text between strings and buffers to copy the text's properties with no
970 special effort.  @xref{Text Properties}, for an explanation of what text
971 properties mean.  Strings with text properties use a special read and
972 print syntax:
974 @example
975 #("@var{characters}" @var{property-data}...)
976 @end example
978 @noindent
979 where @var{property-data} consists of zero or more elements, in groups
980 of three as follows:
982 @example
983 @var{beg} @var{end} @var{plist}
984 @end example
986 @noindent
987 The elements @var{beg} and @var{end} are integers, and together specify
988 a range of indices in the string; @var{plist} is the property list for
989 that range.  For example,
991 @example
992 #("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
993 @end example
995 @noindent
996 represents a string whose textual contents are @samp{foo bar}, in which
997 the first three characters have a @code{face} property with value
998 @code{bold}, and the last three have a @code{face} property with value
999 @code{italic}.  (The fourth character has no text properties, so its
1000 property list is @code{nil}.  It is not actually necessary to mention
1001 ranges with @code{nil} as the property list, since any characters not
1002 mentioned in any range will default to having no properties.)
1004 @node Vector Type
1005 @subsection Vector Type
1007   A @dfn{vector} is a one-dimensional array of elements of any type.  It
1008 takes a constant amount of time to access any element of a vector.  (In
1009 a list, the access time of an element is proportional to the distance of
1010 the element from the beginning of the list.)
1012   The printed representation of a vector consists of a left square
1013 bracket, the elements, and a right square bracket.  This is also the
1014 read syntax.  Like numbers and strings, vectors are considered constants
1015 for evaluation.
1017 @example
1018 [1 "two" (three)]      ; @r{A vector of three elements.}
1019      @result{} [1 "two" (three)]
1020 @end example
1022   @xref{Vectors}, for functions that work with vectors.
1024 @node Char-Table Type
1025 @subsection Char-Table Type
1027   A @dfn{char-table} is a one-dimensional array of elements of any type,
1028 indexed by character codes.  Char-tables have certain extra features to
1029 make them more useful for many jobs that involve assigning information
1030 to character codes---for example, a char-table can have a parent to
1031 inherit from, a default value, and a small number of extra slots to use for
1032 special purposes.  A char-table can also specify a single value for
1033 a whole character set.
1035   The printed representation of a char-table is like a vector
1036 except that there is an extra @samp{#^} at the beginning.
1038   @xref{Char-Tables}, for special functions to operate on char-tables.
1039 Uses of char-tables include:
1041 @itemize @bullet
1042 @item
1043 Case tables (@pxref{Case Tables}).
1045 @item
1046 Character category tables (@pxref{Categories}).
1048 @item
1049 Display Tables (@pxref{Display Tables}).
1051 @item
1052 Syntax tables (@pxref{Syntax Tables}).
1053 @end itemize
1055 @node Bool-Vector Type
1056 @subsection Bool-Vector Type
1058   A @dfn{bool-vector} is a one-dimensional array of elements that
1059 must be @code{t} or @code{nil}.
1061   The printed representation of a bool-vector is like a string, except
1062 that it begins with @samp{#&} followed by the length.  The string
1063 constant that follows actually specifies the contents of the bool-vector
1064 as a bitmap---each ``character'' in the string contains 8 bits, which
1065 specify the next 8 elements of the bool-vector (1 stands for @code{t},
1066 and 0 for @code{nil}).  The least significant bits of the character 
1067 correspond to the lowest indices in the bool-vector.  If the length is not a
1068 multiple of 8, the printed representation shows extra elements, but
1069 these extras really make no difference.
1071 @example
1072 (make-bool-vector 3 t)
1073      @result{} #&3"\007"
1074 (make-bool-vector 3 nil)
1075      @result{} #&3"\0"
1076 ;; @r{These are equal since only the first 3 bits are used.}
1077 (equal #&3"\377" #&3"\007")
1078      @result{} t
1079 @end example
1081 @node Hash Table Type
1082 @subsection Hash Table Type
1084     A hash table is a very fast kind of lookup table, somewhat like an
1085 alist in that it maps keys to corresponding values, but much faster.
1086 Hash tables are a new feature in Emacs 21; they have no read syntax, and
1087 print using hash notation.  @xref{Hash Tables}.
1089 @example
1090 (make-hash-table)
1091      @result{} #<hash-table 'eql nil 0/65 0x83af980>
1092 @end example
1094 @node Function Type
1095 @subsection Function Type
1097   Just as functions in other programming languages are executable,
1098 @dfn{Lisp function} objects are pieces of executable code.  However,
1099 functions in Lisp are primarily Lisp objects, and only secondarily the
1100 text which represents them.  These Lisp objects are lambda expressions:
1101 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
1102 Expressions}).
1104   In most programming languages, it is impossible to have a function
1105 without a name.  In Lisp, a function has no intrinsic name.  A lambda
1106 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
1107 Functions}).  A named function in Lisp is actually a symbol with a valid
1108 function in its function cell (@pxref{Defining Functions}).
1110   Most of the time, functions are called when their names are written in
1111 Lisp expressions in Lisp programs.  However, you can construct or obtain
1112 a function object at run time and then call it with the primitive
1113 functions @code{funcall} and @code{apply}.  @xref{Calling Functions}.
1115 @node Macro Type
1116 @subsection Macro Type
1118   A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
1119 language.  It is represented as an object much like a function, but with
1120 different argument-passing semantics.  A Lisp macro has the form of a
1121 list whose first element is the symbol @code{macro} and whose @sc{cdr}
1122 is a Lisp function object, including the @code{lambda} symbol.
1124   Lisp macro objects are usually defined with the built-in
1125 @code{defmacro} function, but any list that begins with @code{macro} is
1126 a macro as far as Emacs is concerned.  @xref{Macros}, for an explanation
1127 of how to write a macro.
1129   @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard
1130 Macros}) are entirely different things.  When we use the word ``macro''
1131 without qualification, we mean a Lisp macro, not a keyboard macro.
1133 @node Primitive Function Type
1134 @subsection Primitive Function Type
1135 @cindex special forms
1137   A @dfn{primitive function} is a function callable from Lisp but
1138 written in the C programming language.  Primitive functions are also
1139 called @dfn{subrs} or @dfn{built-in functions}.  (The word ``subr'' is
1140 derived from ``subroutine''.)  Most primitive functions evaluate all
1141 their arguments when they are called.  A primitive function that does
1142 not evaluate all its arguments is called a @dfn{special form}
1143 (@pxref{Special Forms}).@refill
1145   It does not matter to the caller of a function whether the function is
1146 primitive.  However, this does matter if you try to redefine a primitive
1147 with a function written in Lisp.  The reason is that the primitive
1148 function may be called directly from C code.  Calls to the redefined
1149 function from Lisp will use the new definition, but calls from C code
1150 may still use the built-in definition.  Therefore, @strong{we discourage
1151 redefinition of primitive functions}.
1153   The term @dfn{function} refers to all Emacs functions, whether written
1154 in Lisp or C.  @xref{Function Type}, for information about the
1155 functions written in Lisp.
1157   Primitive functions have no read syntax and print in hash notation
1158 with the name of the subroutine.
1160 @example
1161 @group
1162 (symbol-function 'car)          ; @r{Access the function cell}
1163                                 ;   @r{of the symbol.}
1164      @result{} #<subr car>
1165 (subrp (symbol-function 'car))  ; @r{Is this a primitive function?}
1166      @result{} t                       ; @r{Yes.}
1167 @end group
1168 @end example
1170 @node Byte-Code Type
1171 @subsection Byte-Code Function Type
1173 The byte compiler produces @dfn{byte-code function objects}.
1174 Internally, a byte-code function object is much like a vector; however,
1175 the evaluator handles this data type specially when it appears as a
1176 function to be called.  @xref{Byte Compilation}, for information about
1177 the byte compiler.
1179 The printed representation and read syntax for a byte-code function
1180 object is like that for a vector, with an additional @samp{#} before the
1181 opening @samp{[}.
1183 @node Autoload Type
1184 @subsection Autoload Type
1186   An @dfn{autoload object} is a list whose first element is the symbol
1187 @code{autoload}.  It is stored as the function definition of a symbol,
1188 where it serves as a placeholder for the real definition.  The autoload
1189 object says that the real definition is found in a file of Lisp code
1190 that should be loaded when necessary.  It contains the name of the file,
1191 plus some other information about the real definition.
1193   After the file has been loaded, the symbol should have a new function
1194 definition that is not an autoload object.  The new definition is then
1195 called as if it had been there to begin with.  From the user's point of
1196 view, the function call works as expected, using the function definition
1197 in the loaded file.
1199   An autoload object is usually created with the function
1200 @code{autoload}, which stores the object in the function cell of a
1201 symbol.  @xref{Autoload}, for more details.
1203 @node Editing Types
1204 @section Editing Types
1205 @cindex editing types
1207   The types in the previous section are used for general programming
1208 purposes, and most of them are common to most Lisp dialects.  Emacs Lisp
1209 provides several additional data types for purposes connected with
1210 editing.
1212 @menu
1213 * Buffer Type::         The basic object of editing.
1214 * Marker Type::         A position in a buffer.
1215 * Window Type::         Buffers are displayed in windows.
1216 * Frame Type::          Windows subdivide frames.
1217 * Window Configuration Type::   Recording the way a frame is subdivided.
1218 * Frame Configuration Type::    Recording the status of all frames.
1219 * Process Type::        A process running on the underlying OS.
1220 * Stream Type::         Receive or send characters.
1221 * Keymap Type::         What function a keystroke invokes.
1222 * Overlay Type::        How an overlay is represented.
1223 @end menu
1225 @node Buffer Type
1226 @subsection Buffer Type
1228   A @dfn{buffer} is an object that holds text that can be edited
1229 (@pxref{Buffers}).  Most buffers hold the contents of a disk file
1230 (@pxref{Files}) so they can be edited, but some are used for other
1231 purposes.  Most buffers are also meant to be seen by the user, and
1232 therefore displayed, at some time, in a window (@pxref{Windows}).  But a
1233 buffer need not be displayed in any window.
1235   The contents of a buffer are much like a string, but buffers are not
1236 used like strings in Emacs Lisp, and the available operations are
1237 different.  For example, you can insert text efficiently into an
1238 existing buffer, altering the buffer's contents, whereas ``inserting''
1239 text into a string requires concatenating substrings, and the result is
1240 an entirely new string object.
1242   Each buffer has a designated position called @dfn{point}
1243 (@pxref{Positions}).  At any time, one buffer is the @dfn{current
1244 buffer}.  Most editing commands act on the contents of the current
1245 buffer in the neighborhood of point.  Many of the standard Emacs
1246 functions manipulate or test the characters in the current buffer; a
1247 whole chapter in this manual is devoted to describing these functions
1248 (@pxref{Text}).
1250   Several other data structures are associated with each buffer:
1252 @itemize @bullet
1253 @item
1254 a local syntax table (@pxref{Syntax Tables});
1256 @item
1257 a local keymap (@pxref{Keymaps}); and,
1259 @item
1260 a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
1262 @item
1263 overlays (@pxref{Overlays}).
1265 @item
1266 text properties for the text in the buffer (@pxref{Text Properties}).
1267 @end itemize
1269 @noindent
1270 The local keymap and variable list contain entries that individually
1271 override global bindings or values.  These are used to customize the
1272 behavior of programs in different buffers, without actually changing the
1273 programs.
1275   A buffer may be @dfn{indirect}, which means it shares the text
1276 of another buffer, but presents it differently.  @xref{Indirect Buffers}.
1278   Buffers have no read syntax.  They print in hash notation, showing the
1279 buffer name.
1281 @example
1282 @group
1283 (current-buffer)
1284      @result{} #<buffer objects.texi>
1285 @end group
1286 @end example
1288 @node Marker Type
1289 @subsection Marker Type
1291   A @dfn{marker} denotes a position in a specific buffer.  Markers
1292 therefore have two components: one for the buffer, and one for the
1293 position.  Changes in the buffer's text automatically relocate the
1294 position value as necessary to ensure that the marker always points
1295 between the same two characters in the buffer.
1297   Markers have no read syntax.  They print in hash notation, giving the
1298 current character position and the name of the buffer.
1300 @example
1301 @group
1302 (point-marker)
1303      @result{} #<marker at 10779 in objects.texi>
1304 @end group
1305 @end example
1307 @xref{Markers}, for information on how to test, create, copy, and move
1308 markers.
1310 @node Window Type
1311 @subsection Window Type
1313   A @dfn{window} describes the portion of the terminal screen that Emacs
1314 uses to display a buffer.  Every window has one associated buffer, whose
1315 contents appear in the window.  By contrast, a given buffer may appear
1316 in one window, no window, or several windows.
1318   Though many windows may exist simultaneously, at any time one window
1319 is designated the @dfn{selected window}.  This is the window where the
1320 cursor is (usually) displayed when Emacs is ready for a command.  The
1321 selected window usually displays the current buffer, but this is not
1322 necessarily the case.
1324   Windows are grouped on the screen into frames; each window belongs to
1325 one and only one frame.  @xref{Frame Type}.
1327   Windows have no read syntax.  They print in hash notation, giving the
1328 window number and the name of the buffer being displayed.  The window
1329 numbers exist to identify windows uniquely, since the buffer displayed
1330 in any given window can change frequently.
1332 @example
1333 @group
1334 (selected-window)
1335      @result{} #<window 1 on objects.texi>
1336 @end group
1337 @end example
1339   @xref{Windows}, for a description of the functions that work on windows.
1341 @node Frame Type
1342 @subsection Frame Type
1344   A @dfn{frame} is a rectangle on the screen that contains one or more
1345 Emacs windows.  A frame initially contains a single main window (plus
1346 perhaps a minibuffer window) which you can subdivide vertically or
1347 horizontally into smaller windows.
1349   Frames have no read syntax.  They print in hash notation, giving the
1350 frame's title, plus its address in core (useful to identify the frame
1351 uniquely).
1353 @example
1354 @group
1355 (selected-frame)
1356      @result{} #<frame emacs@@psilocin.gnu.org 0xdac80>
1357 @end group
1358 @end example
1360   @xref{Frames}, for a description of the functions that work on frames.
1362 @node Window Configuration Type
1363 @subsection Window Configuration Type
1364 @cindex screen layout
1366   A @dfn{window configuration} stores information about the positions,
1367 sizes, and contents of the windows in a frame, so you can recreate the
1368 same arrangement of windows later.
1370   Window configurations do not have a read syntax; their print syntax
1371 looks like @samp{#<window-configuration>}.  @xref{Window
1372 Configurations}, for a description of several functions related to
1373 window configurations.
1375 @node Frame Configuration Type
1376 @subsection Frame Configuration Type
1377 @cindex screen layout
1379   A @dfn{frame configuration} stores information about the positions,
1380 sizes, and contents of the windows in all frames.  It is actually
1381 a list whose @sc{car} is @code{frame-configuration} and whose
1382 @sc{cdr} is an alist.  Each alist element describes one frame,
1383 which appears as the @sc{car} of that element.
1385   @xref{Frame Configurations}, for a description of several functions
1386 related to frame configurations.
1388 @node Process Type
1389 @subsection Process Type
1391   The word @dfn{process} usually means a running program.  Emacs itself
1392 runs in a process of this sort.  However, in Emacs Lisp, a process is a
1393 Lisp object that designates a subprocess created by the Emacs process.
1394 Programs such as shells, GDB, ftp, and compilers, running in
1395 subprocesses of Emacs, extend the capabilities of Emacs.
1397   An Emacs subprocess takes textual input from Emacs and returns textual
1398 output to Emacs for further manipulation.  Emacs can also send signals
1399 to the subprocess.
1401   Process objects have no read syntax.  They print in hash notation,
1402 giving the name of the process:
1404 @example
1405 @group
1406 (process-list)
1407      @result{} (#<process shell>)
1408 @end group
1409 @end example
1411 @xref{Processes}, for information about functions that create, delete,
1412 return information about, send input or signals to, and receive output
1413 from processes.
1415 @node Stream Type
1416 @subsection Stream Type
1418   A @dfn{stream} is an object that can be used as a source or sink for
1419 characters---either to supply characters for input or to accept them as
1420 output.  Many different types can be used this way: markers, buffers,
1421 strings, and functions.  Most often, input streams (character sources)
1422 obtain characters from the keyboard, a buffer, or a file, and output
1423 streams (character sinks) send characters to a buffer, such as a
1424 @file{*Help*} buffer, or to the echo area.
1426   The object @code{nil}, in addition to its other meanings, may be used
1427 as a stream.  It stands for the value of the variable
1428 @code{standard-input} or @code{standard-output}.  Also, the object
1429 @code{t} as a stream specifies input using the minibuffer
1430 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
1431 Area}).
1433   Streams have no special printed representation or read syntax, and
1434 print as whatever primitive type they are.
1436   @xref{Read and Print}, for a description of functions
1437 related to streams, including parsing and printing functions.
1439 @node Keymap Type
1440 @subsection Keymap Type
1442   A @dfn{keymap} maps keys typed by the user to commands.  This mapping
1443 controls how the user's command input is executed.  A keymap is actually
1444 a list whose @sc{car} is the symbol @code{keymap}.
1446   @xref{Keymaps}, for information about creating keymaps, handling prefix
1447 keys, local as well as global keymaps, and changing key bindings.
1449 @node Overlay Type
1450 @subsection Overlay Type
1452   An @dfn{overlay} specifies properties that apply to a part of a
1453 buffer.  Each overlay applies to a specified range of the buffer, and
1454 contains a property list (a list whose elements are alternating property
1455 names and values).  Overlay properties are used to present parts of the
1456 buffer temporarily in a different display style.  Overlays have no read
1457 syntax, and print in hash notation, giving the buffer name and range of
1458 positions.
1460   @xref{Overlays}, for how to create and use overlays.
1462 @node Circular Objects
1463 @section Read Syntax for Circular Objects
1464 @cindex circular structure, read syntax
1465 @cindex shared structure, read syntax
1466 @cindex @samp{#@var{n}=} read syntax
1467 @cindex @samp{#@var{n}#} read syntax
1469   In Emacs 21, to represent shared or circular structure within a
1470 complex of Lisp objects, you can use the reader constructs
1471 @samp{#@var{n}=} and @samp{#@var{n}#}.
1473   Use @code{#@var{n}=} before an object to label it for later reference;
1474 subsequently, you can use @code{#@var{n}#} to refer the same object in
1475 another place.  Here, @var{n} is some integer.  For example, here is how
1476 to make a list in which the first element recurs as the third element:
1478 @example
1479 (#1=(a) b #1#)
1480 @end example
1482 @noindent
1483 This differs from ordinary syntax such as this
1485 @example
1486 ((a) b (a))
1487 @end example
1489 @noindent
1490 which would result in a list whose first and third elements
1491 look alike but are not the same Lisp object.  This shows the difference:
1493 @example
1494 (prog1 nil
1495   (setq x '(#1=(a) b #1#)))
1496 (eq (nth 0 x) (nth 2 x))
1497      @result{} t
1498 (setq x '((a) b (a)))
1499 (eq (nth 0 x) (nth 2 x))
1500      @result{} nil
1501 @end example
1503   You can also use the same syntax to make a circular structure, which
1504 appears as an ``element'' within itself.  Here is an example:
1506 @example
1507 #1=(a #1#)
1508 @end example
1510 @noindent
1511 This makes a list whose second element is the list itself.
1512 Here's how you can see that it really works:
1514 @example
1515 (prog1 nil
1516   (setq x '#1=(a #1#)))
1517 (eq x (cadr x))
1518      @result{} t
1519 @end example
1521   The Lisp printer can produce this syntax to record circular and shared
1522 structure in a Lisp object, if you bind the variable @code{print-circle}
1523 to a non-@code{nil} value.  @xref{Output Variables}.
1525 @node Type Predicates
1526 @section Type Predicates
1527 @cindex predicates
1528 @cindex type checking
1529 @kindex wrong-type-argument
1531   The Emacs Lisp interpreter itself does not perform type checking on
1532 the actual arguments passed to functions when they are called.  It could
1533 not do so, since function arguments in Lisp do not have declared data
1534 types, as they do in other programming languages.  It is therefore up to
1535 the individual function to test whether each actual argument belongs to
1536 a type that the function can use.
1538   All built-in functions do check the types of their actual arguments
1539 when appropriate, and signal a @code{wrong-type-argument} error if an
1540 argument is of the wrong type.  For example, here is what happens if you
1541 pass an argument to @code{+} that it cannot handle:
1543 @example
1544 @group
1545 (+ 2 'a)
1546      @error{} Wrong type argument: number-or-marker-p, a
1547 @end group
1548 @end example
1550 @cindex type predicates
1551 @cindex testing types
1552   If you want your program to handle different types differently, you
1553 must do explicit type checking.  The most common way to check the type
1554 of an object is to call a @dfn{type predicate} function.  Emacs has a
1555 type predicate for each type, as well as some predicates for
1556 combinations of types.
1558   A type predicate function takes one argument; it returns @code{t} if
1559 the argument belongs to the appropriate type, and @code{nil} otherwise.
1560 Following a general Lisp convention for predicate functions, most type
1561 predicates' names end with @samp{p}.
1563   Here is an example which uses the predicates @code{listp} to check for
1564 a list and @code{symbolp} to check for a symbol.
1566 @example
1567 (defun add-on (x)
1568   (cond ((symbolp x)
1569          ;; If X is a symbol, put it on LIST.
1570          (setq list (cons x list)))
1571         ((listp x)
1572          ;; If X is a list, add its elements to LIST.
1573          (setq list (append x list)))
1574         (t
1575          ;; We handle only symbols and lists.
1576          (error "Invalid argument %s in add-on" x))))
1577 @end example
1579   Here is a table of predefined type predicates, in alphabetical order,
1580 with references to further information.
1582 @table @code
1583 @item atom
1584 @xref{List-related Predicates, atom}.
1586 @item arrayp
1587 @xref{Array Functions, arrayp}.
1589 @item bool-vector-p
1590 @xref{Bool-Vectors, bool-vector-p}.
1592 @item bufferp
1593 @xref{Buffer Basics, bufferp}.
1595 @item byte-code-function-p
1596 @xref{Byte-Code Type, byte-code-function-p}.
1598 @item case-table-p
1599 @xref{Case Tables, case-table-p}.
1601 @item char-or-string-p
1602 @xref{Predicates for Strings, char-or-string-p}.
1604 @item char-table-p
1605 @xref{Char-Tables, char-table-p}.
1607 @item commandp
1608 @xref{Interactive Call, commandp}.
1610 @item consp
1611 @xref{List-related Predicates, consp}.
1613 @item display-table-p
1614 @xref{Display Tables, display-table-p}.
1616 @item floatp
1617 @xref{Predicates on Numbers, floatp}.
1619 @item frame-configuration-p
1620 @xref{Frame Configurations, frame-configuration-p}.
1622 @item frame-live-p
1623 @xref{Deleting Frames, frame-live-p}.
1625 @item framep
1626 @xref{Frames, framep}.
1628 @item functionp
1629 @xref{Functions, functionp}.
1631 @item integer-or-marker-p
1632 @xref{Predicates on Markers, integer-or-marker-p}.
1634 @item integerp
1635 @xref{Predicates on Numbers, integerp}.
1637 @item keymapp
1638 @xref{Creating Keymaps, keymapp}.
1640 @item keywordp
1641 @xref{Constant Variables}.
1643 @item listp
1644 @xref{List-related Predicates, listp}.
1646 @item markerp
1647 @xref{Predicates on Markers, markerp}.
1649 @item wholenump
1650 @xref{Predicates on Numbers, wholenump}.
1652 @item nlistp
1653 @xref{List-related Predicates, nlistp}.
1655 @item numberp
1656 @xref{Predicates on Numbers, numberp}.
1658 @item number-or-marker-p
1659 @xref{Predicates on Markers, number-or-marker-p}.
1661 @item overlayp
1662 @xref{Overlays, overlayp}.
1664 @item processp
1665 @xref{Processes, processp}.
1667 @item sequencep
1668 @xref{Sequence Functions, sequencep}.
1670 @item stringp
1671 @xref{Predicates for Strings, stringp}.
1673 @item subrp
1674 @xref{Function Cells, subrp}.
1676 @item symbolp
1677 @xref{Symbols, symbolp}.
1679 @item syntax-table-p
1680 @xref{Syntax Tables, syntax-table-p}.
1682 @item user-variable-p
1683 @xref{Defining Variables, user-variable-p}.
1685 @item vectorp
1686 @xref{Vectors, vectorp}.
1688 @item window-configuration-p
1689 @xref{Window Configurations, window-configuration-p}.
1691 @item window-live-p
1692 @xref{Deleting Windows, window-live-p}.
1694 @item windowp
1695 @xref{Basic Windows, windowp}.
1696 @end table
1698   The most general way to check the type of an object is to call the
1699 function @code{type-of}.  Recall that each object belongs to one and
1700 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
1701 Data Types}).  But @code{type-of} knows nothing about non-primitive
1702 types.  In most cases, it is more convenient to use type predicates than
1703 @code{type-of}.
1705 @defun type-of object
1706 This function returns a symbol naming the primitive type of
1707 @var{object}.  The value is one of the symbols @code{symbol},
1708 @code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector},
1709 @code{char-table}, @code{bool-vector}, @code{hash-table}, @code{subr},
1710 @code{compiled-function}, @code{marker}, @code{overlay}, @code{window},
1711 @code{buffer}, @code{frame}, @code{process}, or
1712 @code{window-configuration}.
1714 @example
1715 (type-of 1)
1716      @result{} integer
1717 (type-of 'nil)
1718      @result{} symbol
1719 (type-of '())    ; @r{@code{()} is @code{nil}.}
1720      @result{} symbol
1721 (type-of '(x))
1722      @result{} cons
1723 @end example
1724 @end defun
1726 @node Equality Predicates
1727 @section Equality Predicates
1728 @cindex equality
1730   Here we describe two functions that test for equality between any two
1731 objects.  Other functions test equality between objects of specific
1732 types, e.g., strings.  For these predicates, see the appropriate chapter
1733 describing the data type.
1735 @defun eq object1 object2
1736 This function returns @code{t} if @var{object1} and @var{object2} are
1737 the same object, @code{nil} otherwise.  The ``same object'' means that a
1738 change in one will be reflected by the same change in the other.
1740 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
1741 integers with the same value.  Also, since symbol names are normally
1742 unique, if the arguments are symbols with the same name, they are
1743 @code{eq}.  For other types (e.g., lists, vectors, strings), two
1744 arguments with the same contents or elements are not necessarily
1745 @code{eq} to each other: they are @code{eq} only if they are the same
1746 object.
1748 @example
1749 @group
1750 (eq 'foo 'foo)
1751      @result{} t
1752 @end group
1754 @group
1755 (eq 456 456)
1756      @result{} t
1757 @end group
1759 @group
1760 (eq "asdf" "asdf")
1761      @result{} nil
1762 @end group
1764 @group
1765 (eq '(1 (2 (3))) '(1 (2 (3))))
1766      @result{} nil
1767 @end group
1769 @group
1770 (setq foo '(1 (2 (3))))
1771      @result{} (1 (2 (3)))
1772 (eq foo foo)
1773      @result{} t
1774 (eq foo '(1 (2 (3))))
1775      @result{} nil
1776 @end group
1778 @group
1779 (eq [(1 2) 3] [(1 2) 3])
1780      @result{} nil
1781 @end group
1783 @group
1784 (eq (point-marker) (point-marker))
1785      @result{} nil
1786 @end group
1787 @end example
1789 The @code{make-symbol} function returns an uninterned symbol, distinct
1790 from the symbol that is used if you write the name in a Lisp expression.
1791 Distinct symbols with the same name are not @code{eq}.  @xref{Creating
1792 Symbols}.
1794 @example
1795 @group
1796 (eq (make-symbol "foo") 'foo)
1797      @result{} nil
1798 @end group
1799 @end example
1800 @end defun
1802 @defun equal object1 object2
1803 This function returns @code{t} if @var{object1} and @var{object2} have
1804 equal components, @code{nil} otherwise.  Whereas @code{eq} tests if its
1805 arguments are the same object, @code{equal} looks inside nonidentical
1806 arguments to see if their elements or contents are the same.  So, if two
1807 objects are @code{eq}, they are @code{equal}, but the converse is not
1808 always true.
1810 @example
1811 @group
1812 (equal 'foo 'foo)
1813      @result{} t
1814 @end group
1816 @group
1817 (equal 456 456)
1818      @result{} t
1819 @end group
1821 @group
1822 (equal "asdf" "asdf")
1823      @result{} t
1824 @end group
1825 @group
1826 (eq "asdf" "asdf")
1827      @result{} nil
1828 @end group
1830 @group
1831 (equal '(1 (2 (3))) '(1 (2 (3))))
1832      @result{} t
1833 @end group
1834 @group
1835 (eq '(1 (2 (3))) '(1 (2 (3))))
1836      @result{} nil
1837 @end group
1839 @group
1840 (equal [(1 2) 3] [(1 2) 3])
1841      @result{} t
1842 @end group
1843 @group
1844 (eq [(1 2) 3] [(1 2) 3])
1845      @result{} nil
1846 @end group
1848 @group
1849 (equal (point-marker) (point-marker))
1850      @result{} t
1851 @end group
1853 @group
1854 (eq (point-marker) (point-marker))
1855      @result{} nil
1856 @end group
1857 @end example
1859 Comparison of strings is case-sensitive, but does not take account of
1860 text properties---it compares only the characters in the strings.
1861 A unibyte string never equals a multibyte string unless the
1862 contents are entirely @sc{ascii} (@pxref{Text Representations}).
1864 @example
1865 @group
1866 (equal "asdf" "ASDF")
1867      @result{} nil
1868 @end group
1869 @end example
1871 However, two distinct buffers are never considered @code{equal}, even if
1872 their textual contents are the same.
1873 @end defun
1875   The test for equality is implemented recursively; for example, given
1876 two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})}
1877 returns @code{t} if and only if both the expressions below return
1878 @code{t}:
1880 @example
1881 (equal (car @var{x}) (car @var{y}))
1882 (equal (cdr @var{x}) (cdr @var{y}))
1883 @end example
1885 Because of this recursive method, circular lists may therefore cause
1886 infinite recursion (leading to an error).