2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/objects.info
8 @node Lisp Data Types, Numbers, Packaging, Top
9 @chapter Lisp Data Types
15 A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
16 programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of
19 Every object belongs to at least one type. Objects of the same type
20 have similar structures and may usually be used in the same contexts.
21 Types can overlap, and objects can belong to two or more types.
22 Consequently, we can ask whether an object belongs to a particular type,
23 but not for ``the'' type of an object.
25 @cindex primitive type
26 A few fundamental object types are built into SXEmacs. These, from
27 which all other types are constructed, are called @dfn{primitive types}.
28 Each object belongs to one and only one primitive type. These types
29 include @dfn{integer}, @dfn{character} (starting with XEmacs 20.0),
30 @dfn{float}, @dfn{cons}, @dfn{symbol}, @dfn{string}, @dfn{vector},
31 @dfn{bit-vector}, @dfn{subr}, @dfn{compiled-function}, @dfn{hash-table},
32 @dfn{range-table}, @dfn{char-table}, @dfn{weak-list}, and several
33 special types, such as @dfn{buffer}, that are related to editing.
34 (@xref{Editing Types}.)
36 Each primitive type has a corresponding Lisp function that checks
37 whether an object is a member of that type.
39 Note that Lisp is unlike many other languages in that Lisp objects are
40 @dfn{self-typing}: the primitive type of the object is implicit in the
41 object itself. For example, if an object is a vector, nothing can treat
42 it as a number; Lisp knows it is a vector, not a number.
44 In most languages, the programmer must declare the data type of each
45 variable, and the type is known by the compiler but not represented in
46 the data. Such type declarations do not exist in SXEmacs Lisp. A Lisp
47 variable can have any type of value, and it remembers whatever value
48 you store in it, type and all.
50 This chapter describes the purpose, printed representation, and read
51 syntax of each of the standard types in SXEmacs Lisp. Details on how
52 to use these types can be found in later chapters.
55 * Printed Representation:: How Lisp objects are represented as text.
56 * Comments:: Comments and their formatting conventions.
57 * Primitive Types:: List of all primitive types in SXEmacs.
58 * Programming Types:: Types found in all Lisp systems.
59 * Editing Types:: Types specific to SXEmacs.
60 * Window-System Types:: Types specific to windowing systems.
61 * Type Predicates:: Tests related to types.
62 * Equality Predicates:: Tests of equality between any two objects.
66 @node Printed Representation
67 @section Printed Representation and Read Syntax
68 @cindex printed representation
71 The @dfn{printed representation} of an object is the format of the
72 output generated by the Lisp printer (the function @code{prin1}) for
73 that object. The @dfn{read syntax} of an object is the format of the
74 input accepted by the Lisp reader (the function @code{read}) for that
75 object. Most objects have more than one possible read syntax. Some
76 types of object have no read syntax; except for these cases, the printed
77 representation of an object is also a read syntax for it.
79 In other languages, an expression is text; it has no other form. In
80 Lisp, an expression is primarily a Lisp object and only secondarily the
81 text that is the object's read syntax. Often there is no need to
82 emphasize this distinction, but you must keep it in the back of your
83 mind, or you will occasionally be very confused.
86 Every type has a printed representation. Some types have no read
87 syntax, since it may not make sense to enter objects of these types
88 directly in a Lisp program. For example, the buffer type does not have
89 a read syntax. Objects of these types are printed in @dfn{hash
90 notation}: the characters @samp{#<} followed by a descriptive string
91 (typically the type name followed by the name of the object), and closed
92 with a matching @samp{>}. Hash notation cannot be read at all, so the
93 Lisp reader signals the error @code{invalid-read-syntax} whenever it
95 @kindex invalid-read-syntax
99 @result{} #<buffer "objects.texi">
102 When you evaluate an expression interactively, the Lisp interpreter
103 first reads the textual representation of it, producing a Lisp object,
104 and then evaluates that object (@pxref{Evaluation}). However,
105 evaluation and reading are separate activities. Reading returns the
106 Lisp object represented by the text that is read; the object may or may
107 not be evaluated later. @xref{Input Functions}, for a description of
108 @code{read}, the basic function for reading objects.
114 @cindex @samp{;} in comment
116 A @dfn{comment} is text that is written in a program only for the sake
117 of humans that read the program, and that has no effect on the meaning
118 of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
119 is not within a string or character constant. The comment continues to
120 the end of line. The Lisp reader discards comments; they do not become
121 part of the Lisp objects which represent the program within the Lisp
124 The @samp{#@@@var{count}} construct, which skips the next @var{count}
125 characters, is useful for program-generated comments containing binary
126 data. The SXEmacs Lisp byte compiler uses this in its output files
127 (@pxref{Byte Compilation}). It isn't meant for source files, however.
129 @xref{Comment Tips}, for conventions for formatting comments.
132 @node Primitive Types
133 @section Primitive Types
134 @cindex primitive types
136 For reference, here is a list of all the primitive types that may
137 exist in SXEmacs. Note that some of these types may not exist
138 in some SXEmacs executables; that depends on the options that
139 SXEmacs was configured with.
218 In addition, the following special types are created internally
219 but will never be seen by Lisp code. You may encounter them,
220 however, if you are debugging SXEmacs. The printed representation
221 of these objects begins @samp{#<INTERNAL EMACS BUG}, which indicates
222 to the Lisp programmer that he has found an internal bug in SXEmacs
223 if he ever encounters any of these objects.
245 symbol-value-buffer-local
249 symbol-value-lisp-magic
251 symbol-value-varalias
257 @node Programming Types
258 @section Programming Types
259 @cindex programming types
261 There are two general categories of types in SXEmacs Lisp: those having
262 to do with Lisp programming, and those having to do with editing. The
263 former exist in many Lisp implementations, in one form or another. The
264 latter are unique to SXEmacs Lisp.
267 * Integer Type:: Numbers without fractional parts.
268 * Floating Point Type:: Numbers with fractional parts and with a large range.
269 * Character Type:: The representation of letters, numbers and
271 * Symbol Type:: A multi-use object that refers to a function,
272 variable, or property list, and has a unique identity.
273 * Sequence Type:: Both lists and arrays are classified as sequences.
274 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
275 * Array Type:: Arrays include strings and vectors.
276 * String Type:: An (efficient) array of characters.
277 * Vector Type:: One-dimensional arrays.
278 * Bit Vector Type:: An (efficient) array of bits.
279 * Function Type:: A piece of executable code you can call from elsewhere.
280 * Macro Type:: A method of expanding an expression into another
281 expression, more fundamental but less pretty.
282 * Primitive Function Type:: A function written in C, callable from Lisp.
283 * Compiled-Function Type:: A function written in Lisp, then compiled.
284 * Autoload Type:: A type used for automatically loading seldom-used
286 * Char Table Type:: A mapping from characters to Lisp objects.
287 * Hash Table Type:: A fast mapping between Lisp objects.
288 * Range Table Type:: A mapping from ranges of integers to Lisp objects.
289 * Weak List Type:: A list with special garbage-collection properties.
294 @subsection Integer Type
296 The range of values for integers in SXEmacs Lisp is @minus{}134217728 to
297 134217727 (28 bits; i.e.,
311 on most machines. (Some machines, in particular 64-bit machines such as
312 the DEC Alpha, may provide a wider range.) It is important to note that
313 the XEmacs Lisp arithmetic functions do not check for overflow. Thus
314 @code{(1+ 134217727)} is @minus{}134217728 on most machines. (However,
315 you @emph{will} get an error if you attempt to read an out-of-range
316 number using the Lisp reader.)
318 The read syntax for integers is a sequence of (base ten) digits with
319 an optional sign at the beginning. (The printed representation produced
320 by the Lisp interpreter never has a leading @samp{+}.)
324 -1 ; @r{The integer -1.}
325 1 ; @r{The integer 1.}
326 +1 ; @r{Also the integer 1.}
327 268435457 ; @r{Causes an error on a 28-bit implementation.}
331 @xref{Numbers}, for more information.
334 @node Floating Point Type
335 @subsection Floating Point Type
337 SXEmacs supports floating point numbers. The precise range of floating
338 point numbers is machine-specific.
340 The printed representation for floating point numbers requires either
341 a decimal point (with at least one digit following), an exponent, or
342 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
343 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
344 number whose value is 1500. They are all equivalent.
346 @xref{Numbers}, for more information.
350 @subsection Character Type
351 @cindex @sc{ascii} character codes
352 @cindex char-int confoundance disease
354 In XEmacs version 19, and in all versions of FSF GNU Emacs, a
355 @dfn{character} in XEmacs Lisp is nothing more than an integer.
356 This is yet another holdover from XEmacs Lisp's derivation from
357 vintage-1980 Lisps; modern versions of Lisp consider this equivalence
358 a bad idea, and have separate character types. In XEmacs version 20,
359 and of course all SXEmacs versions, the modern convention is followed,
360 and characters are their own primitive types. This change was necessary
361 in order for @sc{mule}, i.e. Asian-language, support to be correctly
364 Even in XEmacs version 20, remnants of the equivalence between
365 characters and integers still exist; this is termed the @dfn{char-int
366 confoundance disease}. In particular, many functions such as @code{eq},
367 @code{equal}, and @code{memq} have equivalent functions (@code{old-eq},
368 @code{old-equal}, @code{old-memq}, etc.) that pretend like characters
369 are integers are the same. Byte code compiled under any version 19
370 Emacs will have all such functions mapped to their @code{old-} equivalents
371 when the byte code is read into XEmacs 20. This is to preserve
372 compatibility---Emacs 19 converts all constant characters to the equivalent
373 integer during byte-compilation, and thus there is no other way to preserve
374 byte-code compatibility even if the code has specifically been written
375 with the distinction between characters and integers in mind.
377 Every character has an equivalent integer, called the @dfn{character
378 code}. For example, the character @kbd{A} is represented as the
379 @w{integer 65}, following the standard @sc{ascii} representation of
380 characters. If SXEmacs was not compiled with @sc{mule} support, the
381 range of this integer will always be 0 to 255---eight bits, or one
382 byte. (Integers outside this range are accepted but silently truncated;
383 however, you should most decidedly @emph{not} rely on this, because it
384 will not work under SXEmacs with @sc{mule} support.) When @sc{mule}
385 support is present, the range of character codes is much
386 larger. (Currently, 19 bits are used.)
388 FSF GNU Emacs uses kludgy character codes above 255 to represent
389 keyboard input of @sc{ascii} characters in combination with certain
390 modifiers. SXEmacs does not use this (a more general mechanism is
391 used that does not distinguish between @sc{ascii} keys and other
392 keys), so you will never find character codes above 255 in a
393 non-@sc{mule} SXEmacs.
395 Individual characters are not often used in programs. It is far more
396 common to work with @emph{strings}, which are sequences composed of
397 characters. @xref{String Type}.
399 @cindex read syntax for characters
400 @cindex printed representation for characters
401 @cindex syntax for characters
403 The read syntax for characters begins with a question mark, followed
404 by the character (if it's printable) or some symbolic representation of
405 it. In SXEmacs and XEmacs 20+, where characters are their own type,
406 this is also the print representation. In XEmacs 19, however, where
407 characters are really integers, the printed representation of a
408 character is a decimal number.
410 This is also a possible read syntax for a character, but writing
411 characters that way in Lisp programs is a very bad idea. You should
412 @emph{always} use the special read syntax formats that SXEmacs Lisp
413 provides for characters.
415 The usual read syntax for alphanumeric characters is a question mark
416 followed by the character; thus, @samp{?A} for the character
417 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
423 ;; @r{Under SXEmacs:}
424 ?Q @result{} ?Q ?q @result{} ?q
425 (char-int ?Q) @result{} 81
426 ;; @r{Under XEmacs 19:}
427 ?Q @result{} 81 ?q @result{} 113
430 You can use the same syntax for punctuation characters, but it is
431 often a good idea to add a @samp{\} so that the SXEmacs commands for
432 editing Lisp code don't get confused. For example, @samp{?\ } is the
433 way to write the space character. If the character is @samp{\}, you
434 @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
436 SXEmacs always prints punctuation characters with a @samp{\} in front of
437 them, to avoid confusion.
440 @cindex bell character
456 You can express the characters Control-g, backspace, tab, newline,
457 vertical tab, formfeed, return, and escape as @samp{?\a}, @samp{?\b},
458 @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e},
459 respectively. Their character codes are 7, 8, 9, 10, 11, 12, 13, and 27
463 ;; @r{Under SXEmacs:}
464 ?\a @result{} ?\^G ; @r{@kbd{C-g}}
465 (char-int ?\a) @result{} 7
466 ?\b @result{} ?\^H ; @r{backspace, @key{BS}, @kbd{C-h}}
467 (char-int ?\b) @result{} 8
468 ?\t @result{} ?\t ; @r{tab, @key{TAB}, @kbd{C-i}}
469 (char-int ?\t) @result{} 9
470 ?\n @result{} ?\n ; @r{newline, @key{LFD}, @kbd{C-j}}
471 ?\v @result{} ?\^K ; @r{vertical tab, @kbd{C-k}}
472 ?\f @result{} ?\^L ; @r{formfeed character, @kbd{C-l}}
473 ?\r @result{} ?\r ; @r{carriage return, @key{RET}, @kbd{C-m}}
474 ?\e @result{} ?\^[ ; @r{escape character, @key{ESC}, @kbd{C-[}}
475 ?\\ @result{} ?\\ ; @r{backslash character, @kbd{\}}
476 ;; @r{Under XEmacs 19:}
477 ?\a @result{} 7 ; @r{@kbd{C-g}}
478 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
479 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
480 ?\n @result{} 10 ; @r{newline, @key{LFD}, @kbd{C-j}}
481 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
482 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
483 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
484 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
485 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
488 @cindex escape sequence
489 These sequences which start with backslash are also known as
490 @dfn{escape sequences}, because backslash plays the role of an escape
491 character; this usage has nothing to do with the character @key{ESC}.
493 @cindex control characters
494 Control characters may be represented using yet another read syntax.
495 This consists of a question mark followed by a backslash, caret, and the
496 corresponding non-control character, in either upper or lower case. For
497 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
498 character @kbd{C-i}, the character whose value is 9.
500 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
501 equivalent to @samp{?\^I} and to @samp{?\^i}:
504 ;; @r{Under SXEmacs:}
505 ?\^I @result{} ?\t ?\C-I @result{} ?\t
506 (char-int ?\^I) @result{} 9
507 ;; @r{Under XEmacs 19:}
508 ?\^I @result{} 9 ?\C-I @result{} 9
511 There is also a character read syntax beginning with @samp{\M-}. This
512 sets the high bit of the character code (same as adding 128 to the
513 character code). For example, @samp{?\M-A} stands for the character
514 with character code 193, or 128 plus 65. You should @emph{not} use this
515 syntax in your programs. It is a holdover of yet another confoundance
516 disease from earlier Emacsen. (This was used to represent keyboard input
517 with the @key{META} key set, thus the @samp{M}; however, it conflicts
518 with the legitimate @sc{iso}-8859-1 interpretation of the character code.
519 For example, character code 193 is a lowercase @samp{a} with an acute
520 accent, in @sc{iso}-8859-1.)
522 @ignore @c None of this crap applies to SXEmacs nor XEmacs.
523 For use in strings and buffers, you are limited to the control
524 characters that exist in @sc{ascii}, but for keyboard input purposes,
525 you can turn any character into a control character with @samp{C-}. The
526 character codes for these non-@sc{ascii} control characters include the
533 bit as well as the code for the corresponding non-control
534 character. Ordinary terminals have no way of generating non-@sc{ASCII}
535 control characters, but you can generate them straightforwardly using an
538 For historical reasons, Emacs treats the @key{DEL} character as
539 the control equivalent of @kbd{?}:
542 ?\^? @result{} 127 ?\C-? @result{} 127
546 As a result, it is currently not possible to represent the character
547 @kbd{Control-?}, which is a meaningful input character under X. It is
548 not easy to change this as various Lisp files refer to @key{DEL} in this
551 For representing control characters to be found in files or strings,
552 we recommend the @samp{^} syntax; for control characters in keyboard
553 input, we prefer the @samp{C-} syntax. This does not affect the meaning
554 of the program, but may guide the understanding of people who read it.
556 @cindex meta characters
557 A @dfn{meta character} is a character typed with the @key{META}
558 modifier key. The integer that represents such a character has the
565 bit set (which on most machines makes it a negative number). We
566 use high bits for this and other modifiers to make possible a wide range
567 of basic character codes.
576 bit indicates a meta character, so the meta
577 characters that can fit in a string have codes in the range from 128 to
578 255, and are the meta versions of the ordinary @sc{ASCII} characters.
579 (In Emacs versions 18 and older, this convention was used for characters
580 outside of strings as well.)
582 The read syntax for meta characters uses @samp{\M-}. For example,
583 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
584 octal character codes (see below), with @samp{\C-}, or with any other
585 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
586 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
587 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
589 The case of an ordinary letter is indicated by its character code as
590 part of @sc{ASCII}, but @sc{ASCII} has no way to represent whether a
591 control character is upper case or lower case. Emacs uses the
598 bit to indicate that the shift key was used for typing a control
599 character. This distinction is possible only when you use X terminals
600 or other special terminals; ordinary terminals do not indicate the
601 distinction to the computer in any way.
603 @cindex hyper characters
604 @cindex super characters
605 @cindex alt characters
606 The X Window System defines three other modifier bits that can be set
607 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
608 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus,
609 @samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
612 bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
616 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
620 @cindex @samp{?} in character constant
621 @cindex question mark in character constant
622 @cindex @samp{\} in character constant
623 @cindex backslash in character constant
624 @cindex octal character code
625 Finally, the most general read syntax consists of a question mark
626 followed by a backslash and the character code in octal (up to three
627 octal digits); thus, @samp{?\101} for the character @kbd{A},
628 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
629 character @kbd{C-b}. Although this syntax can represent any @sc{ascii}
630 character, it is preferred only when the precise octal value is more
631 important than the @sc{ascii} representation.
635 ;; @r{Under SXEmacs:}
636 ?\012 @result{} ?\n ?\n @result{} ?\n ?\C-j @result{} ?\n
637 ?\101 @result{} ?A ?A @result{} ?A
640 ;; @r{Under XEmacs 19:}
641 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
642 ?\101 @result{} 65 ?A @result{} 65
646 A backslash is allowed, and harmless, preceding any character without
647 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
648 There is no reason to add a backslash before most characters. However,
649 you should add a backslash before any of the characters
650 @samp{()\|;'`"#.,} to avoid confusing the SXEmacs commands for editing
651 Lisp code. Also add a backslash before whitespace characters such as
652 space, tab, newline and formfeed. However, it is cleaner to use one of
653 the easily readable escape sequences, such as @samp{\t}, instead of an
654 actual whitespace character such as a tab.
658 @subsection Symbol Type
660 A @dfn{symbol} in SXEmacs Lisp is an object with a name. The symbol
661 name serves as the printed representation of the symbol. In ordinary
662 use, the name is unique---no two symbols have the same name.
664 A symbol can serve as a variable, as a function name, or to hold a
665 property list. Or it may serve only to be distinct from all other Lisp
666 objects, so that its presence in a data structure may be recognized
667 reliably. In a given context, usually only one of these uses is
668 intended. But you can use one symbol in all of these ways,
671 @cindex @samp{\} in symbols
672 @cindex backslash in symbols
673 A symbol name can contain any characters whatever. Most symbol names
674 are written with letters, digits, and the punctuation characters
675 @samp{-+=*/}. Such names require no special punctuation; the characters
676 of the name suffice as long as the name does not look like a number.
677 (If it does, write a @samp{\} at the beginning of the name to force
678 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}} are
679 less often used but also require no special punctuation. Any other
680 characters may be included in a symbol's name by escaping them with a
681 backslash. In contrast to its use in strings, however, a backslash in
682 the name of a symbol simply quotes the single character that follows the
683 backslash. For example, in a string, @samp{\t} represents a tab
684 character; in the name of a symbol, however, @samp{\t} merely quotes the
685 letter @kbd{t}. To have a symbol with a tab character in its name, you
686 must actually use a tab (preceded with a backslash). But it's rare to
689 @cindex CL note---case of letters
691 @b{Common Lisp note:} In Common Lisp, lower case letters are always
692 ``folded'' to upper case, unless they are explicitly escaped. In SXEmacs
693 Lisp, upper case and lower case letters are distinct.
696 Here are several examples of symbol names. Note that the @samp{+} in
697 the fifth example is escaped to prevent it from being read as a number.
698 This is not necessary in the sixth example because the rest of the name
699 makes it invalid as a number.
703 foo ; @r{A symbol named @samp{foo}.}
704 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
705 char-to-string ; @r{A symbol named @samp{char-to-string}.}
708 1+ ; @r{A symbol named @samp{1+}}
709 ; @r{(not @samp{+1}, which is an integer).}
712 \+1 ; @r{A symbol named @samp{+1}}
713 ; @r{(not a very readable name).}
716 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
717 @c the @'s in this next line use up three characters, hence the
718 @c apparent misalignment of the comment.
719 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
720 ; @r{These characters need not be escaped.}
726 @subsection Sequence Types
728 A @dfn{sequence} is a Lisp object that represents an ordered set of
729 elements. There are two kinds of sequence in SXEmacs Lisp, lists and
730 arrays. Thus, an object of type list or of type array is also
731 considered a sequence.
733 Arrays are further subdivided into strings, vectors, and bit vectors.
734 Vectors can hold elements of any type, but string elements must be
735 characters, and bit vector elements must be either 0 or 1. However, the
736 characters in a string can have extents (@pxref{Extents}) and text
737 properties (@pxref{Text Properties}) like characters in a buffer;
738 vectors do not support extents or text properties even when their
739 elements happen to be characters.
741 Lists, strings, vectors, and bit vectors are different, but they have
742 important similarities. For example, all have a length @var{l}, and all
743 have elements which can be indexed from zero to @var{l} minus one.
744 Also, several functions, called sequence functions, accept any kind of
745 sequence. For example, the function @code{elt} can be used to extract
746 an element of a sequence, given its index. @xref{Sequences Arrays
749 It is impossible to read the same sequence twice, since sequences are
750 always created anew upon reading. If you read the read syntax for a
751 sequence twice, you get two sequences with equal contents. There is one
752 exception: the empty list @code{()} always stands for the same object,
757 @subsection Cons Cell and List Types
758 @cindex address field of register
759 @cindex decrement field of register
761 A @dfn{cons cell} is an object comprising two pointers named the
762 @sc{car} and the @sc{cdr}. Each of them can point to any Lisp object.
764 A @dfn{list} is a series of cons cells, linked together so that the
765 @sc{cdr} of each cons cell points either to another cons cell or to the
766 empty list. @xref{Lists}, for functions that work on lists. Because
767 most cons cells are used as part of lists, the phrase @dfn{list
768 structure} has come to refer to any structure made out of cons cells.
770 The names @sc{car} and @sc{cdr} have only historical meaning now. The
771 original Lisp implementation ran on an @w{IBM 704} computer which
772 divided words into two parts, called the ``address'' part and the
773 ``decrement''; @sc{car} was an instruction to extract the contents of
774 the address part of a register, and @sc{cdr} an instruction to extract
775 the contents of the decrement. By contrast, ``cons cells'' are named
776 for the function @code{cons} that creates them, which in turn is named
777 for its purpose, the construction of cells.
780 Because cons cells are so central to Lisp, we also have a word for
781 ``an object which is not a cons cell''. These objects are called
785 The read syntax and printed representation for lists are identical, and
786 consist of a left parenthesis, an arbitrary number of elements, and a
789 Upon reading, each object inside the parentheses becomes an element
790 of the list. That is, a cons cell is made for each element. The
791 @sc{car} of the cons cell points to the element, and its @sc{cdr} points
792 to the next cons cell of the list, which holds the next element in the
793 list. The @sc{cdr} of the last cons cell is set to point to @code{nil}.
795 @cindex box diagrams, for lists
796 @cindex diagrams, boxed, for lists
797 A list can be illustrated by a diagram in which the cons cells are
798 shown as pairs of boxes. (The Lisp reader cannot read such an
799 illustration; unlike the textual notation, which can be understood by
800 both humans and computers, the box illustrations can be understood only
801 by humans.) The following represents the three-element list @code{(rose
806 ___ ___ ___ ___ ___ ___
807 |___|___|--> |___|___|--> |___|___|--> nil
810 --> rose --> violet --> buttercup
814 In this diagram, each box represents a slot that can refer to any Lisp
815 object. Each pair of boxes represents a cons cell. Each arrow is a
816 reference to a Lisp object, either an atom or another cons cell.
818 In this example, the first box, the @sc{car} of the first cons cell,
819 refers to or ``contains'' @code{rose} (a symbol). The second box, the
820 @sc{cdr} of the first cons cell, refers to the next pair of boxes, the
821 second cons cell. The @sc{car} of the second cons cell refers to
822 @code{violet} and the @sc{cdr} refers to the third cons cell. The
823 @sc{cdr} of the third (and last) cons cell refers to @code{nil}.
825 Here is another diagram of the same list, @code{(rose violet
826 buttercup)}, sketched in a different manner:
830 --------------- ---------------- -------------------
831 | car | cdr | | car | cdr | | car | cdr |
832 | rose | o-------->| violet | o-------->| buttercup | nil |
834 --------------- ---------------- -------------------
838 @cindex @samp{(@dots{})} in lists
839 @cindex @code{nil} in lists
841 A list with no elements in it is the @dfn{empty list}; it is identical
842 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
845 Here are examples of lists written in Lisp syntax:
848 (A 2 "A") ; @r{A list of three elements.}
849 () ; @r{A list of no elements (the empty list).}
850 nil ; @r{A list of no elements (the empty list).}
851 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
852 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
853 (A nil) ; @r{Equivalent to the previous.}
854 ((A B C)) ; @r{A list of one element}
855 ; @r{(which is a list of three elements).}
858 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
859 depicted with boxes and arrows:
864 |___|___|--> |___|___|--> nil
872 * Dotted Pair Notation:: An alternative syntax for lists.
873 * Association List Type:: A specially constructed list.
877 @node Dotted Pair Notation
878 @subsubsection Dotted Pair Notation
879 @cindex dotted pair notation
880 @cindex @samp{.} in lists
882 @dfn{Dotted pair notation} is an alternative syntax for cons cells
883 that represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
884 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
885 the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted
886 pair notation is therefore more general than list syntax. In the dotted
887 pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
888 . nil)))}. For @code{nil}-terminated lists, the two notations produce
889 the same result, but list notation is usually clearer and more
890 convenient when it is applicable. When printing a list, the dotted pair
891 notation is only used if the @sc{cdr} of a cell is not a list.
893 Here's how box notation can illustrate dotted pairs. This example
894 shows the pair @code{(rose . violet)}:
906 Dotted pair notation can be combined with list notation to represent a
907 chain of cons cells with a non-@code{nil} final @sc{cdr}. For example,
908 @code{(rose violet . buttercup)} is equivalent to @code{(rose . (violet
909 . buttercup))}. The object looks like this:
914 |___|___|--> |___|___|--> buttercup
921 These diagrams make it evident why @w{@code{(rose .@: violet .@:
922 buttercup)}} is invalid syntax; it would require a cons cell that has
923 three parts rather than two.
925 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}
931 |___|___|--> |___|___|--> nil
938 Similarly, the three-element list @code{(rose violet buttercup)}
939 is equivalent to @code{(rose . (violet . (buttercup)))}.
945 ___ ___ ___ ___ ___ ___
946 |___|___|--> |___|___|--> |___|___|--> nil
949 --> rose --> violet --> buttercup
955 @node Association List Type
956 @subsubsection Association List Type
958 An @dfn{association list} or @dfn{alist} is a specially-constructed
959 list whose elements are cons cells. In each element, the @sc{car} is
960 considered a @dfn{key}, and the @sc{cdr} is considered an
961 @dfn{associated value}. (In some cases, the associated value is stored
962 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
963 stacks, since it is easy to add or remove associations at the front of
969 (setq alist-of-colors
970 '((rose . red) (lily . white) (buttercup . yellow)))
974 sets the variable @code{alist-of-colors} to an alist of three elements. In the
975 first element, @code{rose} is the key and @code{red} is the value.
977 @xref{Association Lists}, for a further explanation of alists and for
978 functions that work on alists.
982 @subsection Array Type
984 An @dfn{array} is composed of an arbitrary number of slots for
985 referring to other Lisp objects, arranged in a contiguous block of
986 memory. Accessing any element of an array takes the same amount of
987 time. In contrast, accessing an element of a list requires time
988 proportional to the position of the element in the list. (Elements at
989 the end of a list take longer to access than elements at the beginning
992 SXEmacs defines three types of array, strings, vectors, and bit
993 vectors. A string is an array of characters, a vector is an array of
994 arbitrary objects, and a bit vector is an array of 1's and 0's. All are
995 one-dimensional. (Most other programming languages support
996 multidimensional arrays, but they are not essential; you can get the
997 same effect with an array of arrays.) Each type of array has its own
998 read syntax; see @ref{String Type}, @ref{Vector Type}, and @ref{Bit
1001 An array may have any length up to the largest integer; but once
1002 created, it has a fixed size. The first element of an array has index
1003 zero, the second element has index 1, and so on. This is called
1004 @dfn{zero-origin} indexing. For example, an array of four elements has
1005 indices 0, 1, 2, @w{and 3}.
1007 The array type is contained in the sequence type and contains the
1008 string type, the vector type, and the bit vector type.
1012 @subsection String Type
1014 A @dfn{string} is an array of characters. Strings are used for many
1015 purposes in SXEmacs, as can be expected in a text editor; for example, as
1016 the names of Lisp symbols, as messages for the user, and to represent
1017 text extracted from buffers. Strings in Lisp are constants: evaluation
1018 of a string returns the same string.
1020 @cindex @samp{"} in strings
1021 @cindex double-quote in strings
1022 @cindex @samp{\} in strings
1023 @cindex backslash in strings
1024 The read syntax for strings is a double-quote, an arbitrary number of
1025 characters, and another double-quote, @code{"like this"}. The Lisp
1026 reader accepts the same formats for reading the characters of a string
1027 as it does for reading single characters (without the question mark that
1028 begins a character literal). You can enter a nonprinting character such
1029 as tab or @kbd{C-a} using the convenient escape sequences, like this:
1030 @code{"\t, \C-a"}. You can include a double-quote in a string by
1031 preceding it with a backslash; thus, @code{"\""} is a string containing
1032 just a single double-quote character. (@xref{Character Type}, for a
1033 description of the read syntax for characters.)
1035 @ignore @c More ill-conceived FSF Emacs crap.
1036 If you use the @samp{\M-} syntax to indicate a meta character in a
1037 string constant, this sets the
1044 bit of the character in the string.
1045 This is not the same representation that the meta modifier has in a
1046 character on its own (not inside a string). @xref{Character Type}.
1048 Strings cannot hold characters that have the hyper, super, or alt
1049 modifiers; they can hold @sc{ASCII} control characters, but no others.
1050 They do not distinguish case in @sc{ASCII} control characters.
1053 The printed representation of a string consists of a double-quote, the
1054 characters it contains, and another double-quote. However, you must
1055 escape any backslash or double-quote characters in the string with a
1056 backslash, like this: @code{"this \" is an embedded quote"}.
1058 An alternative syntax allows insertion of raw backslashes into a
1059 string, like this: @code{#r"this \ is an embedded backslash"}. In such
1060 a string, each character following a backslash is included literally in
1061 the string, and all backslashes are left in the string. This means that
1062 @code{#r"\""} is a valid string literal with two characters, a backslash and a
1063 double-quote. It also means that a string with this syntax @emph{cannot end
1064 in a single backslash}.
1066 The newline character is not special in the read syntax for strings;
1067 if you write a new line between the double-quotes, it becomes a
1068 character in the string. But an escaped newline---one that is preceded
1069 by @samp{\}---does not become part of the string; i.e., the Lisp reader
1070 ignores an escaped newline while reading a string.
1071 @cindex newline in strings
1074 "It is useful to include newlines
1075 in documentation strings,
1076 but the newline is \
1077 ignored if escaped."
1078 @result{} "It is useful to include newlines
1079 in documentation strings,
1080 but the newline is ignored if escaped."
1083 A string can hold extents and properties of the text it contains, in
1084 addition to the characters themselves. This enables programs that copy
1085 text between strings and buffers to preserve the extents and properties
1086 with no special effort. @xref{Extents}, @xref{Text Properties}.
1088 Note that FSF GNU Emacs has a special read and print syntax for
1089 strings with text properties, but SXEmacs does not currently implement
1090 this. It was judged better not to include this in SXEmacs because it
1091 entails that @code{equal} return @code{nil} when passed a string with
1092 text properties and the equivalent string without text properties, which
1093 is often counter-intuitive.
1095 @ignore @c Not in SXEmacs nor XEmacs
1097 properties have a special read and print syntax:
1100 #("@var{characters}" @var{property-data}...)
1104 where @var{property-data} consists of zero or more elements, in groups
1105 of three as follows:
1108 @var{start} @var{end} @var{plist}
1112 The elements @var{start} and @var{end} are integers, and together specify
1113 a range of indices in the string; @var{plist} is the property list for
1117 @xref{Strings and Characters}, for functions that work on strings.
1121 @subsection Vector Type
1123 A @dfn{vector} is a one-dimensional array of elements of any type. It
1124 takes a constant amount of time to access any element of a vector. (In
1125 a list, the access time of an element is proportional to the distance of
1126 the element from the beginning of the list.)
1128 The printed representation of a vector consists of a left square
1129 bracket, the elements, and a right square bracket. This is also the
1130 read syntax. Like numbers and strings, vectors are considered constants
1134 [1 "two" (three)] ; @r{A vector of three elements.}
1135 @result{} [1 "two" (three)]
1138 @xref{Vectors}, for functions that work with vectors.
1141 @node Bit Vector Type
1142 @subsection Bit Vector Type
1144 A @dfn{bit vector} is a one-dimensional array of 1's and 0's. It
1145 takes a constant amount of time to access any element of a bit vector,
1146 as for vectors. Bit vectors have an extremely compact internal
1147 representation (one machine bit per element), which makes them ideal
1148 for keeping track of unordered sets, large collections of boolean values,
1151 The printed representation of a bit vector consists of @samp{#*}
1152 followed by the bits in the vector. This is also the read syntax. Like
1153 numbers, strings, and vectors, bit vectors are considered constants for
1157 #*00101000 ; @r{A bit vector of eight elements.}
1158 @result{} #*00101000
1161 @xref{Bit Vectors}, for functions that work with bit vectors.
1165 @subsection Function Type
1167 Just as functions in other programming languages are executable,
1168 @dfn{Lisp function} objects are pieces of executable code. However,
1169 functions in Lisp are primarily Lisp objects, and only secondarily the
1170 text which represents them. These Lisp objects are lambda expressions:
1171 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
1174 In most programming languages, it is impossible to have a function
1175 without a name. In Lisp, a function has no intrinsic name. A lambda
1176 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
1177 Functions}). A named function in Lisp is actually a symbol with a valid
1178 function in its function cell (@pxref{Defining Functions}).
1180 Most of the time, functions are called when their names are written in
1181 Lisp expressions in Lisp programs. However, you can construct or obtain
1182 a function object at run time and then call it with the primitive
1183 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
1187 @subsection Macro Type
1189 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
1190 language. It is represented as an object much like a function, but with
1191 different parameter-passing semantics. A Lisp macro has the form of a
1192 list whose first element is the symbol @code{macro} and whose @sc{cdr}
1193 is a Lisp function object, including the @code{lambda} symbol.
1195 Lisp macro objects are usually defined with the built-in
1196 @code{defmacro} function, but any list that begins with @code{macro} is
1197 a macro as far as SXEmacs is concerned. @xref{Macros}, for an explanation
1198 of how to write a macro.
1201 @node Primitive Function Type
1202 @subsection Primitive Function Type
1203 @cindex special forms
1205 A @dfn{primitive function} is a function callable from Lisp but
1206 written in the C programming language. Primitive functions are also
1207 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
1208 derived from ``subroutine''.) Most primitive functions evaluate all
1209 their arguments when they are called. A primitive function that does
1210 not evaluate all its arguments is called a @dfn{special form}
1211 (@pxref{Special Forms}).@refill
1213 It does not matter to the caller of a function whether the function is
1214 primitive. However, this does matter if you try to substitute a
1215 function written in Lisp for a primitive of the same name. The reason
1216 is that the primitive function may be called directly from C code.
1217 Calls to the redefined function from Lisp will use the new definition,
1218 but calls from C code may still use the built-in definition.
1220 The term @dfn{function} refers to all SXEmacs functions, whether
1221 written in Lisp or C. @xref{Function Type}, for information about the
1222 functions written in Lisp.
1224 Primitive functions have no read syntax and print in hash notation
1225 with the name of the subroutine.
1229 (symbol-function 'car) ; @r{Access the function cell}
1230 ; @r{of the symbol.}
1231 @result{} #<subr car>
1232 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
1233 @result{} t ; @r{Yes.}
1238 @node Compiled-Function Type
1239 @subsection Compiled-Function Type
1241 The byte compiler produces @dfn{compiled-function objects}. The
1242 evaluator handles this data type specially when it appears as a function
1243 to be called. @xref{Byte Compilation}, for information about the byte
1246 The printed representation for a compiled-function object is normally
1247 @samp{#<compiled-function...>}. If @code{print-readably} is true,
1248 however, it is @samp{#[...]}.
1252 @subsection Autoload Type
1254 An @dfn{autoload object} is a list whose first element is the symbol
1255 @code{autoload}. It is stored as the function definition of a symbol as
1256 a placeholder for the real definition; it says that the real definition
1257 is found in a file of Lisp code that should be loaded when necessary.
1258 The autoload object contains the name of the file, plus some other
1259 information about the real definition.
1261 After the file has been loaded, the symbol should have a new function
1262 definition that is not an autoload object. The new definition is then
1263 called as if it had been there to begin with. From the user's point of
1264 view, the function call works as expected, using the function definition
1267 An autoload object is usually created with the function
1268 @code{autoload}, which stores the object in the function cell of a
1269 symbol. @xref{Autoload}, for more details.
1272 @node Char Table Type
1273 @subsection Char Table Type
1274 @cindex char table type
1276 (not yet documented)
1279 @node Hash Table Type
1280 @subsection Hash Table Type
1281 @cindex hash table type
1283 A @dfn{hash table} is a table providing an arbitrary mapping from
1284 one Lisp object to another, using an internal indexing method
1285 called @dfn{hashing}. Hash tables are very fast (much more efficient
1286 that using an association list, when there are a large number of
1287 elements in the table).
1289 Hash tables have a special read syntax beginning with
1290 @samp{#s(hash-table} (this is an example of @dfn{structure} read
1291 syntax. This notation is also used for printing when
1292 @code{print-readably} is @code{t}.
1294 Otherwise they print in hash notation (The ``hash'' in ``hash notation''
1295 has nothing to do with the ``hash'' in ``hash table''), giving the
1296 number of elements, total space allocated for elements, and a unique
1297 number assigned at the time the hash table was created. (Hash tables
1298 automatically resize as necessary so there is no danger of running out
1299 of space for elements.)
1303 (make-hash-table :size 50)
1304 @result{} #<hash-table 0/107 0x313a>
1308 @xref{Hash Tables}, for information on how to create and work with hash
1312 @node Range Table Type
1313 @subsection Range Table Type
1314 @cindex range table type
1316 A @dfn{range table} is a table that maps from ranges of integers to
1317 arbitrary Lisp objects. Range tables automatically combine overlapping
1318 ranges that map to the same Lisp object, and operations are provided
1319 for mapping over all of the ranges in a range table.
1321 Range tables have a special read syntax beginning with
1322 @samp{#s(range-table} (this is an example of @dfn{structure} read syntax,
1323 which is also used for char tables and faces).
1327 (setq x (make-range-table))
1328 (put-range-table 20 50 'foo x)
1329 (put-range-table 100 200 "bar" x)
1331 @result{} #s(range-table data ((20 50) foo (100 200) "bar"))
1335 @xref{Range Tables}, for information on how to create and work with range
1339 @node Weak List Type
1340 @subsection Weak List Type
1341 @cindex weak list type
1343 (not yet documented)
1347 @section Editing Types
1348 @cindex editing types
1350 The types in the previous section are common to many Lisp dialects.
1351 SXEmacs Lisp provides several additional data types for purposes connected
1355 * Buffer Type:: The basic object of editing.
1356 * Marker Type:: A position in a buffer.
1357 * Extent Type:: A range in a buffer or string, maybe with properties.
1358 * Window Type:: Buffers are displayed in windows.
1359 * Frame Type:: Windows subdivide frames.
1360 * Device Type:: Devices group all frames on a display.
1361 * Console Type:: Consoles group all devices with the same keyboard.
1362 * Window Configuration Type:: Recording the way a frame is subdivided.
1363 * Event Type:: An interesting occurrence in the system.
1364 * Process Type:: A process running on the underlying OS.
1365 * Stream Type:: Receive or send characters.
1366 * Keymap Type:: What function a keystroke invokes.
1367 * Syntax Table Type:: What a character means.
1368 * Display Table Type:: How display tables are represented.
1369 * Database Type:: A connection to an external DBM or DB database.
1370 * Charset Type:: A character set (e.g. all Kanji characters),
1372 * Coding System Type:: An object encapsulating a way of converting between
1373 different textual encodings, under SXEmacs/MULE.
1378 @subsection Buffer Type
1380 A @dfn{buffer} is an object that holds text that can be edited
1381 (@pxref{Buffers}). Most buffers hold the contents of a disk file
1382 (@pxref{Files}) so they can be edited, but some are used for other
1383 purposes. Most buffers are also meant to be seen by the user, and
1384 therefore displayed, at some time, in a window (@pxref{Windows}). But a
1385 buffer need not be displayed in any window.
1387 The contents of a buffer are much like a string, but buffers are not
1388 used like strings in SXEmacs Lisp, and the available operations are
1389 different. For example, insertion of text into a buffer is very
1390 efficient, whereas ``inserting'' text into a string requires
1391 concatenating substrings, and the result is an entirely new string
1394 Each buffer has a designated position called @dfn{point}
1395 (@pxref{Positions}). At any time, one buffer is the @dfn{current
1396 buffer}. Most editing commands act on the contents of the current
1397 buffer in the neighborhood of point. Many of the standard SXEmacs
1398 functions manipulate or test the characters in the current buffer; a
1399 whole chapter in this manual is devoted to describing these functions
1402 Several other data structures are associated with each buffer:
1406 a local syntax table (@pxref{Syntax Tables});
1409 a local keymap (@pxref{Keymaps});
1412 a local variable binding list (@pxref{Buffer-Local Variables});
1415 a list of extents (@pxref{Extents});
1418 and various other related properties.
1422 The local keymap and variable list contain entries that individually
1423 override global bindings or values. These are used to customize the
1424 behavior of programs in different buffers, without actually changing the
1427 A buffer may be @dfn{indirect}, which means it shares the text
1428 of another buffer. @xref{Indirect Buffers}.
1430 Buffers have no read syntax. They print in hash notation, showing the
1436 @result{} #<buffer "objects.texi">
1442 @subsection Marker Type
1444 A @dfn{marker} denotes a position in a specific buffer. Markers
1445 therefore have two components: one for the buffer, and one for the
1446 position. Changes in the buffer's text automatically relocate the
1447 position value as necessary to ensure that the marker always points
1448 between the same two characters in the buffer.
1450 Markers have no read syntax. They print in hash notation, giving the
1451 current character position and the name of the buffer.
1456 @result{} #<marker at 50661 in objects.texi>
1460 @xref{Markers}, for information on how to test, create, copy, and move
1465 @subsection Extent Type
1467 An @dfn{extent} specifies temporary alteration of the display
1468 appearance of a part of a buffer (or string). It contains markers
1469 delimiting a range of the buffer, plus a property list (a list whose
1470 elements are alternating property names and values). Extents are used
1471 to present parts of the buffer temporarily in a different display style.
1472 They have no read syntax, and print in hash notation, giving the buffer
1473 name and range of positions.
1475 Extents can exist over strings as well as buffers; the primary use
1476 of this is to preserve extent and text property information as text
1477 is copied from one buffer to another or between different parts of
1480 Extents have no read syntax. They print in hash notation, giving the
1481 range of text they cover, the name of the buffer or string they are in,
1482 the address in core, and a summary of some of the properties attached to
1488 @result{} #<extent [51742, 51748) font-lock text-prop 0x90121e0 in buffer objects.texi>
1492 @xref{Extents}, for how to create and use extents.
1494 Extents are used to implement text properties. @xref{Text Properties}.
1498 @subsection Window Type
1500 A @dfn{window} describes the portion of the frame that SXEmacs uses to
1501 display a buffer. (In standard window-system usage, a @dfn{window} is
1502 what SXEmacs calls a @dfn{frame}; SXEmacs confusingly uses the term
1503 ``window'' to refer to what is called a @dfn{pane} in standard
1504 window-system usage.) Every window has one associated buffer, whose
1505 contents appear in the window. By contrast, a given buffer may appear
1506 in one window, no window, or several windows.
1508 Though many windows may exist simultaneously, at any time one window
1509 is designated the @dfn{selected window}. This is the window where the
1510 cursor is (usually) displayed when SXEmacs is ready for a command. The
1511 selected window usually displays the current buffer, but this is not
1512 necessarily the case.
1514 Windows are grouped on the screen into frames; each window belongs to
1515 one and only one frame. @xref{Frame Type}.
1517 Windows have no read syntax. They print in hash notation, giving the
1518 name of the buffer being displayed and a unique number assigned at the
1519 time the window was created. (This number can be useful because the
1520 buffer displayed in any given window can change frequently.)
1525 @result{} #<window on "objects.texi" 0x266c>
1529 @xref{Windows}, for a description of the functions that work on windows.
1533 @subsection Frame Type
1535 A @var{frame} is a rectangle on the screen (a @dfn{window} in standard
1536 window-system terminology) that contains one or more non-overlapping
1537 SXEmacs windows (@dfn{panes} in standard window-system terminology). A
1538 frame initially contains a single main window (plus perhaps a minibuffer
1539 window) which you can subdivide vertically or horizontally into smaller
1542 Frames have no read syntax. They print in hash notation, giving the
1543 frame's type, name as used for resourcing, and a unique number assigned
1544 at the time the frame was created.
1549 @result{} #<x-frame "emacs" 0x9db>
1553 @xref{Frames}, for a description of the functions that work on frames.
1557 @subsection Device Type
1559 A @dfn{device} represents a single display on which frames exist.
1560 Normally, there is only one device object, but there may be more
1561 than one if SXEmacs is being run on a multi-headed display (e.g. an
1562 X server with attached color and mono screens) or if SXEmacs is
1563 simultaneously driving frames attached to different consoles, e.g.
1564 an X display and a @sc{tty} connection.
1566 Devices do not have a read syntax. They print in hash notation,
1567 giving the device's type, connection name, and a unique number assigned
1568 at the time the device was created.
1573 @result{} #<x-device on ":0.0" 0x5b9>
1577 @xref{Consoles and Devices}, for a description of several functions
1582 @subsection Console Type
1584 A @dfn{console} represents a single keyboard to which devices
1585 (i.e. displays on which frames exist) are connected. Normally, there is
1586 only one console object, but there may be more than one if SXEmacs is
1587 simultaneously driving frames attached to different X servers and/or
1588 @sc{tty} connections.
1590 SXEmacs is capable of driving multiple X and @sc{tty} connections at the
1591 same time, and provides a robust mechanism for handling the differing
1592 display capabilities of such heterogeneous environments. A buffer with
1593 embedded glyphs and multiple fonts and colors, for example, will display
1594 reasonably if it simultaneously appears on a frame on a color X display,
1595 a frame on a mono X display, and a frame on a @sc{tty} connection.
1597 Consoles do not have a read syntax. They print in hash notation,
1598 giving the console's type, connection name, and a unique number assigned
1599 at the time the console was created.
1604 @result{} #<x-console on "localhost:0" 0x5b7>
1608 @xref{Consoles and Devices}, for a description of several functions
1609 related to consoles.
1612 @node Window Configuration Type
1613 @subsection Window Configuration Type
1614 @cindex screen layout
1616 A @dfn{window configuration} stores information about the positions,
1617 sizes, and contents of the windows in a frame, so you can recreate the
1618 same arrangement of windows later.
1620 Window configurations do not have a read syntax. They print in hash
1621 notation, giving a unique number assigned at the time the window
1622 configuration was created.
1626 (current-window-configuration)
1627 @result{} #<window-configuration 0x2db4>
1631 @xref{Window Configurations}, for a description of several functions
1632 related to window configurations.
1636 @subsection Event Type
1638 (not yet documented)
1642 @subsection Process Type
1644 The word @dfn{process} usually means a running program. SXEmacs itself
1645 runs in a process of this sort. However, in SXEmacs Lisp, a process is a
1646 Lisp object that designates a subprocess created by the SXEmacs process.
1647 Programs such as shells, GDB, ftp, and compilers, running in
1648 subprocesses of SXEmacs, extend the capabilities of SXEmacs.
1650 A SXEmacs subprocess takes textual input from SXEmacs and returns textual
1651 output to SXEmacs for further manipulation. SXEmacs can also send signals
1654 Process objects have no read syntax. They print in hash notation,
1655 giving the name of the process, its associated process ID, and the
1656 current state of the process:
1661 @result{} (#<process "shell" pid 2909 state:run>)
1665 @xref{Processes}, for information about functions that create, delete,
1666 return information about, send input or signals to, and receive output
1671 @subsection Stream Type
1673 A @dfn{stream} is an object that can be used as a source or sink for
1674 characters---either to supply characters for input or to accept them as
1675 output. Many different types can be used this way: markers, buffers,
1676 strings, and functions. Most often, input streams (character sources)
1677 obtain characters from the keyboard, a buffer, or a file, and output
1678 streams (character sinks) send characters to a buffer, such as a
1679 @file{*Help*} buffer, or to the echo area.
1681 The object @code{nil}, in addition to its other meanings, may be used
1682 as a stream. It stands for the value of the variable
1683 @code{standard-input} or @code{standard-output}. Also, the object
1684 @code{t} as a stream specifies input using the minibuffer
1685 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
1688 Streams have no special printed representation or read syntax, and
1689 print as whatever primitive type they are.
1691 @xref{Read and Print}, for a description of functions
1692 related to streams, including parsing and printing functions.
1696 @subsection Keymap Type
1698 A @dfn{keymap} maps keys typed by the user to commands. This mapping
1699 controls how the user's command input is executed.
1701 NOTE: In SXEmacs, a keymap is a separate primitive type. In FSF GNU
1702 Emacs, a keymap is actually a list whose @sc{car} is the symbol
1705 @xref{Keymaps}, for information about creating keymaps, handling prefix
1706 keys, local as well as global keymaps, and changing key bindings.
1709 @node Syntax Table Type
1710 @subsection Syntax Table Type
1712 Under SXEmacs and XEmacs 20+, a @dfn{syntax table} is a particular
1713 type of char table. Under XEmacs 19, a syntax table a vector of 256
1714 integers. In both cases, each element defines how one character is
1715 interpreted when it appears in a buffer. For example, in C mode
1716 (@pxref{Major Modes}), the @samp{+} character is punctuation, but in
1717 Lisp mode it is a valid character in a symbol. These modes specify
1718 different interpretations by changing the syntax table entry for
1721 Syntax tables are used only for scanning text in buffers, not for
1722 reading Lisp expressions. The table the Lisp interpreter uses to read
1723 expressions is built into the SXEmacs source code and cannot be changed;
1724 thus, to change the list delimiters to be @samp{@{} and @samp{@}}
1725 instead of @samp{(} and @samp{)} would be impossible.
1727 @xref{Syntax Tables}, for details about syntax classes and how to make
1728 and modify syntax tables.
1731 @node Display Table Type
1732 @subsection Display Table Type
1734 A @dfn{display table} specifies how to display each character code.
1735 Each buffer and each window can have its own display table. A display
1736 table is actually a vector of length 256, although in SXEmacs and XEmacs
1737 20+ this may change to be a particular type of char table.
1738 @xref{Display Tables}.
1742 @subsection Database Type
1743 @cindex database type
1745 (not yet documented)
1749 @subsection Charset Type
1750 @cindex charset type
1752 (not yet documented)
1755 @node Coding System Type
1756 @subsection Coding System Type
1757 @cindex coding system type
1759 (not yet documented)
1762 @node Window-System Types
1763 @section Window-System Types
1764 @cindex window system types
1766 SXEmacs also has some types that represent objects such as faces
1767 (collections of display characters), fonts, and pixmaps that are
1768 commonly found in windowing systems.
1771 * Face Type:: A collection of display characteristics.
1772 * Glyph Type:: An image appearing in a buffer or elsewhere.
1773 * Specifier Type:: A way of controlling display characteristics on
1774 a per-buffer, -frame, -window, or -device level.
1775 * Font Instance Type:: The way a font appears on a particular device.
1776 * Color Instance Type:: The way a color appears on a particular device.
1777 * Image Instance Type:: The way an image appears on a particular device.
1778 * Toolbar Button Type:: An object representing a button in a toolbar.
1779 * Subwindow Type:: An externally-controlled window-system window
1780 appearing in a buffer.
1781 * X Resource Type:: A miscellaneous X resource, if Epoch support was
1782 compiled into SXEmacs.
1787 @subsection Face Type
1790 (not yet documented)
1794 @subsection Glyph Type
1797 (not yet documented)
1800 @node Specifier Type
1801 @subsection Specifier Type
1802 @cindex specifier type
1804 (not yet documented)
1807 @node Font Instance Type
1808 @subsection Font Instance Type
1809 @cindex font instance type
1811 (not yet documented)
1814 @node Color Instance Type
1815 @subsection Color Instance Type
1816 @cindex color instance type
1818 (not yet documented)
1821 @node Image Instance Type
1822 @subsection Image Instance Type
1823 @cindex image instance type
1825 (not yet documented)
1828 @node Toolbar Button Type
1829 @subsection Toolbar Button Type
1830 @cindex toolbar button type
1832 (not yet documented)
1835 @node Subwindow Type
1836 @subsection Subwindow Type
1837 @cindex subwindow type
1839 (not yet documented)
1842 @node X Resource Type
1843 @subsection X Resource Type
1844 @cindex X resource type
1846 (not yet documented)
1849 @node Type Predicates
1850 @section Type Predicates
1852 @cindex type checking
1853 @kindex wrong-type-argument
1855 The SXEmacs Lisp interpreter itself does not perform type checking on
1856 the actual arguments passed to functions when they are called. It could
1857 not do so, since function arguments in Lisp do not have declared data
1858 types, as they do in other programming languages. It is therefore up to
1859 the individual function to test whether each actual argument belongs to
1860 a type that the function can use.
1862 All built-in functions do check the types of their actual arguments
1863 when appropriate, and signal a @code{wrong-type-argument} error if an
1864 argument is of the wrong type. For example, here is what happens if you
1865 pass an argument to @code{+} that it cannot handle:
1870 @error{} Wrong type argument: integer-or-marker-p, a
1874 @cindex type predicates
1875 @cindex testing types
1876 If you want your program to handle different types differently, you
1877 must do explicit type checking. The most common way to check the type
1878 of an object is to call a @dfn{type predicate} function. SXEmacs has a
1879 type predicate for each type, as well as some predicates for
1880 combinations of types.
1882 A type predicate function takes one argument; it returns @code{t} if
1883 the argument belongs to the appropriate type, and @code{nil} otherwise.
1884 Following a general Lisp convention for predicate functions, most type
1885 predicates' names end with @samp{p}.
1887 Here is an example which uses the predicates @code{listp} to check for
1888 a list and @code{symbolp} to check for a symbol.
1893 ;; If X is a symbol, put it on LIST.
1894 (setq list (cons x list)))
1896 ;; If X is a list, add its elements to LIST.
1897 (setq list (append x list)))
1900 ;; We only handle symbols and lists.
1901 (error "Invalid argument %s in add-on" x))))
1904 Here is a table of predefined type predicates, in alphabetical order,
1905 with references to further information.
1909 @xref{Annotation Primitives, annotationp}.
1912 @xref{Array Functions, arrayp}.
1915 @xref{List-related Predicates, atom}.
1918 @xref{Bit Vector Functions, bit-vector-p}.
1921 @xref{Bit Vector Functions, bitp}.
1923 @item boolean-specifier-p
1924 @xref{Specifier Types, boolean-specifier-p}.
1926 @item buffer-glyph-p
1927 @xref{Glyph Types, buffer-glyph-p}.
1930 @xref{Killing Buffers, buffer-live-p}.
1933 @xref{Buffer Basics, bufferp}.
1935 @item button-event-p
1936 @xref{Event Predicates, button-event-p}.
1938 @item button-press-event-p
1939 @xref{Event Predicates, button-press-event-p}.
1941 @item button-release-event-p
1942 @xref{Event Predicates, button-release-event-p}.
1945 @xref{Case Tables, case-table-p}.
1948 @xref{Character Codes, char-int-p}.
1950 @item char-or-char-int-p
1951 @xref{Character Codes, char-or-char-int-p}.
1953 @item char-or-string-p
1954 @xref{Predicates for Strings, char-or-string-p}.
1957 @xref{Char Tables, char-table-p}.
1960 @xref{Predicates for Characters, characterp}.
1962 @item color-instance-p
1963 @xref{Colors, color-instance-p}.
1965 @item color-pixmap-image-instance-p
1966 @xref{Image Instance Types, color-pixmap-image-instance-p}.
1968 @item color-specifier-p
1969 @xref{Specifier Types, color-specifier-p}.
1972 @xref{Interactive Call, commandp}.
1974 @item compiled-function-p
1975 @xref{Compiled-Function Type, compiled-function-p}.
1977 @item console-live-p
1978 @xref{Connecting to a Console or Device, console-live-p}.
1981 @xref{Consoles and Devices, consolep}.
1984 @xref{List-related Predicates, consp}.
1986 @item database-live-p
1987 @xref{Connecting to a Database, database-live-p}.
1990 @xref{Databases, databasep}.
1993 @xref{Connecting to a Console or Device, device-live-p}.
1995 @item device-or-frame-p
1996 @xref{Basic Device Functions, device-or-frame-p}.
1999 @xref{Consoles and Devices, devicep}.
2002 @xref{Event Predicates, eval-event-p}.
2005 @xref{Event Predicates, event-live-p}.
2008 @xref{Events, eventp}.
2011 @xref{Creating and Modifying Extents, extent-live-p}.
2014 @xref{Extents, extentp}.
2016 @item face-boolean-specifier-p
2017 @xref{Specifier Types, face-boolean-specifier-p}.
2020 @xref{Basic Face Functions, facep}.
2023 @xref{Predicates on Numbers, floatp}.
2025 @item font-instance-p
2026 @xref{Fonts, font-instance-p}.
2028 @item font-specifier-p
2029 @xref{Specifier Types, font-specifier-p}.
2032 @xref{Deleting Frames, frame-live-p}.
2035 @xref{Frames, framep}.
2038 (not yet documented)
2040 @item generic-specifier-p
2041 @xref{Specifier Types, generic-specifier-p}.
2044 @xref{Glyphs, glyphp}.
2047 @xref{Hash Tables, hash-table-p}.
2050 @xref{Glyph Types, icon-glyph-p}.
2052 @item image-instance-p
2053 @xref{Images, image-instance-p}.
2055 @item image-specifier-p
2056 @xref{Specifier Types, image-specifier-p}.
2058 @item integer-char-or-marker-p
2059 @xref{Predicates on Markers, integer-char-or-marker-p}.
2061 @item integer-or-char-p
2062 @xref{Predicates for Characters, integer-or-char-p}.
2064 @item integer-or-marker-p
2065 @xref{Predicates on Markers, integer-or-marker-p}.
2067 @item integer-specifier-p
2068 @xref{Specifier Types, integer-specifier-p}.
2071 @xref{Predicates on Numbers, integerp}.
2074 (not yet documented)
2076 @item key-press-event-p
2077 @xref{Event Predicates, key-press-event-p}.
2080 @xref{Creating Keymaps, keymapp}.
2083 (not yet documented)
2086 @xref{List-related Predicates, listp}.
2089 @xref{Predicates on Markers, markerp}.
2091 @item misc-user-event-p
2092 @xref{Event Predicates, misc-user-event-p}.
2094 @item mono-pixmap-image-instance-p
2095 @xref{Image Instance Types, mono-pixmap-image-instance-p}.
2097 @item motion-event-p
2098 @xref{Event Predicates, motion-event-p}.
2101 @xref{Event Predicates, mouse-event-p}.
2103 @item natnum-specifier-p
2104 @xref{Specifier Types, natnum-specifier-p}.
2107 @xref{Predicates on Numbers, natnump}.
2110 @xref{List-related Predicates, nlistp}.
2112 @item nothing-image-instance-p
2113 @xref{Image Instance Types, nothing-image-instance-p}.
2115 @item number-char-or-marker-p
2116 @xref{Predicates on Markers, number-char-or-marker-p}.
2118 @item number-or-marker-p
2119 @xref{Predicates on Markers, number-or-marker-p}.
2122 @xref{Predicates on Numbers, numberp}.
2124 @item pointer-glyph-p
2125 @xref{Glyph Types, pointer-glyph-p}.
2127 @item pointer-image-instance-p
2128 @xref{Image Instance Types, pointer-image-instance-p}.
2130 @item process-event-p
2131 @xref{Event Predicates, process-event-p}.
2134 @xref{Processes, processp}.
2137 @xref{Range Tables, range-table-p}.
2140 (not yet documented)
2143 @xref{Sequence Functions, sequencep}.
2146 @xref{Specifiers, specifierp}.
2149 @xref{Predicates for Strings, stringp}.
2152 @xref{Function Cells, subrp}.
2154 @item subwindow-image-instance-p
2155 @xref{Image Instance Types, subwindow-image-instance-p}.
2158 @xref{Subwindows, subwindowp}.
2161 @xref{Symbols, symbolp}.
2163 @item syntax-table-p
2164 @xref{Syntax Tables, syntax-table-p}.
2166 @item text-image-instance-p
2167 @xref{Image Instance Types, text-image-instance-p}.
2169 @item timeout-event-p
2170 @xref{Event Predicates, timeout-event-p}.
2172 @item toolbar-button-p
2173 @xref{Toolbar, toolbar-button-p}.
2175 @item toolbar-specifier-p
2176 @xref{Toolbar, toolbar-specifier-p}.
2178 @item user-variable-p
2179 @xref{Defining Variables, user-variable-p}.
2182 @xref{Vectors, vectorp}.
2185 @xref{Weak Lists, weak-list-p}.
2189 @xref{Predicates on Numbers, wholenump}.
2192 @item window-configuration-p
2193 @xref{Window Configurations, window-configuration-p}.
2196 @xref{Deleting Windows, window-live-p}.
2199 @xref{Basic Windows, windowp}.
2202 The most general way to check the type of an object is to call the
2203 function @code{type-of}. Recall that each object belongs to one and
2204 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
2205 Data Types}). But @code{type-of} knows nothing about non-primitive
2206 types. In most cases, it is more convenient to use type predicates than
2209 @defun type-of object
2210 This function returns a symbol naming the primitive type of
2211 @var{object}. The value is one of @code{bit-vector}, @code{buffer},
2212 @code{char-table}, @code{character}, @code{charset},
2213 @code{coding-system}, @code{cons}, @code{color-instance},
2214 @code{compiled-function}, @code{console}, @code{database},
2215 @code{device}, @code{event}, @code{extent}, @code{face}, @code{float},
2216 @code{font-instance}, @code{frame}, @code{glyph}, @code{hash-table},
2217 @code{image-instance}, @code{integer}, @code{keymap}, @code{marker},
2218 @code{process}, @code{range-table}, @code{specifier}, @code{string},
2219 @code{subr}, @code{subwindow}, @code{symbol}, @code{toolbar-button},
2221 @code{weak-list}, @code{window}, @code{window-configuration}, or
2229 (type-of '()) ; @r{@code{()} is @code{nil}.}
2237 @node Equality Predicates
2238 @section Equality Predicates
2241 Here we describe two functions that test for equality between any two
2242 objects. Other functions test equality between objects of specific
2243 types, e.g., strings. For these predicates, see the appropriate chapter
2244 describing the data type.
2246 @defun eq object1 object2
2247 This function returns @code{t} if @var{object1} and @var{object2} are
2248 the same object, @code{nil} otherwise. The ``same object'' means that a
2249 change in one will be reflected by the same change in the other.
2251 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
2252 integers with the same value. Also, since symbol names are normally
2253 unique, if the arguments are symbols with the same name, they are
2254 @code{eq}. For other types (e.g., lists, vectors, strings), two
2255 arguments with the same contents or elements are not necessarily
2256 @code{eq} to each other: they are @code{eq} only if they are the same
2259 (The @code{make-symbol} function returns an uninterned symbol that is
2260 not interned in the standard @code{obarray}. When uninterned symbols
2261 are in use, symbol names are no longer unique. Distinct symbols with
2262 the same name are not @code{eq}. @xref{Creating Symbols}.)
2264 NOTE: Under XEmacs 19, characters are really just integers, and thus
2265 characters and integers are @code{eq}. Under SXEmacs and XEmacs 20+, it
2266 was necessary to preserve remnants of this in function such as
2267 @code{old-eq} in order to maintain byte-code compatibility. Byte code
2268 compiled under any Emacs 19 will automatically have calls to @code{eq}
2269 mapped to @code{old-eq} when executed under SXEmacs or XEmacs 20+.
2288 (eq '(1 (2 (3))) '(1 (2 (3))))
2293 (setq foo '(1 (2 (3))))
2294 @result{} (1 (2 (3)))
2297 (eq foo '(1 (2 (3))))
2302 (eq [(1 2) 3] [(1 2) 3])
2307 (eq (point-marker) (point-marker))
2314 @defun old-eq object1 object2
2315 This function exists under SXEmacs and XEmacs 20+ and is exactly like
2316 @code{eq} except that it suffers from the char-int confoundance disease.
2317 In other words, it returns @code{t} if given a character and the
2318 equivalent integer, even though the objects are of different types!
2319 You should @emph{not} ever call this function explicitly in your
2320 code. However, be aware that all calls to @code{eq} in byte code
2321 compiled under version 19 map to @code{old-eq} in SXEmacs or XEmacs 20+.
2323 Likewise for @code{old-equal}, @code{old-memq}, @code{old-member},
2324 @code{old-assq} and @code{old-assoc}.
2328 ;; @r{Remember, this does not apply under XEmacs 19.}
2334 @result{} t ; @r{Eek, we've been infected.}
2336 @result{} nil ; @r{We are still healthy.}
2341 @defun equal object1 object2
2342 This function returns @code{t} if @var{object1} and @var{object2} have
2343 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
2344 arguments are the same object, @code{equal} looks inside nonidentical
2345 arguments to see if their elements are the same. So, if two objects are
2346 @code{eq}, they are @code{equal}, but the converse is not always true.
2360 (equal "asdf" "asdf")
2369 (equal '(1 (2 (3))) '(1 (2 (3))))
2373 (eq '(1 (2 (3))) '(1 (2 (3))))
2378 (equal [(1 2) 3] [(1 2) 3])
2382 (eq [(1 2) 3] [(1 2) 3])
2387 (equal (point-marker) (point-marker))
2392 (eq (point-marker) (point-marker))
2397 Comparison of strings is case-sensitive.
2399 Note that in FSF GNU Emacs, comparison of strings takes into account
2400 their text properties, and you have to use @code{string-equal} if you
2401 want only the strings themselves compared. This difference does not
2402 exist in SXEmacs; @code{equal} and @code{string-equal} always return
2403 the same value on the same strings.
2405 @ignore @c Not true in SXEmacs nor XEmacs
2406 Comparison of strings is case-sensitive and takes account of text
2407 properties as well as the characters in the strings. To compare
2408 two strings' characters without comparing their text properties,
2409 use @code{string=} (@pxref{Text Comparison}).
2414 (equal "asdf" "ASDF")
2419 Two distinct buffers are never @code{equal}, even if their contents
2423 The test for equality is implemented recursively, and circular lists may
2424 therefore cause infinite recursion (leading to an error).