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.
222 In addition, the following special types are created internally
223 but will never be seen by Lisp code. You may encounter them,
224 however, if you are debugging SXEmacs. The printed representation
225 of these objects begins @samp{#<INTERNAL EMACS BUG}, which indicates
226 to the Lisp programmer that he has found an internal bug in SXEmacs
227 if he ever encounters any of these objects.
249 symbol-value-buffer-local
253 symbol-value-lisp-magic
255 symbol-value-varalias
261 @node Programming Types
262 @section Programming Types
263 @cindex programming types
265 There are two general categories of types in SXEmacs Lisp: those having
266 to do with Lisp programming, and those having to do with editing. The
267 former exist in many Lisp implementations, in one form or another. The
268 latter are unique to SXEmacs Lisp.
271 * Integer Type:: Numbers without fractional parts.
272 * Floating Point Type:: Numbers with fractional parts and with a large range.
273 * Character Type:: The representation of letters, numbers and
275 * Symbol Type:: A multi-use object that refers to a function,
276 variable, or property list, and has a unique identity.
277 * Sequence Type:: Both lists and arrays are classified as sequences.
278 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
279 * Array Type:: Arrays include strings and vectors.
280 * String Type:: An (efficient) array of characters.
281 * Vector Type:: One-dimensional arrays.
282 * Bit Vector Type:: An (efficient) array of bits.
283 * Function Type:: A piece of executable code you can call from elsewhere.
284 * Macro Type:: A method of expanding an expression into another
285 expression, more fundamental but less pretty.
286 * Primitive Function Type:: A function written in C, callable from Lisp.
287 * Compiled-Function Type:: A function written in Lisp, then compiled.
288 * Autoload Type:: A type used for automatically loading seldom-used
290 * Char Table Type:: A mapping from characters to Lisp objects.
291 * Hash Table Type:: A fast mapping between Lisp objects.
292 * Range Table Type:: A mapping from ranges of integers to Lisp objects.
293 * Weak List Type:: A list with special garbage-collection properties.
298 @subsection Integer Type
300 The range of values for integers in SXEmacs Lisp is @minus{}134217728 to
301 134217727 (28 bits; i.e.,
315 on most machines. (Some machines, in particular 64-bit machines such as
316 the DEC Alpha, may provide a wider range.) It is important to note that
317 the XEmacs Lisp arithmetic functions do not check for overflow. Thus
318 @code{(1+ 134217727)} is @minus{}134217728 on most machines. (However,
319 you @emph{will} get an error if you attempt to read an out-of-range
320 number using the Lisp reader.)
322 The read syntax for integers is a sequence of (base ten) digits with
323 an optional sign at the beginning. (The printed representation produced
324 by the Lisp interpreter never has a leading @samp{+}.)
328 -1 ; @r{The integer -1.}
329 1 ; @r{The integer 1.}
330 +1 ; @r{Also the integer 1.}
331 268435457 ; @r{Causes an error on a 28-bit implementation.}
335 @xref{Numbers}, for more information.
338 @node Floating Point Type
339 @subsection Floating Point Type
341 SXEmacs supports floating point numbers. The precise range of floating
342 point numbers is machine-specific.
344 The printed representation for floating point numbers requires either
345 a decimal point (with at least one digit following), an exponent, or
346 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
347 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
348 number whose value is 1500. They are all equivalent.
350 @xref{Numbers}, for more information.
354 @subsection Character Type
355 @cindex @sc{ascii} character codes
356 @cindex char-int confoundance disease
358 In XEmacs version 19, and in all versions of FSF GNU Emacs, a
359 @dfn{character} in XEmacs Lisp is nothing more than an integer.
360 This is yet another holdover from XEmacs Lisp's derivation from
361 vintage-1980 Lisps; modern versions of Lisp consider this equivalence
362 a bad idea, and have separate character types. In XEmacs version 20,
363 and of course all SXEmacs versions, the modern convention is followed,
364 and characters are their own primitive types. This change was necessary
365 in order for @sc{mule}, i.e. Asian-language, support to be correctly
368 Even in XEmacs version 20, remnants of the equivalence between
369 characters and integers still exist; this is termed the @dfn{char-int
370 confoundance disease}. In particular, many functions such as @code{eq},
371 @code{equal}, and @code{memq} have equivalent functions (@code{old-eq},
372 @code{old-equal}, @code{old-memq}, etc.) that pretend like characters
373 are integers are the same. Byte code compiled under any version 19
374 Emacs will have all such functions mapped to their @code{old-} equivalents
375 when the byte code is read into XEmacs 20. This is to preserve
376 compatibility---Emacs 19 converts all constant characters to the equivalent
377 integer during byte-compilation, and thus there is no other way to preserve
378 byte-code compatibility even if the code has specifically been written
379 with the distinction between characters and integers in mind.
381 Every character has an equivalent integer, called the @dfn{character
382 code}. For example, the character @kbd{A} is represented as the
383 @w{integer 65}, following the standard @sc{ascii} representation of
384 characters. If SXEmacs was not compiled with @sc{mule} support, the
385 range of this integer will always be 0 to 255---eight bits, or one
386 byte. (Integers outside this range are accepted but silently truncated;
387 however, you should most decidedly @emph{not} rely on this, because it
388 will not work under SXEmacs with @sc{mule} support.) When @sc{mule}
389 support is present, the range of character codes is much
390 larger. (Currently, 19 bits are used.)
392 FSF GNU Emacs uses kludgy character codes above 255 to represent
393 keyboard input of @sc{ascii} characters in combination with certain
394 modifiers. SXEmacs does not use this (a more general mechanism is
395 used that does not distinguish between @sc{ascii} keys and other
396 keys), so you will never find character codes above 255 in a
397 non-@sc{mule} SXEmacs.
399 Individual characters are not often used in programs. It is far more
400 common to work with @emph{strings}, which are sequences composed of
401 characters. @xref{String Type}.
403 @cindex read syntax for characters
404 @cindex printed representation for characters
405 @cindex syntax for characters
407 The read syntax for characters begins with a question mark, followed
408 by the character (if it's printable) or some symbolic representation of
409 it. In SXEmacs and XEmacs 20+, where characters are their own type,
410 this is also the print representation. In XEmacs 19, however, where
411 characters are really integers, the printed representation of a
412 character is a decimal number.
414 This is also a possible read syntax for a character, but writing
415 characters that way in Lisp programs is a very bad idea. You should
416 @emph{always} use the special read syntax formats that SXEmacs Lisp
417 provides for characters.
419 The usual read syntax for alphanumeric characters is a question mark
420 followed by the character; thus, @samp{?A} for the character
421 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
427 ;; @r{Under SXEmacs:}
428 ?Q @result{} ?Q ?q @result{} ?q
429 (char-int ?Q) @result{} 81
430 ;; @r{Under XEmacs 19:}
431 ?Q @result{} 81 ?q @result{} 113
434 You can use the same syntax for punctuation characters, but it is
435 often a good idea to add a @samp{\} so that the SXEmacs commands for
436 editing Lisp code don't get confused. For example, @samp{?\ } is the
437 way to write the space character. If the character is @samp{\}, you
438 @emph{must} use a second @samp{\} to quote it: @samp{?\\}.
440 SXEmacs always prints punctuation characters with a @samp{\} in front of
441 them, to avoid confusion.
444 @cindex bell character
460 You can express the characters Control-g, backspace, tab, newline,
461 vertical tab, formfeed, return, and escape as @samp{?\a}, @samp{?\b},
462 @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e},
463 respectively. Their character codes are 7, 8, 9, 10, 11, 12, 13, and 27
467 ;; @r{Under SXEmacs:}
468 ?\a @result{} ?\^G ; @r{@kbd{C-g}}
469 (char-int ?\a) @result{} 7
470 ?\b @result{} ?\^H ; @r{backspace, @key{BS}, @kbd{C-h}}
471 (char-int ?\b) @result{} 8
472 ?\t @result{} ?\t ; @r{tab, @key{TAB}, @kbd{C-i}}
473 (char-int ?\t) @result{} 9
474 ?\n @result{} ?\n ; @r{newline, @key{LFD}, @kbd{C-j}}
475 ?\v @result{} ?\^K ; @r{vertical tab, @kbd{C-k}}
476 ?\f @result{} ?\^L ; @r{formfeed character, @kbd{C-l}}
477 ?\r @result{} ?\r ; @r{carriage return, @key{RET}, @kbd{C-m}}
478 ?\e @result{} ?\^[ ; @r{escape character, @key{ESC}, @kbd{C-[}}
479 ?\\ @result{} ?\\ ; @r{backslash character, @kbd{\}}
480 ;; @r{Under XEmacs 19:}
481 ?\a @result{} 7 ; @r{@kbd{C-g}}
482 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
483 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
484 ?\n @result{} 10 ; @r{newline, @key{LFD}, @kbd{C-j}}
485 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
486 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
487 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
488 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
489 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
492 @cindex escape sequence
493 These sequences which start with backslash are also known as
494 @dfn{escape sequences}, because backslash plays the role of an escape
495 character; this usage has nothing to do with the character @key{ESC}.
497 @cindex control characters
498 Control characters may be represented using yet another read syntax.
499 This consists of a question mark followed by a backslash, caret, and the
500 corresponding non-control character, in either upper or lower case. For
501 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
502 character @kbd{C-i}, the character whose value is 9.
504 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
505 equivalent to @samp{?\^I} and to @samp{?\^i}:
508 ;; @r{Under SXEmacs:}
509 ?\^I @result{} ?\t ?\C-I @result{} ?\t
510 (char-int ?\^I) @result{} 9
511 ;; @r{Under XEmacs 19:}
512 ?\^I @result{} 9 ?\C-I @result{} 9
515 There is also a character read syntax beginning with @samp{\M-}. This
516 sets the high bit of the character code (same as adding 128 to the
517 character code). For example, @samp{?\M-A} stands for the character
518 with character code 193, or 128 plus 65. You should @emph{not} use this
519 syntax in your programs. It is a holdover of yet another confoundance
520 disease from earlier Emacsen. (This was used to represent keyboard input
521 with the @key{META} key set, thus the @samp{M}; however, it conflicts
522 with the legitimate @sc{iso}-8859-1 interpretation of the character code.
523 For example, character code 193 is a lowercase @samp{a} with an acute
524 accent, in @sc{iso}-8859-1.)
526 @ignore @c None of this crap applies to SXEmacs nor XEmacs.
527 For use in strings and buffers, you are limited to the control
528 characters that exist in @sc{ascii}, but for keyboard input purposes,
529 you can turn any character into a control character with @samp{C-}. The
530 character codes for these non-@sc{ascii} control characters include the
537 bit as well as the code for the corresponding non-control
538 character. Ordinary terminals have no way of generating non-@sc{ASCII}
539 control characters, but you can generate them straightforwardly using an
542 For historical reasons, Emacs treats the @key{DEL} character as
543 the control equivalent of @kbd{?}:
546 ?\^? @result{} 127 ?\C-? @result{} 127
550 As a result, it is currently not possible to represent the character
551 @kbd{Control-?}, which is a meaningful input character under X. It is
552 not easy to change this as various Lisp files refer to @key{DEL} in this
555 For representing control characters to be found in files or strings,
556 we recommend the @samp{^} syntax; for control characters in keyboard
557 input, we prefer the @samp{C-} syntax. This does not affect the meaning
558 of the program, but may guide the understanding of people who read it.
560 @cindex meta characters
561 A @dfn{meta character} is a character typed with the @key{META}
562 modifier key. The integer that represents such a character has the
569 bit set (which on most machines makes it a negative number). We
570 use high bits for this and other modifiers to make possible a wide range
571 of basic character codes.
580 bit indicates a meta character, so the meta
581 characters that can fit in a string have codes in the range from 128 to
582 255, and are the meta versions of the ordinary @sc{ASCII} characters.
583 (In Emacs versions 18 and older, this convention was used for characters
584 outside of strings as well.)
586 The read syntax for meta characters uses @samp{\M-}. For example,
587 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
588 octal character codes (see below), with @samp{\C-}, or with any other
589 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
590 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
591 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
593 The case of an ordinary letter is indicated by its character code as
594 part of @sc{ASCII}, but @sc{ASCII} has no way to represent whether a
595 control character is upper case or lower case. Emacs uses the
602 bit to indicate that the shift key was used for typing a control
603 character. This distinction is possible only when you use X terminals
604 or other special terminals; ordinary terminals do not indicate the
605 distinction to the computer in any way.
607 @cindex hyper characters
608 @cindex super characters
609 @cindex alt characters
610 The X Window System defines three other modifier bits that can be set
611 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
612 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus,
613 @samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
616 bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
620 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
624 @cindex @samp{?} in character constant
625 @cindex question mark in character constant
626 @cindex @samp{\} in character constant
627 @cindex backslash in character constant
628 @cindex octal character code
629 Finally, the most general read syntax consists of a question mark
630 followed by a backslash and the character code in octal (up to three
631 octal digits); thus, @samp{?\101} for the character @kbd{A},
632 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
633 character @kbd{C-b}. Although this syntax can represent any @sc{ascii}
634 character, it is preferred only when the precise octal value is more
635 important than the @sc{ascii} representation.
639 ;; @r{Under SXEmacs:}
640 ?\012 @result{} ?\n ?\n @result{} ?\n ?\C-j @result{} ?\n
641 ?\101 @result{} ?A ?A @result{} ?A
644 ;; @r{Under XEmacs 19:}
645 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
646 ?\101 @result{} 65 ?A @result{} 65
650 A backslash is allowed, and harmless, preceding any character without
651 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
652 There is no reason to add a backslash before most characters. However,
653 you should add a backslash before any of the characters
654 @samp{()\|;'`"#.,} to avoid confusing the SXEmacs commands for editing
655 Lisp code. Also add a backslash before whitespace characters such as
656 space, tab, newline and formfeed. However, it is cleaner to use one of
657 the easily readable escape sequences, such as @samp{\t}, instead of an
658 actual whitespace character such as a tab.
662 @subsection Symbol Type
664 A @dfn{symbol} in SXEmacs Lisp is an object with a name. The symbol
665 name serves as the printed representation of the symbol. In ordinary
666 use, the name is unique---no two symbols have the same name.
668 A symbol can serve as a variable, as a function name, or to hold a
669 property list. Or it may serve only to be distinct from all other Lisp
670 objects, so that its presence in a data structure may be recognized
671 reliably. In a given context, usually only one of these uses is
672 intended. But you can use one symbol in all of these ways,
675 @cindex @samp{\} in symbols
676 @cindex backslash in symbols
677 A symbol name can contain any characters whatever. Most symbol names
678 are written with letters, digits, and the punctuation characters
679 @samp{-+=*/}. Such names require no special punctuation; the characters
680 of the name suffice as long as the name does not look like a number.
681 (If it does, write a @samp{\} at the beginning of the name to force
682 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}} are
683 less often used but also require no special punctuation. Any other
684 characters may be included in a symbol's name by escaping them with a
685 backslash. In contrast to its use in strings, however, a backslash in
686 the name of a symbol simply quotes the single character that follows the
687 backslash. For example, in a string, @samp{\t} represents a tab
688 character; in the name of a symbol, however, @samp{\t} merely quotes the
689 letter @kbd{t}. To have a symbol with a tab character in its name, you
690 must actually use a tab (preceded with a backslash). But it's rare to
693 @cindex CL note---case of letters
695 @b{Common Lisp note:} In Common Lisp, lower case letters are always
696 ``folded'' to upper case, unless they are explicitly escaped. In SXEmacs
697 Lisp, upper case and lower case letters are distinct.
700 Here are several examples of symbol names. Note that the @samp{+} in
701 the fifth example is escaped to prevent it from being read as a number.
702 This is not necessary in the sixth example because the rest of the name
703 makes it invalid as a number.
707 foo ; @r{A symbol named @samp{foo}.}
708 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
709 char-to-string ; @r{A symbol named @samp{char-to-string}.}
712 1+ ; @r{A symbol named @samp{1+}}
713 ; @r{(not @samp{+1}, which is an integer).}
716 \+1 ; @r{A symbol named @samp{+1}}
717 ; @r{(not a very readable name).}
720 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
721 @c the @'s in this next line use up three characters, hence the
722 @c apparent misalignment of the comment.
723 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
724 ; @r{These characters need not be escaped.}
730 @subsection Sequence Types
732 A @dfn{sequence} is a Lisp object that represents an ordered set of
733 elements. There are two kinds of sequence in SXEmacs Lisp, lists and
734 arrays. Thus, an object of type list or of type array is also
735 considered a sequence.
737 Arrays are further subdivided into strings, vectors, and bit vectors.
738 Vectors can hold elements of any type, but string elements must be
739 characters, and bit vector elements must be either 0 or 1. However, the
740 characters in a string can have extents (@pxref{Extents}) and text
741 properties (@pxref{Text Properties}) like characters in a buffer;
742 vectors do not support extents or text properties even when their
743 elements happen to be characters.
745 Lists, strings, vectors, and bit vectors are different, but they have
746 important similarities. For example, all have a length @var{l}, and all
747 have elements which can be indexed from zero to @var{l} minus one.
748 Also, several functions, called sequence functions, accept any kind of
749 sequence. For example, the function @code{elt} can be used to extract
750 an element of a sequence, given its index. @xref{Sequences Arrays
753 It is impossible to read the same sequence twice, since sequences are
754 always created anew upon reading. If you read the read syntax for a
755 sequence twice, you get two sequences with equal contents. There is one
756 exception: the empty list @code{()} always stands for the same object,
761 @subsection Cons Cell and List Types
762 @cindex address field of register
763 @cindex decrement field of register
765 A @dfn{cons cell} is an object comprising two pointers named the
766 @sc{car} and the @sc{cdr}. Each of them can point to any Lisp object.
768 A @dfn{list} is a series of cons cells, linked together so that the
769 @sc{cdr} of each cons cell points either to another cons cell or to the
770 empty list. @xref{Lists}, for functions that work on lists. Because
771 most cons cells are used as part of lists, the phrase @dfn{list
772 structure} has come to refer to any structure made out of cons cells.
774 The names @sc{car} and @sc{cdr} have only historical meaning now. The
775 original Lisp implementation ran on an @w{IBM 704} computer which
776 divided words into two parts, called the ``address'' part and the
777 ``decrement''; @sc{car} was an instruction to extract the contents of
778 the address part of a register, and @sc{cdr} an instruction to extract
779 the contents of the decrement. By contrast, ``cons cells'' are named
780 for the function @code{cons} that creates them, which in turn is named
781 for its purpose, the construction of cells.
784 Because cons cells are so central to Lisp, we also have a word for
785 ``an object which is not a cons cell''. These objects are called
789 The read syntax and printed representation for lists are identical, and
790 consist of a left parenthesis, an arbitrary number of elements, and a
793 Upon reading, each object inside the parentheses becomes an element
794 of the list. That is, a cons cell is made for each element. The
795 @sc{car} of the cons cell points to the element, and its @sc{cdr} points
796 to the next cons cell of the list, which holds the next element in the
797 list. The @sc{cdr} of the last cons cell is set to point to @code{nil}.
799 @cindex box diagrams, for lists
800 @cindex diagrams, boxed, for lists
801 A list can be illustrated by a diagram in which the cons cells are
802 shown as pairs of boxes. (The Lisp reader cannot read such an
803 illustration; unlike the textual notation, which can be understood by
804 both humans and computers, the box illustrations can be understood only
805 by humans.) The following represents the three-element list @code{(rose
810 ___ ___ ___ ___ ___ ___
811 |___|___|--> |___|___|--> |___|___|--> nil
814 --> rose --> violet --> buttercup
818 In this diagram, each box represents a slot that can refer to any Lisp
819 object. Each pair of boxes represents a cons cell. Each arrow is a
820 reference to a Lisp object, either an atom or another cons cell.
822 In this example, the first box, the @sc{car} of the first cons cell,
823 refers to or ``contains'' @code{rose} (a symbol). The second box, the
824 @sc{cdr} of the first cons cell, refers to the next pair of boxes, the
825 second cons cell. The @sc{car} of the second cons cell refers to
826 @code{violet} and the @sc{cdr} refers to the third cons cell. The
827 @sc{cdr} of the third (and last) cons cell refers to @code{nil}.
829 Here is another diagram of the same list, @code{(rose violet
830 buttercup)}, sketched in a different manner:
834 --------------- ---------------- -------------------
835 | car | cdr | | car | cdr | | car | cdr |
836 | rose | o-------->| violet | o-------->| buttercup | nil |
838 --------------- ---------------- -------------------
842 @cindex @samp{(@dots{})} in lists
843 @cindex @code{nil} in lists
845 A list with no elements in it is the @dfn{empty list}; it is identical
846 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
849 Here are examples of lists written in Lisp syntax:
852 (A 2 "A") ; @r{A list of three elements.}
853 () ; @r{A list of no elements (the empty list).}
854 nil ; @r{A list of no elements (the empty list).}
855 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
856 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
857 (A nil) ; @r{Equivalent to the previous.}
858 ((A B C)) ; @r{A list of one element}
859 ; @r{(which is a list of three elements).}
862 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
863 depicted with boxes and arrows:
868 |___|___|--> |___|___|--> nil
876 * Dotted Pair Notation:: An alternative syntax for lists.
877 * Association List Type:: A specially constructed list.
881 @node Dotted Pair Notation
882 @subsubsection Dotted Pair Notation
883 @cindex dotted pair notation
884 @cindex @samp{.} in lists
886 @dfn{Dotted pair notation} is an alternative syntax for cons cells
887 that represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
888 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
889 the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted
890 pair notation is therefore more general than list syntax. In the dotted
891 pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
892 . nil)))}. For @code{nil}-terminated lists, the two notations produce
893 the same result, but list notation is usually clearer and more
894 convenient when it is applicable. When printing a list, the dotted pair
895 notation is only used if the @sc{cdr} of a cell is not a list.
897 Here's how box notation can illustrate dotted pairs. This example
898 shows the pair @code{(rose . violet)}:
910 Dotted pair notation can be combined with list notation to represent a
911 chain of cons cells with a non-@code{nil} final @sc{cdr}. For example,
912 @code{(rose violet . buttercup)} is equivalent to @code{(rose . (violet
913 . buttercup))}. The object looks like this:
918 |___|___|--> |___|___|--> buttercup
925 These diagrams make it evident why @w{@code{(rose .@: violet .@:
926 buttercup)}} is invalid syntax; it would require a cons cell that has
927 three parts rather than two.
929 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}
935 |___|___|--> |___|___|--> nil
942 Similarly, the three-element list @code{(rose violet buttercup)}
943 is equivalent to @code{(rose . (violet . (buttercup)))}.
949 ___ ___ ___ ___ ___ ___
950 |___|___|--> |___|___|--> |___|___|--> nil
953 --> rose --> violet --> buttercup
959 @node Association List Type
960 @subsubsection Association List Type
962 An @dfn{association list} or @dfn{alist} is a specially-constructed
963 list whose elements are cons cells. In each element, the @sc{car} is
964 considered a @dfn{key}, and the @sc{cdr} is considered an
965 @dfn{associated value}. (In some cases, the associated value is stored
966 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
967 stacks, since it is easy to add or remove associations at the front of
973 (setq alist-of-colors
974 '((rose . red) (lily . white) (buttercup . yellow)))
978 sets the variable @code{alist-of-colors} to an alist of three elements. In the
979 first element, @code{rose} is the key and @code{red} is the value.
981 @xref{Association Lists}, for a further explanation of alists and for
982 functions that work on alists.
986 @subsection Array Type
988 An @dfn{array} is composed of an arbitrary number of slots for
989 referring to other Lisp objects, arranged in a contiguous block of
990 memory. Accessing any element of an array takes the same amount of
991 time. In contrast, accessing an element of a list requires time
992 proportional to the position of the element in the list. (Elements at
993 the end of a list take longer to access than elements at the beginning
996 SXEmacs defines three types of array, strings, vectors, and bit
997 vectors. A string is an array of characters, a vector is an array of
998 arbitrary objects, and a bit vector is an array of 1's and 0's. All are
999 one-dimensional. (Most other programming languages support
1000 multidimensional arrays, but they are not essential; you can get the
1001 same effect with an array of arrays.) Each type of array has its own
1002 read syntax; see @ref{String Type}, @ref{Vector Type}, and @ref{Bit
1005 An array may have any length up to the largest integer; but once
1006 created, it has a fixed size. The first element of an array has index
1007 zero, the second element has index 1, and so on. This is called
1008 @dfn{zero-origin} indexing. For example, an array of four elements has
1009 indices 0, 1, 2, @w{and 3}.
1011 The array type is contained in the sequence type and contains the
1012 string type, the vector type, and the bit vector type.
1016 @subsection String Type
1018 A @dfn{string} is an array of characters. Strings are used for many
1019 purposes in SXEmacs, as can be expected in a text editor; for example, as
1020 the names of Lisp symbols, as messages for the user, and to represent
1021 text extracted from buffers. Strings in Lisp are constants: evaluation
1022 of a string returns the same string.
1024 @cindex @samp{"} in strings
1025 @cindex double-quote in strings
1026 @cindex @samp{\} in strings
1027 @cindex backslash in strings
1028 The read syntax for strings is a double-quote, an arbitrary number of
1029 characters, and another double-quote, @code{"like this"}. The Lisp
1030 reader accepts the same formats for reading the characters of a string
1031 as it does for reading single characters (without the question mark that
1032 begins a character literal). You can enter a nonprinting character such
1033 as tab or @kbd{C-a} using the convenient escape sequences, like this:
1034 @code{"\t, \C-a"}. You can include a double-quote in a string by
1035 preceding it with a backslash; thus, @code{"\""} is a string containing
1036 just a single double-quote character. (@xref{Character Type}, for a
1037 description of the read syntax for characters.)
1039 @ignore @c More ill-conceived FSF Emacs crap.
1040 If you use the @samp{\M-} syntax to indicate a meta character in a
1041 string constant, this sets the
1048 bit of the character in the string.
1049 This is not the same representation that the meta modifier has in a
1050 character on its own (not inside a string). @xref{Character Type}.
1052 Strings cannot hold characters that have the hyper, super, or alt
1053 modifiers; they can hold @sc{ASCII} control characters, but no others.
1054 They do not distinguish case in @sc{ASCII} control characters.
1057 The printed representation of a string consists of a double-quote, the
1058 characters it contains, and another double-quote. However, you must
1059 escape any backslash or double-quote characters in the string with a
1060 backslash, like this: @code{"this \" is an embedded quote"}.
1062 An alternative syntax allows insertion of raw backslashes into a
1063 string, like this: @code{#r"this \ is an embedded backslash"}. In such
1064 a string, each character following a backslash is included literally in
1065 the string, and all backslashes are left in the string. This means that
1066 @code{#r"\""} is a valid string literal with two characters, a backslash and a
1067 double-quote. It also means that a string with this syntax @emph{cannot end
1068 in a single backslash}.
1070 The newline character is not special in the read syntax for strings;
1071 if you write a new line between the double-quotes, it becomes a
1072 character in the string. But an escaped newline---one that is preceded
1073 by @samp{\}---does not become part of the string; i.e., the Lisp reader
1074 ignores an escaped newline while reading a string.
1075 @cindex newline in strings
1078 "It is useful to include newlines
1079 in documentation strings,
1080 but the newline is \
1081 ignored if escaped."
1082 @result{} "It is useful to include newlines
1083 in documentation strings,
1084 but the newline is ignored if escaped."
1087 A string can hold extents and properties of the text it contains, in
1088 addition to the characters themselves. This enables programs that copy
1089 text between strings and buffers to preserve the extents and properties
1090 with no special effort. @xref{Extents}, @xref{Text Properties}.
1092 Note that FSF GNU Emacs has a special read and print syntax for
1093 strings with text properties, but SXEmacs does not currently implement
1094 this. It was judged better not to include this in SXEmacs because it
1095 entails that @code{equal} return @code{nil} when passed a string with
1096 text properties and the equivalent string without text properties, which
1097 is often counter-intuitive.
1099 @ignore @c Not in SXEmacs nor XEmacs
1101 properties have a special read and print syntax:
1104 #("@var{characters}" @var{property-data}...)
1108 where @var{property-data} consists of zero or more elements, in groups
1109 of three as follows:
1112 @var{start} @var{end} @var{plist}
1116 The elements @var{start} and @var{end} are integers, and together specify
1117 a range of indices in the string; @var{plist} is the property list for
1121 @xref{Strings and Characters}, for functions that work on strings.
1125 @subsection Vector Type
1127 A @dfn{vector} is a one-dimensional array of elements of any type. It
1128 takes a constant amount of time to access any element of a vector. (In
1129 a list, the access time of an element is proportional to the distance of
1130 the element from the beginning of the list.)
1132 The printed representation of a vector consists of a left square
1133 bracket, the elements, and a right square bracket. This is also the
1134 read syntax. Like numbers and strings, vectors are considered constants
1138 [1 "two" (three)] ; @r{A vector of three elements.}
1139 @result{} [1 "two" (three)]
1142 @xref{Vectors}, for functions that work with vectors.
1145 @node Bit Vector Type
1146 @subsection Bit Vector Type
1148 A @dfn{bit vector} is a one-dimensional array of 1's and 0's. It
1149 takes a constant amount of time to access any element of a bit vector,
1150 as for vectors. Bit vectors have an extremely compact internal
1151 representation (one machine bit per element), which makes them ideal
1152 for keeping track of unordered sets, large collections of boolean values,
1155 The printed representation of a bit vector consists of @samp{#*}
1156 followed by the bits in the vector. This is also the read syntax. Like
1157 numbers, strings, and vectors, bit vectors are considered constants for
1161 #*00101000 ; @r{A bit vector of eight elements.}
1162 @result{} #*00101000
1165 @xref{Bit Vectors}, for functions that work with bit vectors.
1169 @subsection Function Type
1171 Just as functions in other programming languages are executable,
1172 @dfn{Lisp function} objects are pieces of executable code. However,
1173 functions in Lisp are primarily Lisp objects, and only secondarily the
1174 text which represents them. These Lisp objects are lambda expressions:
1175 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
1178 In most programming languages, it is impossible to have a function
1179 without a name. In Lisp, a function has no intrinsic name. A lambda
1180 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
1181 Functions}). A named function in Lisp is actually a symbol with a valid
1182 function in its function cell (@pxref{Defining Functions}).
1184 Most of the time, functions are called when their names are written in
1185 Lisp expressions in Lisp programs. However, you can construct or obtain
1186 a function object at run time and then call it with the primitive
1187 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
1191 @subsection Macro Type
1193 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
1194 language. It is represented as an object much like a function, but with
1195 different parameter-passing semantics. A Lisp macro has the form of a
1196 list whose first element is the symbol @code{macro} and whose @sc{cdr}
1197 is a Lisp function object, including the @code{lambda} symbol.
1199 Lisp macro objects are usually defined with the built-in
1200 @code{defmacro} function, but any list that begins with @code{macro} is
1201 a macro as far as SXEmacs is concerned. @xref{Macros}, for an explanation
1202 of how to write a macro.
1205 @node Primitive Function Type
1206 @subsection Primitive Function Type
1207 @cindex special forms
1209 A @dfn{primitive function} is a function callable from Lisp but
1210 written in the C programming language. Primitive functions are also
1211 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
1212 derived from ``subroutine''.) Most primitive functions evaluate all
1213 their arguments when they are called. A primitive function that does
1214 not evaluate all its arguments is called a @dfn{special form}
1215 (@pxref{Special Forms}).@refill
1217 It does not matter to the caller of a function whether the function is
1218 primitive. However, this does matter if you try to substitute a
1219 function written in Lisp for a primitive of the same name. The reason
1220 is that the primitive function may be called directly from C code.
1221 Calls to the redefined function from Lisp will use the new definition,
1222 but calls from C code may still use the built-in definition.
1224 The term @dfn{function} refers to all SXEmacs functions, whether
1225 written in Lisp or C. @xref{Function Type}, for information about the
1226 functions written in Lisp.
1228 Primitive functions have no read syntax and print in hash notation
1229 with the name of the subroutine.
1233 (symbol-function 'car) ; @r{Access the function cell}
1234 ; @r{of the symbol.}
1235 @result{} #<subr car>
1236 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
1237 @result{} t ; @r{Yes.}
1242 @node Compiled-Function Type
1243 @subsection Compiled-Function Type
1245 The byte compiler produces @dfn{compiled-function objects}. The
1246 evaluator handles this data type specially when it appears as a function
1247 to be called. @xref{Byte Compilation}, for information about the byte
1250 The printed representation for a compiled-function object is normally
1251 @samp{#<compiled-function...>}. If @code{print-readably} is true,
1252 however, it is @samp{#[...]}.
1256 @subsection Autoload Type
1258 An @dfn{autoload object} is a list whose first element is the symbol
1259 @code{autoload}. It is stored as the function definition of a symbol as
1260 a placeholder for the real definition; it says that the real definition
1261 is found in a file of Lisp code that should be loaded when necessary.
1262 The autoload object contains the name of the file, plus some other
1263 information about the real definition.
1265 After the file has been loaded, the symbol should have a new function
1266 definition that is not an autoload object. The new definition is then
1267 called as if it had been there to begin with. From the user's point of
1268 view, the function call works as expected, using the function definition
1271 An autoload object is usually created with the function
1272 @code{autoload}, which stores the object in the function cell of a
1273 symbol. @xref{Autoload}, for more details.
1276 @node Char Table Type
1277 @subsection Char Table Type
1278 @cindex char table type
1280 (not yet documented)
1283 @node Hash Table Type
1284 @subsection Hash Table Type
1285 @cindex hash table type
1287 A @dfn{hash table} is a table providing an arbitrary mapping from
1288 one Lisp object to another, using an internal indexing method
1289 called @dfn{hashing}. Hash tables are very fast (much more efficient
1290 that using an association list, when there are a large number of
1291 elements in the table).
1293 Hash tables have a special read syntax beginning with
1294 @samp{#s(hash-table} (this is an example of @dfn{structure} read
1295 syntax. This notation is also used for printing when
1296 @code{print-readably} is @code{t}.
1298 Otherwise they print in hash notation (The ``hash'' in ``hash notation''
1299 has nothing to do with the ``hash'' in ``hash table''), giving the
1300 number of elements, total space allocated for elements, and a unique
1301 number assigned at the time the hash table was created. (Hash tables
1302 automatically resize as necessary so there is no danger of running out
1303 of space for elements.)
1307 (make-hash-table :size 50)
1308 @result{} #<hash-table 0/107 0x313a>
1312 @xref{Hash Tables}, for information on how to create and work with hash
1316 @node Range Table Type
1317 @subsection Range Table Type
1318 @cindex range table type
1320 A @dfn{range table} is a table that maps from ranges of integers to
1321 arbitrary Lisp objects. Range tables automatically combine overlapping
1322 ranges that map to the same Lisp object, and operations are provided
1323 for mapping over all of the ranges in a range table.
1325 Range tables have a special read syntax beginning with
1326 @samp{#s(range-table} (this is an example of @dfn{structure} read syntax,
1327 which is also used for char tables and faces).
1331 (setq x (make-range-table))
1332 (put-range-table 20 50 'foo x)
1333 (put-range-table 100 200 "bar" x)
1335 @result{} #s(range-table data ((20 50) foo (100 200) "bar"))
1339 @xref{Range Tables}, for information on how to create and work with range
1343 @node Weak List Type
1344 @subsection Weak List Type
1345 @cindex weak list type
1347 (not yet documented)
1351 @section Editing Types
1352 @cindex editing types
1354 The types in the previous section are common to many Lisp dialects.
1355 SXEmacs Lisp provides several additional data types for purposes connected
1359 * Buffer Type:: The basic object of editing.
1360 * Marker Type:: A position in a buffer.
1361 * Extent Type:: A range in a buffer or string, maybe with properties.
1362 * Window Type:: Buffers are displayed in windows.
1363 * Frame Type:: Windows subdivide frames.
1364 * Device Type:: Devices group all frames on a display.
1365 * Console Type:: Consoles group all devices with the same keyboard.
1366 * Window Configuration Type:: Recording the way a frame is subdivided.
1367 * Event Type:: An interesting occurrence in the system.
1368 * Process Type:: A process running on the underlying OS.
1369 * Stream Type:: Receive or send characters.
1370 * Keymap Type:: What function a keystroke invokes.
1371 * Syntax Table Type:: What a character means.
1372 * Display Table Type:: How display tables are represented.
1373 * Database Type:: A connection to an external DBM or DB database.
1374 * Charset Type:: A character set (e.g. all Kanji characters),
1376 * Coding System Type:: An object encapsulating a way of converting between
1377 different textual encodings, under SXEmacs/MULE.
1378 * ToolTalk Message Type:: A message, in the ToolTalk IPC protocol.
1379 * ToolTalk Pattern Type:: A pattern, in the ToolTalk IPC protocol.
1384 @subsection Buffer Type
1386 A @dfn{buffer} is an object that holds text that can be edited
1387 (@pxref{Buffers}). Most buffers hold the contents of a disk file
1388 (@pxref{Files}) so they can be edited, but some are used for other
1389 purposes. Most buffers are also meant to be seen by the user, and
1390 therefore displayed, at some time, in a window (@pxref{Windows}). But a
1391 buffer need not be displayed in any window.
1393 The contents of a buffer are much like a string, but buffers are not
1394 used like strings in SXEmacs Lisp, and the available operations are
1395 different. For example, insertion of text into a buffer is very
1396 efficient, whereas ``inserting'' text into a string requires
1397 concatenating substrings, and the result is an entirely new string
1400 Each buffer has a designated position called @dfn{point}
1401 (@pxref{Positions}). At any time, one buffer is the @dfn{current
1402 buffer}. Most editing commands act on the contents of the current
1403 buffer in the neighborhood of point. Many of the standard SXEmacs
1404 functions manipulate or test the characters in the current buffer; a
1405 whole chapter in this manual is devoted to describing these functions
1408 Several other data structures are associated with each buffer:
1412 a local syntax table (@pxref{Syntax Tables});
1415 a local keymap (@pxref{Keymaps});
1418 a local variable binding list (@pxref{Buffer-Local Variables});
1421 a list of extents (@pxref{Extents});
1424 and various other related properties.
1428 The local keymap and variable list contain entries that individually
1429 override global bindings or values. These are used to customize the
1430 behavior of programs in different buffers, without actually changing the
1433 A buffer may be @dfn{indirect}, which means it shares the text
1434 of another buffer. @xref{Indirect Buffers}.
1436 Buffers have no read syntax. They print in hash notation, showing the
1442 @result{} #<buffer "objects.texi">
1448 @subsection Marker Type
1450 A @dfn{marker} denotes a position in a specific buffer. Markers
1451 therefore have two components: one for the buffer, and one for the
1452 position. Changes in the buffer's text automatically relocate the
1453 position value as necessary to ensure that the marker always points
1454 between the same two characters in the buffer.
1456 Markers have no read syntax. They print in hash notation, giving the
1457 current character position and the name of the buffer.
1462 @result{} #<marker at 50661 in objects.texi>
1466 @xref{Markers}, for information on how to test, create, copy, and move
1471 @subsection Extent Type
1473 An @dfn{extent} specifies temporary alteration of the display
1474 appearance of a part of a buffer (or string). It contains markers
1475 delimiting a range of the buffer, plus a property list (a list whose
1476 elements are alternating property names and values). Extents are used
1477 to present parts of the buffer temporarily in a different display style.
1478 They have no read syntax, and print in hash notation, giving the buffer
1479 name and range of positions.
1481 Extents can exist over strings as well as buffers; the primary use
1482 of this is to preserve extent and text property information as text
1483 is copied from one buffer to another or between different parts of
1486 Extents have no read syntax. They print in hash notation, giving the
1487 range of text they cover, the name of the buffer or string they are in,
1488 the address in core, and a summary of some of the properties attached to
1494 @result{} #<extent [51742, 51748) font-lock text-prop 0x90121e0 in buffer objects.texi>
1498 @xref{Extents}, for how to create and use extents.
1500 Extents are used to implement text properties. @xref{Text Properties}.
1504 @subsection Window Type
1506 A @dfn{window} describes the portion of the frame that SXEmacs uses to
1507 display a buffer. (In standard window-system usage, a @dfn{window} is
1508 what SXEmacs calls a @dfn{frame}; SXEmacs confusingly uses the term
1509 ``window'' to refer to what is called a @dfn{pane} in standard
1510 window-system usage.) Every window has one associated buffer, whose
1511 contents appear in the window. By contrast, a given buffer may appear
1512 in one window, no window, or several windows.
1514 Though many windows may exist simultaneously, at any time one window
1515 is designated the @dfn{selected window}. This is the window where the
1516 cursor is (usually) displayed when SXEmacs is ready for a command. The
1517 selected window usually displays the current buffer, but this is not
1518 necessarily the case.
1520 Windows are grouped on the screen into frames; each window belongs to
1521 one and only one frame. @xref{Frame Type}.
1523 Windows have no read syntax. They print in hash notation, giving the
1524 name of the buffer being displayed and a unique number assigned at the
1525 time the window was created. (This number can be useful because the
1526 buffer displayed in any given window can change frequently.)
1531 @result{} #<window on "objects.texi" 0x266c>
1535 @xref{Windows}, for a description of the functions that work on windows.
1539 @subsection Frame Type
1541 A @var{frame} is a rectangle on the screen (a @dfn{window} in standard
1542 window-system terminology) that contains one or more non-overlapping
1543 SXEmacs windows (@dfn{panes} in standard window-system terminology). A
1544 frame initially contains a single main window (plus perhaps a minibuffer
1545 window) which you can subdivide vertically or horizontally into smaller
1548 Frames have no read syntax. They print in hash notation, giving the
1549 frame's type, name as used for resourcing, and a unique number assigned
1550 at the time the frame was created.
1555 @result{} #<x-frame "emacs" 0x9db>
1559 @xref{Frames}, for a description of the functions that work on frames.
1563 @subsection Device Type
1565 A @dfn{device} represents a single display on which frames exist.
1566 Normally, there is only one device object, but there may be more
1567 than one if SXEmacs is being run on a multi-headed display (e.g. an
1568 X server with attached color and mono screens) or if SXEmacs is
1569 simultaneously driving frames attached to different consoles, e.g.
1570 an X display and a @sc{tty} connection.
1572 Devices do not have a read syntax. They print in hash notation,
1573 giving the device's type, connection name, and a unique number assigned
1574 at the time the device was created.
1579 @result{} #<x-device on ":0.0" 0x5b9>
1583 @xref{Consoles and Devices}, for a description of several functions
1588 @subsection Console Type
1590 A @dfn{console} represents a single keyboard to which devices
1591 (i.e. displays on which frames exist) are connected. Normally, there is
1592 only one console object, but there may be more than one if SXEmacs is
1593 simultaneously driving frames attached to different X servers and/or
1594 @sc{tty} connections.
1596 SXEmacs is capable of driving multiple X and @sc{tty} connections at the
1597 same time, and provides a robust mechanism for handling the differing
1598 display capabilities of such heterogeneous environments. A buffer with
1599 embedded glyphs and multiple fonts and colors, for example, will display
1600 reasonably if it simultaneously appears on a frame on a color X display,
1601 a frame on a mono X display, and a frame on a @sc{tty} connection.
1603 Consoles do not have a read syntax. They print in hash notation,
1604 giving the console's type, connection name, and a unique number assigned
1605 at the time the console was created.
1610 @result{} #<x-console on "localhost:0" 0x5b7>
1614 @xref{Consoles and Devices}, for a description of several functions
1615 related to consoles.
1618 @node Window Configuration Type
1619 @subsection Window Configuration Type
1620 @cindex screen layout
1622 A @dfn{window configuration} stores information about the positions,
1623 sizes, and contents of the windows in a frame, so you can recreate the
1624 same arrangement of windows later.
1626 Window configurations do not have a read syntax. They print in hash
1627 notation, giving a unique number assigned at the time the window
1628 configuration was created.
1632 (current-window-configuration)
1633 @result{} #<window-configuration 0x2db4>
1637 @xref{Window Configurations}, for a description of several functions
1638 related to window configurations.
1642 @subsection Event Type
1644 (not yet documented)
1648 @subsection Process Type
1650 The word @dfn{process} usually means a running program. SXEmacs itself
1651 runs in a process of this sort. However, in SXEmacs Lisp, a process is a
1652 Lisp object that designates a subprocess created by the SXEmacs process.
1653 Programs such as shells, GDB, ftp, and compilers, running in
1654 subprocesses of SXEmacs, extend the capabilities of SXEmacs.
1656 A SXEmacs subprocess takes textual input from SXEmacs and returns textual
1657 output to SXEmacs for further manipulation. SXEmacs can also send signals
1660 Process objects have no read syntax. They print in hash notation,
1661 giving the name of the process, its associated process ID, and the
1662 current state of the process:
1667 @result{} (#<process "shell" pid 2909 state:run>)
1671 @xref{Processes}, for information about functions that create, delete,
1672 return information about, send input or signals to, and receive output
1677 @subsection Stream Type
1679 A @dfn{stream} is an object that can be used as a source or sink for
1680 characters---either to supply characters for input or to accept them as
1681 output. Many different types can be used this way: markers, buffers,
1682 strings, and functions. Most often, input streams (character sources)
1683 obtain characters from the keyboard, a buffer, or a file, and output
1684 streams (character sinks) send characters to a buffer, such as a
1685 @file{*Help*} buffer, or to the echo area.
1687 The object @code{nil}, in addition to its other meanings, may be used
1688 as a stream. It stands for the value of the variable
1689 @code{standard-input} or @code{standard-output}. Also, the object
1690 @code{t} as a stream specifies input using the minibuffer
1691 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
1694 Streams have no special printed representation or read syntax, and
1695 print as whatever primitive type they are.
1697 @xref{Read and Print}, for a description of functions
1698 related to streams, including parsing and printing functions.
1702 @subsection Keymap Type
1704 A @dfn{keymap} maps keys typed by the user to commands. This mapping
1705 controls how the user's command input is executed.
1707 NOTE: In SXEmacs, a keymap is a separate primitive type. In FSF GNU
1708 Emacs, a keymap is actually a list whose @sc{car} is the symbol
1711 @xref{Keymaps}, for information about creating keymaps, handling prefix
1712 keys, local as well as global keymaps, and changing key bindings.
1715 @node Syntax Table Type
1716 @subsection Syntax Table Type
1718 Under SXEmacs and XEmacs 20+, a @dfn{syntax table} is a particular
1719 type of char table. Under XEmacs 19, a syntax table a vector of 256
1720 integers. In both cases, each element defines how one character is
1721 interpreted when it appears in a buffer. For example, in C mode
1722 (@pxref{Major Modes}), the @samp{+} character is punctuation, but in
1723 Lisp mode it is a valid character in a symbol. These modes specify
1724 different interpretations by changing the syntax table entry for
1727 Syntax tables are used only for scanning text in buffers, not for
1728 reading Lisp expressions. The table the Lisp interpreter uses to read
1729 expressions is built into the SXEmacs source code and cannot be changed;
1730 thus, to change the list delimiters to be @samp{@{} and @samp{@}}
1731 instead of @samp{(} and @samp{)} would be impossible.
1733 @xref{Syntax Tables}, for details about syntax classes and how to make
1734 and modify syntax tables.
1737 @node Display Table Type
1738 @subsection Display Table Type
1740 A @dfn{display table} specifies how to display each character code.
1741 Each buffer and each window can have its own display table. A display
1742 table is actually a vector of length 256, although in SXEmacs and XEmacs
1743 20+ this may change to be a particular type of char table.
1744 @xref{Display Tables}.
1748 @subsection Database Type
1749 @cindex database type
1751 (not yet documented)
1755 @subsection Charset Type
1756 @cindex charset type
1758 (not yet documented)
1761 @node Coding System Type
1762 @subsection Coding System Type
1763 @cindex coding system type
1765 (not yet documented)
1768 @node ToolTalk Message Type
1769 @subsection ToolTalk Message Type
1771 (not yet documented)
1774 @node ToolTalk Pattern Type
1775 @subsection ToolTalk Pattern Type
1777 (not yet documented)
1780 @node Window-System Types
1781 @section Window-System Types
1782 @cindex window system types
1784 SXEmacs also has some types that represent objects such as faces
1785 (collections of display characters), fonts, and pixmaps that are
1786 commonly found in windowing systems.
1789 * Face Type:: A collection of display characteristics.
1790 * Glyph Type:: An image appearing in a buffer or elsewhere.
1791 * Specifier Type:: A way of controlling display characteristics on
1792 a per-buffer, -frame, -window, or -device level.
1793 * Font Instance Type:: The way a font appears on a particular device.
1794 * Color Instance Type:: The way a color appears on a particular device.
1795 * Image Instance Type:: The way an image appears on a particular device.
1796 * Toolbar Button Type:: An object representing a button in a toolbar.
1797 * Subwindow Type:: An externally-controlled window-system window
1798 appearing in a buffer.
1799 * X Resource Type:: A miscellaneous X resource, if Epoch support was
1800 compiled into SXEmacs.
1805 @subsection Face Type
1808 (not yet documented)
1812 @subsection Glyph Type
1815 (not yet documented)
1818 @node Specifier Type
1819 @subsection Specifier Type
1820 @cindex specifier type
1822 (not yet documented)
1825 @node Font Instance Type
1826 @subsection Font Instance Type
1827 @cindex font instance type
1829 (not yet documented)
1832 @node Color Instance Type
1833 @subsection Color Instance Type
1834 @cindex color instance type
1836 (not yet documented)
1839 @node Image Instance Type
1840 @subsection Image Instance Type
1841 @cindex image instance type
1843 (not yet documented)
1846 @node Toolbar Button Type
1847 @subsection Toolbar Button Type
1848 @cindex toolbar button type
1850 (not yet documented)
1853 @node Subwindow Type
1854 @subsection Subwindow Type
1855 @cindex subwindow type
1857 (not yet documented)
1860 @node X Resource Type
1861 @subsection X Resource Type
1862 @cindex X resource type
1864 (not yet documented)
1867 @node Type Predicates
1868 @section Type Predicates
1870 @cindex type checking
1871 @kindex wrong-type-argument
1873 The SXEmacs Lisp interpreter itself does not perform type checking on
1874 the actual arguments passed to functions when they are called. It could
1875 not do so, since function arguments in Lisp do not have declared data
1876 types, as they do in other programming languages. It is therefore up to
1877 the individual function to test whether each actual argument belongs to
1878 a type that the function can use.
1880 All built-in functions do check the types of their actual arguments
1881 when appropriate, and signal a @code{wrong-type-argument} error if an
1882 argument is of the wrong type. For example, here is what happens if you
1883 pass an argument to @code{+} that it cannot handle:
1888 @error{} Wrong type argument: integer-or-marker-p, a
1892 @cindex type predicates
1893 @cindex testing types
1894 If you want your program to handle different types differently, you
1895 must do explicit type checking. The most common way to check the type
1896 of an object is to call a @dfn{type predicate} function. SXEmacs has a
1897 type predicate for each type, as well as some predicates for
1898 combinations of types.
1900 A type predicate function takes one argument; it returns @code{t} if
1901 the argument belongs to the appropriate type, and @code{nil} otherwise.
1902 Following a general Lisp convention for predicate functions, most type
1903 predicates' names end with @samp{p}.
1905 Here is an example which uses the predicates @code{listp} to check for
1906 a list and @code{symbolp} to check for a symbol.
1911 ;; If X is a symbol, put it on LIST.
1912 (setq list (cons x list)))
1914 ;; If X is a list, add its elements to LIST.
1915 (setq list (append x list)))
1918 ;; We only handle symbols and lists.
1919 (error "Invalid argument %s in add-on" x))))
1922 Here is a table of predefined type predicates, in alphabetical order,
1923 with references to further information.
1927 @xref{Annotation Primitives, annotationp}.
1930 @xref{Array Functions, arrayp}.
1933 @xref{List-related Predicates, atom}.
1936 @xref{Bit Vector Functions, bit-vector-p}.
1939 @xref{Bit Vector Functions, bitp}.
1941 @item boolean-specifier-p
1942 @xref{Specifier Types, boolean-specifier-p}.
1944 @item buffer-glyph-p
1945 @xref{Glyph Types, buffer-glyph-p}.
1948 @xref{Killing Buffers, buffer-live-p}.
1951 @xref{Buffer Basics, bufferp}.
1953 @item button-event-p
1954 @xref{Event Predicates, button-event-p}.
1956 @item button-press-event-p
1957 @xref{Event Predicates, button-press-event-p}.
1959 @item button-release-event-p
1960 @xref{Event Predicates, button-release-event-p}.
1963 @xref{Case Tables, case-table-p}.
1966 @xref{Character Codes, char-int-p}.
1968 @item char-or-char-int-p
1969 @xref{Character Codes, char-or-char-int-p}.
1971 @item char-or-string-p
1972 @xref{Predicates for Strings, char-or-string-p}.
1975 @xref{Char Tables, char-table-p}.
1978 @xref{Predicates for Characters, characterp}.
1980 @item color-instance-p
1981 @xref{Colors, color-instance-p}.
1983 @item color-pixmap-image-instance-p
1984 @xref{Image Instance Types, color-pixmap-image-instance-p}.
1986 @item color-specifier-p
1987 @xref{Specifier Types, color-specifier-p}.
1990 @xref{Interactive Call, commandp}.
1992 @item compiled-function-p
1993 @xref{Compiled-Function Type, compiled-function-p}.
1995 @item console-live-p
1996 @xref{Connecting to a Console or Device, console-live-p}.
1999 @xref{Consoles and Devices, consolep}.
2002 @xref{List-related Predicates, consp}.
2004 @item database-live-p
2005 @xref{Connecting to a Database, database-live-p}.
2008 @xref{Databases, databasep}.
2011 @xref{Connecting to a Console or Device, device-live-p}.
2013 @item device-or-frame-p
2014 @xref{Basic Device Functions, device-or-frame-p}.
2017 @xref{Consoles and Devices, devicep}.
2020 @xref{Event Predicates, eval-event-p}.
2023 @xref{Event Predicates, event-live-p}.
2026 @xref{Events, eventp}.
2029 @xref{Creating and Modifying Extents, extent-live-p}.
2032 @xref{Extents, extentp}.
2034 @item face-boolean-specifier-p
2035 @xref{Specifier Types, face-boolean-specifier-p}.
2038 @xref{Basic Face Functions, facep}.
2041 @xref{Predicates on Numbers, floatp}.
2043 @item font-instance-p
2044 @xref{Fonts, font-instance-p}.
2046 @item font-specifier-p
2047 @xref{Specifier Types, font-specifier-p}.
2050 @xref{Deleting Frames, frame-live-p}.
2053 @xref{Frames, framep}.
2056 (not yet documented)
2058 @item generic-specifier-p
2059 @xref{Specifier Types, generic-specifier-p}.
2062 @xref{Glyphs, glyphp}.
2065 @xref{Hash Tables, hash-table-p}.
2068 @xref{Glyph Types, icon-glyph-p}.
2070 @item image-instance-p
2071 @xref{Images, image-instance-p}.
2073 @item image-specifier-p
2074 @xref{Specifier Types, image-specifier-p}.
2076 @item integer-char-or-marker-p
2077 @xref{Predicates on Markers, integer-char-or-marker-p}.
2079 @item integer-or-char-p
2080 @xref{Predicates for Characters, integer-or-char-p}.
2082 @item integer-or-marker-p
2083 @xref{Predicates on Markers, integer-or-marker-p}.
2085 @item integer-specifier-p
2086 @xref{Specifier Types, integer-specifier-p}.
2089 @xref{Predicates on Numbers, integerp}.
2092 (not yet documented)
2094 @item key-press-event-p
2095 @xref{Event Predicates, key-press-event-p}.
2098 @xref{Creating Keymaps, keymapp}.
2101 (not yet documented)
2104 @xref{List-related Predicates, listp}.
2107 @xref{Predicates on Markers, markerp}.
2109 @item misc-user-event-p
2110 @xref{Event Predicates, misc-user-event-p}.
2112 @item mono-pixmap-image-instance-p
2113 @xref{Image Instance Types, mono-pixmap-image-instance-p}.
2115 @item motion-event-p
2116 @xref{Event Predicates, motion-event-p}.
2119 @xref{Event Predicates, mouse-event-p}.
2121 @item natnum-specifier-p
2122 @xref{Specifier Types, natnum-specifier-p}.
2125 @xref{Predicates on Numbers, natnump}.
2128 @xref{List-related Predicates, nlistp}.
2130 @item nothing-image-instance-p
2131 @xref{Image Instance Types, nothing-image-instance-p}.
2133 @item number-char-or-marker-p
2134 @xref{Predicates on Markers, number-char-or-marker-p}.
2136 @item number-or-marker-p
2137 @xref{Predicates on Markers, number-or-marker-p}.
2140 @xref{Predicates on Numbers, numberp}.
2142 @item pointer-glyph-p
2143 @xref{Glyph Types, pointer-glyph-p}.
2145 @item pointer-image-instance-p
2146 @xref{Image Instance Types, pointer-image-instance-p}.
2148 @item process-event-p
2149 @xref{Event Predicates, process-event-p}.
2152 @xref{Processes, processp}.
2155 @xref{Range Tables, range-table-p}.
2158 (not yet documented)
2161 @xref{Sequence Functions, sequencep}.
2164 @xref{Specifiers, specifierp}.
2167 @xref{Predicates for Strings, stringp}.
2170 @xref{Function Cells, subrp}.
2172 @item subwindow-image-instance-p
2173 @xref{Image Instance Types, subwindow-image-instance-p}.
2176 @xref{Subwindows, subwindowp}.
2179 @xref{Symbols, symbolp}.
2181 @item syntax-table-p
2182 @xref{Syntax Tables, syntax-table-p}.
2184 @item text-image-instance-p
2185 @xref{Image Instance Types, text-image-instance-p}.
2187 @item timeout-event-p
2188 @xref{Event Predicates, timeout-event-p}.
2190 @item toolbar-button-p
2191 @xref{Toolbar, toolbar-button-p}.
2193 @item toolbar-specifier-p
2194 @xref{Toolbar, toolbar-specifier-p}.
2196 @item user-variable-p
2197 @xref{Defining Variables, user-variable-p}.
2200 @xref{Vectors, vectorp}.
2203 @xref{Weak Lists, weak-list-p}.
2207 @xref{Predicates on Numbers, wholenump}.
2210 @item window-configuration-p
2211 @xref{Window Configurations, window-configuration-p}.
2214 @xref{Deleting Windows, window-live-p}.
2217 @xref{Basic Windows, windowp}.
2220 The most general way to check the type of an object is to call the
2221 function @code{type-of}. Recall that each object belongs to one and
2222 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
2223 Data Types}). But @code{type-of} knows nothing about non-primitive
2224 types. In most cases, it is more convenient to use type predicates than
2227 @defun type-of object
2228 This function returns a symbol naming the primitive type of
2229 @var{object}. The value is one of @code{bit-vector}, @code{buffer},
2230 @code{char-table}, @code{character}, @code{charset},
2231 @code{coding-system}, @code{cons}, @code{color-instance},
2232 @code{compiled-function}, @code{console}, @code{database},
2233 @code{device}, @code{event}, @code{extent}, @code{face}, @code{float},
2234 @code{font-instance}, @code{frame}, @code{glyph}, @code{hash-table},
2235 @code{image-instance}, @code{integer}, @code{keymap}, @code{marker},
2236 @code{process}, @code{range-table}, @code{specifier}, @code{string},
2237 @code{subr}, @code{subwindow}, @code{symbol}, @code{toolbar-button},
2238 @code{tooltalk-message}, @code{tooltalk-pattern}, @code{vector},
2239 @code{weak-list}, @code{window}, @code{window-configuration}, or
2247 (type-of '()) ; @r{@code{()} is @code{nil}.}
2255 @node Equality Predicates
2256 @section Equality Predicates
2259 Here we describe two functions that test for equality between any two
2260 objects. Other functions test equality between objects of specific
2261 types, e.g., strings. For these predicates, see the appropriate chapter
2262 describing the data type.
2264 @defun eq object1 object2
2265 This function returns @code{t} if @var{object1} and @var{object2} are
2266 the same object, @code{nil} otherwise. The ``same object'' means that a
2267 change in one will be reflected by the same change in the other.
2269 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
2270 integers with the same value. Also, since symbol names are normally
2271 unique, if the arguments are symbols with the same name, they are
2272 @code{eq}. For other types (e.g., lists, vectors, strings), two
2273 arguments with the same contents or elements are not necessarily
2274 @code{eq} to each other: they are @code{eq} only if they are the same
2277 (The @code{make-symbol} function returns an uninterned symbol that is
2278 not interned in the standard @code{obarray}. When uninterned symbols
2279 are in use, symbol names are no longer unique. Distinct symbols with
2280 the same name are not @code{eq}. @xref{Creating Symbols}.)
2282 NOTE: Under XEmacs 19, characters are really just integers, and thus
2283 characters and integers are @code{eq}. Under SXEmacs and XEmacs 20+, it
2284 was necessary to preserve remnants of this in function such as
2285 @code{old-eq} in order to maintain byte-code compatibility. Byte code
2286 compiled under any Emacs 19 will automatically have calls to @code{eq}
2287 mapped to @code{old-eq} when executed under SXEmacs or XEmacs 20+.
2306 (eq '(1 (2 (3))) '(1 (2 (3))))
2311 (setq foo '(1 (2 (3))))
2312 @result{} (1 (2 (3)))
2315 (eq foo '(1 (2 (3))))
2320 (eq [(1 2) 3] [(1 2) 3])
2325 (eq (point-marker) (point-marker))
2332 @defun old-eq object1 object2
2333 This function exists under SXEmacs and XEmacs 20+ and is exactly like
2334 @code{eq} except that it suffers from the char-int confoundance disease.
2335 In other words, it returns @code{t} if given a character and the
2336 equivalent integer, even though the objects are of different types!
2337 You should @emph{not} ever call this function explicitly in your
2338 code. However, be aware that all calls to @code{eq} in byte code
2339 compiled under version 19 map to @code{old-eq} in SXEmacs or XEmacs 20+.
2341 Likewise for @code{old-equal}, @code{old-memq}, @code{old-member},
2342 @code{old-assq} and @code{old-assoc}.
2346 ;; @r{Remember, this does not apply under XEmacs 19.}
2352 @result{} t ; @r{Eek, we've been infected.}
2354 @result{} nil ; @r{We are still healthy.}
2359 @defun equal object1 object2
2360 This function returns @code{t} if @var{object1} and @var{object2} have
2361 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
2362 arguments are the same object, @code{equal} looks inside nonidentical
2363 arguments to see if their elements are the same. So, if two objects are
2364 @code{eq}, they are @code{equal}, but the converse is not always true.
2378 (equal "asdf" "asdf")
2387 (equal '(1 (2 (3))) '(1 (2 (3))))
2391 (eq '(1 (2 (3))) '(1 (2 (3))))
2396 (equal [(1 2) 3] [(1 2) 3])
2400 (eq [(1 2) 3] [(1 2) 3])
2405 (equal (point-marker) (point-marker))
2410 (eq (point-marker) (point-marker))
2415 Comparison of strings is case-sensitive.
2417 Note that in FSF GNU Emacs, comparison of strings takes into account
2418 their text properties, and you have to use @code{string-equal} if you
2419 want only the strings themselves compared. This difference does not
2420 exist in SXEmacs; @code{equal} and @code{string-equal} always return
2421 the same value on the same strings.
2423 @ignore @c Not true in SXEmacs nor XEmacs
2424 Comparison of strings is case-sensitive and takes account of text
2425 properties as well as the characters in the strings. To compare
2426 two strings' characters without comparing their text properties,
2427 use @code{string=} (@pxref{Text Comparison}).
2432 (equal "asdf" "ASDF")
2437 Two distinct buffers are never @code{equal}, even if their contents
2441 The test for equality is implemented recursively, and circular lists may
2442 therefore cause infinite recursion (leading to an error).