annotate man/lispref/objects.texi @ 1058:d7285d54aa5f

[xemacs-hg @ 2002-10-18 05:43:26 by stephent] cygXpm-noX FAQ <87ptu8b972.fsf@tleepslib.sk.tsukuba.ac.jp>
author stephent
date Fri, 18 Oct 2002 05:43:35 +0000
parents b05e2a249757
children bc9eadea35cf
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1 @c -*-texinfo-*-
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2 @c This is part of the XEmacs Lisp Reference Manual.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4 @c See the file lispref.texi for copying conditions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5 @setfilename ../../info/objects.info
693
b05e2a249757 [xemacs-hg @ 2001-12-14 07:50:06 by stephent]
stephent
parents: 444
diff changeset
6 @node Lisp Data Types, Numbers, Packaging, Top
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7 @chapter Lisp Data Types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8 @cindex object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9 @cindex Lisp object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
10 @cindex type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
11 @cindex data type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
12
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
13 A Lisp @dfn{object} is a piece of data used and manipulated by Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
14 programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
15 possible objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
16
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
17 Every object belongs to at least one type. Objects of the same type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
18 have similar structures and may usually be used in the same contexts.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
19 Types can overlap, and objects can belong to two or more types.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
20 Consequently, we can ask whether an object belongs to a particular type,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
21 but not for ``the'' type of an object.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
22
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
23 @cindex primitive type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
24 A few fundamental object types are built into XEmacs. These, from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
25 which all other types are constructed, are called @dfn{primitive types}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
26 Each object belongs to one and only one primitive type. These types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
27 include @dfn{integer}, @dfn{character} (starting with XEmacs 20.0),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
28 @dfn{float}, @dfn{cons}, @dfn{symbol}, @dfn{string}, @dfn{vector},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
29 @dfn{bit-vector}, @dfn{subr}, @dfn{compiled-function}, @dfn{hash-table},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
30 @dfn{range-table}, @dfn{char-table}, @dfn{weak-list}, and several
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
31 special types, such as @dfn{buffer}, that are related to editing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
32 (@xref{Editing Types}.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
33
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
34 Each primitive type has a corresponding Lisp function that checks
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
35 whether an object is a member of that type.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
36
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
37 Note that Lisp is unlike many other languages in that Lisp objects are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
38 @dfn{self-typing}: the primitive type of the object is implicit in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
39 object itself. For example, if an object is a vector, nothing can treat
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
40 it as a number; Lisp knows it is a vector, not a number.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
41
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
42 In most languages, the programmer must declare the data type of each
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
43 variable, and the type is known by the compiler but not represented in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
44 the data. Such type declarations do not exist in XEmacs Lisp. A Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
45 variable can have any type of value, and it remembers whatever value
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
46 you store in it, type and all.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
47
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
48 This chapter describes the purpose, printed representation, and read
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
49 syntax of each of the standard types in Emacs Lisp. Details on how
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
50 to use these types can be found in later chapters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
51
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
52 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
53 * Printed Representation:: How Lisp objects are represented as text.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
54 * Comments:: Comments and their formatting conventions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
55 * Primitive Types:: List of all primitive types in XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
56 * Programming Types:: Types found in all Lisp systems.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
57 * Editing Types:: Types specific to XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
58 * Window-System Types:: Types specific to windowing systems.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
59 * Type Predicates:: Tests related to types.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
60 * Equality Predicates:: Tests of equality between any two objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
61 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
62
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
63 @node Printed Representation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
64 @section Printed Representation and Read Syntax
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
65 @cindex printed representation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
66 @cindex read syntax
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
67
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
68 The @dfn{printed representation} of an object is the format of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
69 output generated by the Lisp printer (the function @code{prin1}) for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
70 that object. The @dfn{read syntax} of an object is the format of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
71 input accepted by the Lisp reader (the function @code{read}) for that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
72 object. Most objects have more than one possible read syntax. Some
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
73 types of object have no read syntax; except for these cases, the printed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
74 representation of an object is also a read syntax for it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
75
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
76 In other languages, an expression is text; it has no other form. In
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
77 Lisp, an expression is primarily a Lisp object and only secondarily the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
78 text that is the object's read syntax. Often there is no need to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
79 emphasize this distinction, but you must keep it in the back of your
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
80 mind, or you will occasionally be very confused.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
81
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
82 @cindex hash notation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
83 Every type has a printed representation. Some types have no read
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
84 syntax, since it may not make sense to enter objects of these types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
85 directly in a Lisp program. For example, the buffer type does not have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
86 a read syntax. Objects of these types are printed in @dfn{hash
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
87 notation}: the characters @samp{#<} followed by a descriptive string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
88 (typically the type name followed by the name of the object), and closed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
89 with a matching @samp{>}. Hash notation cannot be read at all, so the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
90 Lisp reader signals the error @code{invalid-read-syntax} whenever it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
91 encounters @samp{#<}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
92 @kindex invalid-read-syntax
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
93
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
94 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
95 (current-buffer)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
96 @result{} #<buffer "objects.texi">
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
97 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
98
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
99 When you evaluate an expression interactively, the Lisp interpreter
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
100 first reads the textual representation of it, producing a Lisp object,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
101 and then evaluates that object (@pxref{Evaluation}). However,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
102 evaluation and reading are separate activities. Reading returns the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
103 Lisp object represented by the text that is read; the object may or may
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
104 not be evaluated later. @xref{Input Functions}, for a description of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
105 @code{read}, the basic function for reading objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
106
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
107 @node Comments
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
108 @section Comments
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
109 @cindex comments
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
110 @cindex @samp{;} in comment
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
111
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
112 A @dfn{comment} is text that is written in a program only for the sake
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
113 of humans that read the program, and that has no effect on the meaning
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
114 of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
115 is not within a string or character constant. The comment continues to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
116 the end of line. The Lisp reader discards comments; they do not become
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
117 part of the Lisp objects which represent the program within the Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
118 system.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
119
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
120 The @samp{#@@@var{count}} construct, which skips the next @var{count}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
121 characters, is useful for program-generated comments containing binary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
122 data. The XEmacs Lisp byte compiler uses this in its output files
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
123 (@pxref{Byte Compilation}). It isn't meant for source files, however.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
124
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
125 @xref{Comment Tips}, for conventions for formatting comments.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
126
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
127 @node Primitive Types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
128 @section Primitive Types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
129 @cindex primitive types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
130
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
131 For reference, here is a list of all the primitive types that may
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
132 exist in XEmacs. Note that some of these types may not exist
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
133 in some XEmacs executables; that depends on the options that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
134 XEmacs was configured with.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
135
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
136 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
137 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
138 bit-vector
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
139 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
140 buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
141 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
142 char-table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
143 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
144 character
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
145 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
146 charset
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
147 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
148 coding-system
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
149 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
150 cons
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
151 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
152 color-instance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
153 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
154 compiled-function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
155 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
156 console
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
157 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
158 database
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
159 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
160 device
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
161 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
162 event
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
163 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
164 extent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
165 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
166 face
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
167 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
168 float
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
169 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
170 font-instance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
171 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
172 frame
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
173 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
174 glyph
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
175 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
176 hash-table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
177 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
178 image-instance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
179 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
180 integer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
181 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
182 keymap
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
183 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
184 marker
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
185 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
186 process
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
187 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
188 range-table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
189 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
190 specifier
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
191 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
192 string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
193 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
194 subr
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
195 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
196 subwindow
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
197 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
198 symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
199 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
200 toolbar-button
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
201 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
202 tooltalk-message
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
203 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
204 tooltalk-pattern
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
205 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
206 vector
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
207 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
208 weak-list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
209 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
210 window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
211 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
212 window-configuration
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
213 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
214 x-resource
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
215 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
216
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
217 In addition, the following special types are created internally
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
218 but will never be seen by Lisp code. You may encounter them,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
219 however, if you are debugging XEmacs. The printed representation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
220 of these objects begins @samp{#<INTERNAL EMACS BUG}, which indicates
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
221 to the Lisp programmer that he has found an internal bug in XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
222 if he ever encounters any of these objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
223
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
224 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
225 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
226 char-table-entry
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
227 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
228 command-builder
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
229 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
230 extent-auxiliary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
231 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
232 extent-info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
233 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
234 lcrecord-list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
235 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
236 lstream
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
237 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
238 opaque
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
239 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
240 opaque-list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
241 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
242 popup-data
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
243 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
244 symbol-value-buffer-local
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
245 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
246 symbol-value-forward
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
247 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
248 symbol-value-lisp-magic
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
249 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
250 symbol-value-varalias
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
251 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
252 toolbar-data
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
253 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
254
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
255 @node Programming Types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
256 @section Programming Types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
257 @cindex programming types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
258
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
259 There are two general categories of types in XEmacs Lisp: those having
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
260 to do with Lisp programming, and those having to do with editing. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
261 former exist in many Lisp implementations, in one form or another. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
262 latter are unique to XEmacs Lisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
263
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
264 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
265 * Integer Type:: Numbers without fractional parts.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
266 * Floating Point Type:: Numbers with fractional parts and with a large range.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
267 * Character Type:: The representation of letters, numbers and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
268 control characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
269 * Symbol Type:: A multi-use object that refers to a function,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
270 variable, or property list, and has a unique identity.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
271 * Sequence Type:: Both lists and arrays are classified as sequences.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
272 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
273 * Array Type:: Arrays include strings and vectors.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
274 * String Type:: An (efficient) array of characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
275 * Vector Type:: One-dimensional arrays.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
276 * Bit Vector Type:: An (efficient) array of bits.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
277 * Function Type:: A piece of executable code you can call from elsewhere.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
278 * Macro Type:: A method of expanding an expression into another
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
279 expression, more fundamental but less pretty.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
280 * Primitive Function Type:: A function written in C, callable from Lisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
281 * Compiled-Function Type:: A function written in Lisp, then compiled.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
282 * Autoload Type:: A type used for automatically loading seldom-used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
283 functions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
284 * Char Table Type:: A mapping from characters to Lisp objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
285 * Hash Table Type:: A fast mapping between Lisp objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
286 * Range Table Type:: A mapping from ranges of integers to Lisp objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
287 * Weak List Type:: A list with special garbage-collection properties.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
288 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
289
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
290 @node Integer Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
291 @subsection Integer Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
292
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
293 The range of values for integers in XEmacs Lisp is @minus{}134217728 to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
294 134217727 (28 bits; i.e.,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
295 @ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
296 -2**27
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
297 @end ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
298 @tex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
299 $-2^{27}$
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
300 @end tex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
301 to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
302 @ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
303 2**27 - 1)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
304 @end ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
305 @tex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
306 $2^{28}-1$)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
307 @end tex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
308 on most machines. (Some machines, in particular 64-bit machines such as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
309 the DEC Alpha, may provide a wider range.) It is important to note that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
310 the XEmacs Lisp arithmetic functions do not check for overflow. Thus
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
311 @code{(1+ 134217727)} is @minus{}134217728 on most machines. (However,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
312 you @emph{will} get an error if you attempt to read an out-of-range
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
313 number using the Lisp reader.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
314
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
315 The read syntax for integers is a sequence of (base ten) digits with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
316 an optional sign at the beginning. (The printed representation produced
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
317 by the Lisp interpreter never has a leading @samp{+}.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
318
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
319 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
320 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
321 -1 ; @r{The integer -1.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
322 1 ; @r{The integer 1.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
323 +1 ; @r{Also the integer 1.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
324 268435457 ; @r{Causes an error on a 28-bit implementation.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
325 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
326 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
327
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
328 @xref{Numbers}, for more information.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
329
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
330 @node Floating Point Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
331 @subsection Floating Point Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
332
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
333 XEmacs supports floating point numbers. The precise range of floating
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
334 point numbers is machine-specific.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
335
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
336 The printed representation for floating point numbers requires either
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
337 a decimal point (with at least one digit following), an exponent, or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
338 both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
339 @samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
340 number whose value is 1500. They are all equivalent.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
341
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
342 @xref{Numbers}, for more information.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
343
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
344 @node Character Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
345 @subsection Character Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
346 @cindex @sc{ascii} character codes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
347 @cindex char-int confoundance disease
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
348
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
349 In XEmacs version 19, and in all versions of FSF GNU Emacs, a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
350 @dfn{character} in XEmacs Lisp is nothing more than an integer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
351 This is yet another holdover from XEmacs Lisp's derivation from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
352 vintage-1980 Lisps; modern versions of Lisp consider this equivalence
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
353 a bad idea, and have separate character types. In XEmacs version 20,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
354 the modern convention is followed, and characters are their own
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
355 primitive types. (This change was necessary in order for @sc{mule},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
356 i.e. Asian-language, support to be correctly implemented.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
357
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
358 Even in XEmacs version 20, remnants of the equivalence between
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
359 characters and integers still exist; this is termed the @dfn{char-int
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
360 confoundance disease}. In particular, many functions such as @code{eq},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
361 @code{equal}, and @code{memq} have equivalent functions (@code{old-eq},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
362 @code{old-equal}, @code{old-memq}, etc.) that pretend like characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
363 are integers are the same. Byte code compiled under any version 19
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
364 Emacs will have all such functions mapped to their @code{old-} equivalents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
365 when the byte code is read into XEmacs 20. This is to preserve
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
366 compatibility---Emacs 19 converts all constant characters to the equivalent
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
367 integer during byte-compilation, and thus there is no other way to preserve
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
368 byte-code compatibility even if the code has specifically been written
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
369 with the distinction between characters and integers in mind.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
370
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
371 Every character has an equivalent integer, called the @dfn{character
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
372 code}. For example, the character @kbd{A} is represented as the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
373 @w{integer 65}, following the standard @sc{ascii} representation of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
374 characters. If XEmacs was not compiled with @sc{mule} support, the
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
375 range of this integer will always be 0 to 255---eight bits, or one
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
376 byte. (Integers outside this range are accepted but silently truncated;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
377 however, you should most decidedly @emph{not} rely on this, because it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
378 will not work under XEmacs with @sc{mule} support.) When @sc{mule}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
379 support is present, the range of character codes is much
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
380 larger. (Currently, 19 bits are used.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
381
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
382 FSF GNU Emacs uses kludgy character codes above 255 to represent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
383 keyboard input of @sc{ascii} characters in combination with certain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
384 modifiers. XEmacs does not use this (a more general mechanism is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
385 used that does not distinguish between @sc{ascii} keys and other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
386 keys), so you will never find character codes above 255 in a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
387 non-@sc{mule} XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
388
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
389 Individual characters are not often used in programs. It is far more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
390 common to work with @emph{strings}, which are sequences composed of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
391 characters. @xref{String Type}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
392
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
393 @cindex read syntax for characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
394 @cindex printed representation for characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
395 @cindex syntax for characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
396
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
397 The read syntax for characters begins with a question mark, followed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
398 by the character (if it's printable) or some symbolic representation of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
399 it. In XEmacs 20, where characters are their own type, this is also the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
400 print representation. In XEmacs 19, however, where characters are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
401 really integers, the printed representation of a character is a decimal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
402 number. This is also a possible read syntax for a character, but
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
403 writing characters that way in Lisp programs is a very bad idea. You
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
404 should @emph{always} use the special read syntax formats that XEmacs Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
405 provides for characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
406
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
407 The usual read syntax for alphanumeric characters is a question mark
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
408 followed by the character; thus, @samp{?A} for the character
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
409 @kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
410 character @kbd{a}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
411
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
412 For example:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
413
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
414 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
415 ;; @r{Under XEmacs 20:}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
416 ?Q @result{} ?Q ?q @result{} ?q
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
417 (char-int ?Q) @result{} 81
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
418 ;; @r{Under XEmacs 19:}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
419 ?Q @result{} 81 ?q @result{} 113
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
420 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
421
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
422 You can use the same syntax for punctuation characters, but it is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
423 often a good idea to add a @samp{\} so that the Emacs commands for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
424 editing Lisp code don't get confused. For example, @samp{?\ } is the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
425 way to write the space character. If the character is @samp{\}, you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
426 @emph{must} use a second @samp{\} to quote it: @samp{?\\}. XEmacs 20
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
427 always prints punctuation characters with a @samp{\} in front of them,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
428 to avoid confusion.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
429
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
430 @cindex whitespace
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
431 @cindex bell character
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
432 @cindex @samp{\a}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
433 @cindex backspace
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
434 @cindex @samp{\b}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
435 @cindex tab
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
436 @cindex @samp{\t}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
437 @cindex vertical tab
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
438 @cindex @samp{\v}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
439 @cindex formfeed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
440 @cindex @samp{\f}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
441 @cindex newline
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
442 @cindex @samp{\n}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
443 @cindex return
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
444 @cindex @samp{\r}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
445 @cindex escape
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
446 @cindex @samp{\e}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
447 You can express the characters Control-g, backspace, tab, newline,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
448 vertical tab, formfeed, return, and escape as @samp{?\a}, @samp{?\b},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
449 @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
450 respectively. Their character codes are 7, 8, 9, 10, 11, 12, 13, and 27
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
451 in decimal. Thus,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
452
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
453 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
454 ;; @r{Under XEmacs 20:}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
455 ?\a @result{} ?\^G ; @r{@kbd{C-g}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
456 (char-int ?\a) @result{} 7
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
457 ?\b @result{} ?\^H ; @r{backspace, @key{BS}, @kbd{C-h}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
458 (char-int ?\b) @result{} 8
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
459 ?\t @result{} ?\t ; @r{tab, @key{TAB}, @kbd{C-i}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
460 (char-int ?\t) @result{} 9
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
461 ?\n @result{} ?\n ; @r{newline, @key{LFD}, @kbd{C-j}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
462 ?\v @result{} ?\^K ; @r{vertical tab, @kbd{C-k}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
463 ?\f @result{} ?\^L ; @r{formfeed character, @kbd{C-l}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
464 ?\r @result{} ?\r ; @r{carriage return, @key{RET}, @kbd{C-m}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
465 ?\e @result{} ?\^[ ; @r{escape character, @key{ESC}, @kbd{C-[}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
466 ?\\ @result{} ?\\ ; @r{backslash character, @kbd{\}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
467 ;; @r{Under XEmacs 19:}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
468 ?\a @result{} 7 ; @r{@kbd{C-g}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
469 ?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
470 ?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
471 ?\n @result{} 10 ; @r{newline, @key{LFD}, @kbd{C-j}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
472 ?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
473 ?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
474 ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
475 ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
476 ?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
477 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
478
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
479 @cindex escape sequence
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
480 These sequences which start with backslash are also known as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
481 @dfn{escape sequences}, because backslash plays the role of an escape
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
482 character; this usage has nothing to do with the character @key{ESC}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
483
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
484 @cindex control characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
485 Control characters may be represented using yet another read syntax.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
486 This consists of a question mark followed by a backslash, caret, and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
487 corresponding non-control character, in either upper or lower case. For
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
488 example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
489 character @kbd{C-i}, the character whose value is 9.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
490
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
491 Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
492 equivalent to @samp{?\^I} and to @samp{?\^i}:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
493
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
494 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
495 ;; @r{Under XEmacs 20:}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
496 ?\^I @result{} ?\t ?\C-I @result{} ?\t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
497 (char-int ?\^I) @result{} 9
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
498 ;; @r{Under XEmacs 19:}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
499 ?\^I @result{} 9 ?\C-I @result{} 9
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
500 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
501
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
502 There is also a character read syntax beginning with @samp{\M-}. This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
503 sets the high bit of the character code (same as adding 128 to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
504 character code). For example, @samp{?\M-A} stands for the character
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
505 with character code 193, or 128 plus 65. You should @emph{not} use this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
506 syntax in your programs. It is a holdover of yet another confoundance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
507 disease from earlier Emacsen. (This was used to represent keyboard input
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
508 with the @key{META} key set, thus the @samp{M}; however, it conflicts
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
509 with the legitimate @sc{iso}-8859-1 interpretation of the character code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
510 For example, character code 193 is a lowercase @samp{a} with an acute
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
511 accent, in @sc{iso}-8859-1.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
512
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
513 @ignore @c None of this crap applies to XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
514 For use in strings and buffers, you are limited to the control
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
515 characters that exist in @sc{ascii}, but for keyboard input purposes,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
516 you can turn any character into a control character with @samp{C-}. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
517 character codes for these non-@sc{ascii} control characters include the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
518 @iftex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
519 $2^{26}$
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
520 @end iftex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
521 @ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
522 2**26
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
523 @end ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
524 bit as well as the code for the corresponding non-control
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
525 character. Ordinary terminals have no way of generating non-@sc{ASCII}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
526 control characters, but you can generate them straightforwardly using an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
527 X terminal.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
528
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
529 For historical reasons, Emacs treats the @key{DEL} character as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
530 the control equivalent of @kbd{?}:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
531
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
532 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
533 ?\^? @result{} 127 ?\C-? @result{} 127
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
534 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
535
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
536 @noindent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
537 As a result, it is currently not possible to represent the character
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
538 @kbd{Control-?}, which is a meaningful input character under X. It is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
539 not easy to change this as various Lisp files refer to @key{DEL} in this
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
540 way.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
541
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
542 For representing control characters to be found in files or strings,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
543 we recommend the @samp{^} syntax; for control characters in keyboard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
544 input, we prefer the @samp{C-} syntax. This does not affect the meaning
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
545 of the program, but may guide the understanding of people who read it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
546
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
547 @cindex meta characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
548 A @dfn{meta character} is a character typed with the @key{META}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
549 modifier key. The integer that represents such a character has the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
550 @iftex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
551 $2^{27}$
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
552 @end iftex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
553 @ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
554 2**27
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
555 @end ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
556 bit set (which on most machines makes it a negative number). We
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
557 use high bits for this and other modifiers to make possible a wide range
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
558 of basic character codes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
559
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
560 In a string, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
561 @iftex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
562 $2^{7}$
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
563 @end iftex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
564 @ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
565 2**7
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
566 @end ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
567 bit indicates a meta character, so the meta
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
568 characters that can fit in a string have codes in the range from 128 to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
569 255, and are the meta versions of the ordinary @sc{ASCII} characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
570 (In Emacs versions 18 and older, this convention was used for characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
571 outside of strings as well.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
572
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
573 The read syntax for meta characters uses @samp{\M-}. For example,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
574 @samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
575 octal character codes (see below), with @samp{\C-}, or with any other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
576 syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
577 or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
578 @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
579
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
580 The case of an ordinary letter is indicated by its character code as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
581 part of @sc{ASCII}, but @sc{ASCII} has no way to represent whether a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
582 control character is upper case or lower case. Emacs uses the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
583 @iftex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
584 $2^{25}$
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
585 @end iftex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
586 @ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
587 2**25
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
588 @end ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
589 bit to indicate that the shift key was used for typing a control
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
590 character. This distinction is possible only when you use X terminals
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
591 or other special terminals; ordinary terminals do not indicate the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
592 distinction to the computer in any way.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
593
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
594 @cindex hyper characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
595 @cindex super characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
596 @cindex alt characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
597 The X Window System defines three other modifier bits that can be set
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
598 in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
599 for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
600 @samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
601 @iftex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
602 Numerically, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
603 bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
604 @end iftex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
605 @ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
606 Numerically, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
607 bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
608 @end ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
609 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
610
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
611 @cindex @samp{?} in character constant
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
612 @cindex question mark in character constant
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
613 @cindex @samp{\} in character constant
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
614 @cindex backslash in character constant
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
615 @cindex octal character code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
616 Finally, the most general read syntax consists of a question mark
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
617 followed by a backslash and the character code in octal (up to three
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
618 octal digits); thus, @samp{?\101} for the character @kbd{A},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
619 @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
620 character @kbd{C-b}. Although this syntax can represent any @sc{ascii}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
621 character, it is preferred only when the precise octal value is more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
622 important than the @sc{ascii} representation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
623
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
624 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
625 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
626 ;; @r{Under XEmacs 20:}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
627 ?\012 @result{} ?\n ?\n @result{} ?\n ?\C-j @result{} ?\n
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
628 ?\101 @result{} ?A ?A @result{} ?A
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
629 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
630 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
631 ;; @r{Under XEmacs 19:}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
632 ?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
633 ?\101 @result{} 65 ?A @result{} 65
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
634 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
635 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
636
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
637 A backslash is allowed, and harmless, preceding any character without
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
638 a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
639 There is no reason to add a backslash before most characters. However,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
640 you should add a backslash before any of the characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
641 @samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
642 Lisp code. Also add a backslash before whitespace characters such as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
643 space, tab, newline and formfeed. However, it is cleaner to use one of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
644 the easily readable escape sequences, such as @samp{\t}, instead of an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
645 actual whitespace character such as a tab.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
646
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
647 @node Symbol Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
648 @subsection Symbol Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
649
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
650 A @dfn{symbol} in XEmacs Lisp is an object with a name. The symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
651 name serves as the printed representation of the symbol. In ordinary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
652 use, the name is unique---no two symbols have the same name.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
653
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
654 A symbol can serve as a variable, as a function name, or to hold a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
655 property list. Or it may serve only to be distinct from all other Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
656 objects, so that its presence in a data structure may be recognized
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
657 reliably. In a given context, usually only one of these uses is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
658 intended. But you can use one symbol in all of these ways,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
659 independently.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
660
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
661 @cindex @samp{\} in symbols
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
662 @cindex backslash in symbols
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
663 A symbol name can contain any characters whatever. Most symbol names
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
664 are written with letters, digits, and the punctuation characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
665 @samp{-+=*/}. Such names require no special punctuation; the characters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
666 of the name suffice as long as the name does not look like a number.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
667 (If it does, write a @samp{\} at the beginning of the name to force
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
668 interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}} are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
669 less often used but also require no special punctuation. Any other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
670 characters may be included in a symbol's name by escaping them with a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
671 backslash. In contrast to its use in strings, however, a backslash in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
672 the name of a symbol simply quotes the single character that follows the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
673 backslash. For example, in a string, @samp{\t} represents a tab
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
674 character; in the name of a symbol, however, @samp{\t} merely quotes the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
675 letter @kbd{t}. To have a symbol with a tab character in its name, you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
676 must actually use a tab (preceded with a backslash). But it's rare to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
677 do such a thing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
678
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
679 @cindex CL note---case of letters
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
680 @quotation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
681 @b{Common Lisp note:} In Common Lisp, lower case letters are always
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
682 ``folded'' to upper case, unless they are explicitly escaped. In Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
683 Lisp, upper case and lower case letters are distinct.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
684 @end quotation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
685
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
686 Here are several examples of symbol names. Note that the @samp{+} in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
687 the fifth example is escaped to prevent it from being read as a number.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
688 This is not necessary in the sixth example because the rest of the name
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
689 makes it invalid as a number.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
690
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
691 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
692 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
693 foo ; @r{A symbol named @samp{foo}.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
694 FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
695 char-to-string ; @r{A symbol named @samp{char-to-string}.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
696 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
697 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
698 1+ ; @r{A symbol named @samp{1+}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
699 ; @r{(not @samp{+1}, which is an integer).}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
700 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
701 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
702 \+1 ; @r{A symbol named @samp{+1}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
703 ; @r{(not a very readable name).}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
704 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
705 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
706 \(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
707 @c the @'s in this next line use up three characters, hence the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
708 @c apparent misalignment of the comment.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
709 +-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
710 ; @r{These characters need not be escaped.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
711 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
712 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
713
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
714 @node Sequence Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
715 @subsection Sequence Types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
716
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
717 A @dfn{sequence} is a Lisp object that represents an ordered set of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
718 elements. There are two kinds of sequence in XEmacs Lisp, lists and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
719 arrays. Thus, an object of type list or of type array is also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
720 considered a sequence.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
721
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
722 Arrays are further subdivided into strings, vectors, and bit vectors.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
723 Vectors can hold elements of any type, but string elements must be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
724 characters, and bit vector elements must be either 0 or 1. However, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
725 characters in a string can have extents (@pxref{Extents}) and text
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
726 properties (@pxref{Text Properties}) like characters in a buffer;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
727 vectors do not support extents or text properties even when their
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
728 elements happen to be characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
729
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
730 Lists, strings, vectors, and bit vectors are different, but they have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
731 important similarities. For example, all have a length @var{l}, and all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
732 have elements which can be indexed from zero to @var{l} minus one.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
733 Also, several functions, called sequence functions, accept any kind of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
734 sequence. For example, the function @code{elt} can be used to extract
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
735 an element of a sequence, given its index. @xref{Sequences Arrays
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
736 Vectors}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
737
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
738 It is impossible to read the same sequence twice, since sequences are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
739 always created anew upon reading. If you read the read syntax for a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
740 sequence twice, you get two sequences with equal contents. There is one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
741 exception: the empty list @code{()} always stands for the same object,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
742 @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
743
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
744 @node Cons Cell Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
745 @subsection Cons Cell and List Types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
746 @cindex address field of register
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
747 @cindex decrement field of register
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
748
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
749 A @dfn{cons cell} is an object comprising two pointers named the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
750 @sc{car} and the @sc{cdr}. Each of them can point to any Lisp object.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
751
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
752 A @dfn{list} is a series of cons cells, linked together so that the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
753 @sc{cdr} of each cons cell points either to another cons cell or to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
754 empty list. @xref{Lists}, for functions that work on lists. Because
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
755 most cons cells are used as part of lists, the phrase @dfn{list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
756 structure} has come to refer to any structure made out of cons cells.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
757
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
758 The names @sc{car} and @sc{cdr} have only historical meaning now. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
759 original Lisp implementation ran on an @w{IBM 704} computer which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
760 divided words into two parts, called the ``address'' part and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
761 ``decrement''; @sc{car} was an instruction to extract the contents of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
762 the address part of a register, and @sc{cdr} an instruction to extract
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
763 the contents of the decrement. By contrast, ``cons cells'' are named
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
764 for the function @code{cons} that creates them, which in turn is named
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
765 for its purpose, the construction of cells.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
766
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
767 @cindex atom
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
768 Because cons cells are so central to Lisp, we also have a word for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
769 ``an object which is not a cons cell''. These objects are called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
770 @dfn{atoms}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
771
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
772 @cindex parenthesis
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
773 The read syntax and printed representation for lists are identical, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
774 consist of a left parenthesis, an arbitrary number of elements, and a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
775 right parenthesis.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
776
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
777 Upon reading, each object inside the parentheses becomes an element
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
778 of the list. That is, a cons cell is made for each element. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
779 @sc{car} of the cons cell points to the element, and its @sc{cdr} points
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
780 to the next cons cell of the list, which holds the next element in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
781 list. The @sc{cdr} of the last cons cell is set to point to @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
782
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
783 @cindex box diagrams, for lists
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
784 @cindex diagrams, boxed, for lists
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
785 A list can be illustrated by a diagram in which the cons cells are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
786 shown as pairs of boxes. (The Lisp reader cannot read such an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
787 illustration; unlike the textual notation, which can be understood by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
788 both humans and computers, the box illustrations can be understood only
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
789 by humans.) The following represents the three-element list @code{(rose
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
790 violet buttercup)}:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
791
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
792 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
793 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
794 ___ ___ ___ ___ ___ ___
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
795 |___|___|--> |___|___|--> |___|___|--> nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
796 | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
797 | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
798 --> rose --> violet --> buttercup
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
799 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
800 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
801
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
802 In this diagram, each box represents a slot that can refer to any Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
803 object. Each pair of boxes represents a cons cell. Each arrow is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
804 reference to a Lisp object, either an atom or another cons cell.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
805
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
806 In this example, the first box, the @sc{car} of the first cons cell,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
807 refers to or ``contains'' @code{rose} (a symbol). The second box, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
808 @sc{cdr} of the first cons cell, refers to the next pair of boxes, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
809 second cons cell. The @sc{car} of the second cons cell refers to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
810 @code{violet} and the @sc{cdr} refers to the third cons cell. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
811 @sc{cdr} of the third (and last) cons cell refers to @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
812
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
813 Here is another diagram of the same list, @code{(rose violet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
814 buttercup)}, sketched in a different manner:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
815
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
816 @smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
817 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
818 --------------- ---------------- -------------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
819 | car | cdr | | car | cdr | | car | cdr |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
820 | rose | o-------->| violet | o-------->| buttercup | nil |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
821 | | | | | | | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
822 --------------- ---------------- -------------------
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
823 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
824 @end smallexample
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
825
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
826 @cindex @samp{(@dots{})} in lists
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
827 @cindex @code{nil} in lists
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
828 @cindex empty list
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
829 A list with no elements in it is the @dfn{empty list}; it is identical
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
830 to the symbol @code{nil}. In other words, @code{nil} is both a symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
831 and a list.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
832
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
833 Here are examples of lists written in Lisp syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
834
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
835 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
836 (A 2 "A") ; @r{A list of three elements.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
837 () ; @r{A list of no elements (the empty list).}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
838 nil ; @r{A list of no elements (the empty list).}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
839 ("A ()") ; @r{A list of one element: the string @code{"A ()"}.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
840 (A ()) ; @r{A list of two elements: @code{A} and the empty list.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
841 (A nil) ; @r{Equivalent to the previous.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
842 ((A B C)) ; @r{A list of one element}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
843 ; @r{(which is a list of three elements).}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
844 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
845
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
846 Here is the list @code{(A ())}, or equivalently @code{(A nil)},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
847 depicted with boxes and arrows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
848
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
849 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
850 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
851 ___ ___ ___ ___
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
852 |___|___|--> |___|___|--> nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
853 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
854 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
855 --> A --> nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
856 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
857 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
858
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
859 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
860 * Dotted Pair Notation:: An alternative syntax for lists.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
861 * Association List Type:: A specially constructed list.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
862 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
863
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
864 @node Dotted Pair Notation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
865 @subsubsection Dotted Pair Notation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
866 @cindex dotted pair notation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
867 @cindex @samp{.} in lists
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
868
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
869 @dfn{Dotted pair notation} is an alternative syntax for cons cells
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
870 that represents the @sc{car} and @sc{cdr} explicitly. In this syntax,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
871 @code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
872 the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
873 pair notation is therefore more general than list syntax. In the dotted
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
874 pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
875 . nil)))}. For @code{nil}-terminated lists, the two notations produce
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
876 the same result, but list notation is usually clearer and more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
877 convenient when it is applicable. When printing a list, the dotted pair
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
878 notation is only used if the @sc{cdr} of a cell is not a list.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
879
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
880 Here's how box notation can illustrate dotted pairs. This example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
881 shows the pair @code{(rose . violet)}:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
882
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
883 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
884 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
885 ___ ___
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
886 |___|___|--> violet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
887 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
888 |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
889 --> rose
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
890 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
891 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
892
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
893 Dotted pair notation can be combined with list notation to represent a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
894 chain of cons cells with a non-@code{nil} final @sc{cdr}. For example,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
895 @code{(rose violet . buttercup)} is equivalent to @code{(rose . (violet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
896 . buttercup))}. The object looks like this:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
897
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
898 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
899 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
900 ___ ___ ___ ___
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
901 |___|___|--> |___|___|--> buttercup
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
902 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
903 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
904 --> rose --> violet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
905 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
906 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
907
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
908 These diagrams make it evident why @w{@code{(rose .@: violet .@:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
909 buttercup)}} is invalid syntax; it would require a cons cell that has
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
910 three parts rather than two.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
911
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
912 The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
913 and looks like this:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
914
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
915 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
916 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
917 ___ ___ ___ ___
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
918 |___|___|--> |___|___|--> nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
919 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
920 | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
921 --> rose --> violet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
922 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
923 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
924
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
925 Similarly, the three-element list @code{(rose violet buttercup)}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
926 is equivalent to @code{(rose . (violet . (buttercup)))}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
927 @ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
928 It looks like this:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
929
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
930 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
931 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
932 ___ ___ ___ ___ ___ ___
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
933 |___|___|--> |___|___|--> |___|___|--> nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
934 | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
935 | | |
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
936 --> rose --> violet --> buttercup
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
937 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
938 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
939 @end ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
940
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
941 @node Association List Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
942 @subsubsection Association List Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
943
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
944 An @dfn{association list} or @dfn{alist} is a specially-constructed
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
945 list whose elements are cons cells. In each element, the @sc{car} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
946 considered a @dfn{key}, and the @sc{cdr} is considered an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
947 @dfn{associated value}. (In some cases, the associated value is stored
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
948 in the @sc{car} of the @sc{cdr}.) Association lists are often used as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
949 stacks, since it is easy to add or remove associations at the front of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
950 the list.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
951
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
952 For example,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
953
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
954 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
955 (setq alist-of-colors
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
956 '((rose . red) (lily . white) (buttercup . yellow)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
957 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
958
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
959 @noindent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
960 sets the variable @code{alist-of-colors} to an alist of three elements. In the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
961 first element, @code{rose} is the key and @code{red} is the value.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
962
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
963 @xref{Association Lists}, for a further explanation of alists and for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
964 functions that work on alists.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
965
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
966 @node Array Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
967 @subsection Array Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
968
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
969 An @dfn{array} is composed of an arbitrary number of slots for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
970 referring to other Lisp objects, arranged in a contiguous block of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
971 memory. Accessing any element of an array takes the same amount of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
972 time. In contrast, accessing an element of a list requires time
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
973 proportional to the position of the element in the list. (Elements at
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
974 the end of a list take longer to access than elements at the beginning
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
975 of a list.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
976
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
977 XEmacs defines three types of array, strings, vectors, and bit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
978 vectors. A string is an array of characters, a vector is an array of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
979 arbitrary objects, and a bit vector is an array of 1's and 0's. All are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
980 one-dimensional. (Most other programming languages support
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
981 multidimensional arrays, but they are not essential; you can get the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
982 same effect with an array of arrays.) Each type of array has its own
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
983 read syntax; see @ref{String Type}, @ref{Vector Type}, and @ref{Bit
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
984 Vector Type}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
985
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
986 An array may have any length up to the largest integer; but once
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
987 created, it has a fixed size. The first element of an array has index
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
988 zero, the second element has index 1, and so on. This is called
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
989 @dfn{zero-origin} indexing. For example, an array of four elements has
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
990 indices 0, 1, 2, @w{and 3}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
991
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
992 The array type is contained in the sequence type and contains the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
993 string type, the vector type, and the bit vector type.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
994
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
995 @node String Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
996 @subsection String Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
997
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
998 A @dfn{string} is an array of characters. Strings are used for many
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
999 purposes in XEmacs, as can be expected in a text editor; for example, as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1000 the names of Lisp symbols, as messages for the user, and to represent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1001 text extracted from buffers. Strings in Lisp are constants: evaluation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1002 of a string returns the same string.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1003
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1004 @cindex @samp{"} in strings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1005 @cindex double-quote in strings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1006 @cindex @samp{\} in strings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1007 @cindex backslash in strings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1008 The read syntax for strings is a double-quote, an arbitrary number of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1009 characters, and another double-quote, @code{"like this"}. The Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1010 reader accepts the same formats for reading the characters of a string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1011 as it does for reading single characters (without the question mark that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1012 begins a character literal). You can enter a nonprinting character such
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1013 as tab or @kbd{C-a} using the convenient escape sequences, like this:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1014 @code{"\t, \C-a"}. You can include a double-quote in a string by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1015 preceding it with a backslash; thus, @code{"\""} is a string containing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1016 just a single double-quote character. (@xref{Character Type}, for a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1017 description of the read syntax for characters.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1018
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1019 @ignore @c More ill-conceived FSF Emacs crap.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1020 If you use the @samp{\M-} syntax to indicate a meta character in a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1021 string constant, this sets the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1022 @iftex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1023 $2^{7}$
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1024 @end iftex
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1025 @ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1026 2**7
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1027 @end ifinfo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1028 bit of the character in the string.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1029 This is not the same representation that the meta modifier has in a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1030 character on its own (not inside a string). @xref{Character Type}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1031
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1032 Strings cannot hold characters that have the hyper, super, or alt
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1033 modifiers; they can hold @sc{ASCII} control characters, but no others.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1034 They do not distinguish case in @sc{ASCII} control characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1035 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1036
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1037 The printed representation of a string consists of a double-quote, the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1038 characters it contains, and another double-quote. However, you must
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1039 escape any backslash or double-quote characters in the string with a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1040 backslash, like this: @code{"this \" is an embedded quote"}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1041
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1042 The newline character is not special in the read syntax for strings;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1043 if you write a new line between the double-quotes, it becomes a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1044 character in the string. But an escaped newline---one that is preceded
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1045 by @samp{\}---does not become part of the string; i.e., the Lisp reader
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1046 ignores an escaped newline while reading a string.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1047 @cindex newline in strings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1048
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1049 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1050 "It is useful to include newlines
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1051 in documentation strings,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1052 but the newline is \
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1053 ignored if escaped."
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1054 @result{} "It is useful to include newlines
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1055 in documentation strings,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1056 but the newline is ignored if escaped."
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1057 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1058
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1059 A string can hold extents and properties of the text it contains, in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1060 addition to the characters themselves. This enables programs that copy
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1061 text between strings and buffers to preserve the extents and properties
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1062 with no special effort. @xref{Extents}, @xref{Text Properties}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1063
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1064 Note that FSF GNU Emacs has a special read and print syntax for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1065 strings with text properties, but XEmacs does not currently implement
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1066 this. It was judged better not to include this in XEmacs because it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1067 entails that @code{equal} return @code{nil} when passed a string with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1068 text properties and the equivalent string without text properties, which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1069 is often counter-intuitive.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1070
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1071 @ignore @c Not in XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1072 Strings with text
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1073 properties have a special read and print syntax:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1074
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1075 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1076 #("@var{characters}" @var{property-data}...)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1077 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1078
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1079 @noindent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1080 where @var{property-data} consists of zero or more elements, in groups
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1081 of three as follows:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1082
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1083 @example
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1084 @var{start} @var{end} @var{plist}
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1085 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1086
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1087 @noindent
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
1088 The elements @var{start} and @var{end} are integers, and together specify
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1089 a range of indices in the string; @var{plist} is the property list for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1090 that range.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1091 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1092
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1093 @xref{Strings and Characters}, for functions that work on strings.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1094
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1095 @node Vector Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1096 @subsection Vector Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1097
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1098 A @dfn{vector} is a one-dimensional array of elements of any type. It
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1099 takes a constant amount of time to access any element of a vector. (In
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1100 a list, the access time of an element is proportional to the distance of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1101 the element from the beginning of the list.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1102
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1103 The printed representation of a vector consists of a left square
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1104 bracket, the elements, and a right square bracket. This is also the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1105 read syntax. Like numbers and strings, vectors are considered constants
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1106 for evaluation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1107
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1108 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1109 [1 "two" (three)] ; @r{A vector of three elements.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1110 @result{} [1 "two" (three)]
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1111 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1112
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1113 @xref{Vectors}, for functions that work with vectors.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1114
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1115 @node Bit Vector Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1116 @subsection Bit Vector Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1117
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1118 A @dfn{bit vector} is a one-dimensional array of 1's and 0's. It
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1119 takes a constant amount of time to access any element of a bit vector,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1120 as for vectors. Bit vectors have an extremely compact internal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1121 representation (one machine bit per element), which makes them ideal
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1122 for keeping track of unordered sets, large collections of boolean values,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1123 etc.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1124
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1125 The printed representation of a bit vector consists of @samp{#*}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1126 followed by the bits in the vector. This is also the read syntax. Like
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1127 numbers, strings, and vectors, bit vectors are considered constants for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1128 evaluation.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1129
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1130 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1131 #*00101000 ; @r{A bit vector of eight elements.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1132 @result{} #*00101000
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1133 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1134
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1135 @xref{Bit Vectors}, for functions that work with bit vectors.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1136
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1137 @node Function Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1138 @subsection Function Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1139
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1140 Just as functions in other programming languages are executable,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1141 @dfn{Lisp function} objects are pieces of executable code. However,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1142 functions in Lisp are primarily Lisp objects, and only secondarily the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1143 text which represents them. These Lisp objects are lambda expressions:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1144 lists whose first element is the symbol @code{lambda} (@pxref{Lambda
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1145 Expressions}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1146
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1147 In most programming languages, it is impossible to have a function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1148 without a name. In Lisp, a function has no intrinsic name. A lambda
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1149 expression is also called an @dfn{anonymous function} (@pxref{Anonymous
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1150 Functions}). A named function in Lisp is actually a symbol with a valid
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1151 function in its function cell (@pxref{Defining Functions}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1152
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1153 Most of the time, functions are called when their names are written in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1154 Lisp expressions in Lisp programs. However, you can construct or obtain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1155 a function object at run time and then call it with the primitive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1156 functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1157
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1158 @node Macro Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1159 @subsection Macro Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1160
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1161 A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1162 language. It is represented as an object much like a function, but with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1163 different parameter-passing semantics. A Lisp macro has the form of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1164 list whose first element is the symbol @code{macro} and whose @sc{cdr}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1165 is a Lisp function object, including the @code{lambda} symbol.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1166
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1167 Lisp macro objects are usually defined with the built-in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1168 @code{defmacro} function, but any list that begins with @code{macro} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1169 a macro as far as XEmacs is concerned. @xref{Macros}, for an explanation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1170 of how to write a macro.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1171
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1172 @node Primitive Function Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1173 @subsection Primitive Function Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1174 @cindex special forms
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1175
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1176 A @dfn{primitive function} is a function callable from Lisp but
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1177 written in the C programming language. Primitive functions are also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1178 called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1179 derived from ``subroutine''.) Most primitive functions evaluate all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1180 their arguments when they are called. A primitive function that does
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1181 not evaluate all its arguments is called a @dfn{special form}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1182 (@pxref{Special Forms}).@refill
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1183
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1184 It does not matter to the caller of a function whether the function is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1185 primitive. However, this does matter if you try to substitute a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1186 function written in Lisp for a primitive of the same name. The reason
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1187 is that the primitive function may be called directly from C code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1188 Calls to the redefined function from Lisp will use the new definition,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1189 but calls from C code may still use the built-in definition.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1190
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1191 The term @dfn{function} refers to all Emacs functions, whether written
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1192 in Lisp or C. @xref{Function Type}, for information about the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1193 functions written in Lisp.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1194
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1195 Primitive functions have no read syntax and print in hash notation
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1196 with the name of the subroutine.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1197
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1198 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1199 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1200 (symbol-function 'car) ; @r{Access the function cell}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1201 ; @r{of the symbol.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1202 @result{} #<subr car>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1203 (subrp (symbol-function 'car)) ; @r{Is this a primitive function?}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1204 @result{} t ; @r{Yes.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1205 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1206 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1207
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1208 @node Compiled-Function Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1209 @subsection Compiled-Function Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1210
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1211 The byte compiler produces @dfn{compiled-function objects}. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1212 evaluator handles this data type specially when it appears as a function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1213 to be called. @xref{Byte Compilation}, for information about the byte
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1214 compiler.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1215
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1216 The printed representation for a compiled-function object is normally
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1217 @samp{#<compiled-function...>}. If @code{print-readably} is true,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1218 however, it is @samp{#[...]}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1219
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1220 @node Autoload Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1221 @subsection Autoload Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1222
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1223 An @dfn{autoload object} is a list whose first element is the symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1224 @code{autoload}. It is stored as the function definition of a symbol as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1225 a placeholder for the real definition; it says that the real definition
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1226 is found in a file of Lisp code that should be loaded when necessary.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1227 The autoload object contains the name of the file, plus some other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1228 information about the real definition.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1229
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1230 After the file has been loaded, the symbol should have a new function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1231 definition that is not an autoload object. The new definition is then
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1232 called as if it had been there to begin with. From the user's point of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1233 view, the function call works as expected, using the function definition
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1234 in the loaded file.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1235
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1236 An autoload object is usually created with the function
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1237 @code{autoload}, which stores the object in the function cell of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1238 symbol. @xref{Autoload}, for more details.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1239
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1240 @node Char Table Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1241 @subsection Char Table Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1242 @cindex char table type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1243
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1244 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1245
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1246 @node Hash Table Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1247 @subsection Hash Table Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1248 @cindex hash table type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1249
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1250 A @dfn{hash table} is a table providing an arbitrary mapping from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1251 one Lisp object to another, using an internal indexing method
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1252 called @dfn{hashing}. Hash tables are very fast (much more efficient
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1253 that using an association list, when there are a large number of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1254 elements in the table).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1255
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1256 Hash tables have a special read syntax beginning with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1257 @samp{#s(hash-table} (this is an example of @dfn{structure} read
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1258 syntax. This notation is also used for printing when
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1259 @code{print-readably} is @code{t}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1260
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1261 Otherwise they print in hash notation (The ``hash'' in ``hash notation''
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1262 has nothing to do with the ``hash'' in ``hash table''), giving the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1263 number of elements, total space allocated for elements, and a unique
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1264 number assigned at the time the hash table was created. (Hash tables
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1265 automatically resize as necessary so there is no danger of running out
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1266 of space for elements.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1267
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1268 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1269 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1270 (make-hash-table :size 50)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1271 @result{} #<hash-table 0/107 0x313a>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1272 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1273 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1274
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1275 @xref{Hash Tables}, for information on how to create and work with hash
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1276 tables.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1277
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1278 @node Range Table Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1279 @subsection Range Table Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1280 @cindex range table type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1281
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1282 A @dfn{range table} is a table that maps from ranges of integers to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1283 arbitrary Lisp objects. Range tables automatically combine overlapping
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1284 ranges that map to the same Lisp object, and operations are provided
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1285 for mapping over all of the ranges in a range table.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1286
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1287 Range tables have a special read syntax beginning with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1288 @samp{#s(range-table} (this is an example of @dfn{structure} read syntax,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1289 which is also used for char tables and faces).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1290
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1291 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1292 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1293 (setq x (make-range-table))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1294 (put-range-table 20 50 'foo x)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1295 (put-range-table 100 200 "bar" x)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1296 x
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1297 @result{} #s(range-table data ((20 50) foo (100 200) "bar"))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1298 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1299 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1300
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1301 @xref{Range Tables}, for information on how to create and work with range
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1302 tables.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1303
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1304 @node Weak List Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1305 @subsection Weak List Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1306 @cindex weak list type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1307
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1308 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1309
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1310 @node Editing Types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1311 @section Editing Types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1312 @cindex editing types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1313
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1314 The types in the previous section are common to many Lisp dialects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1315 XEmacs Lisp provides several additional data types for purposes connected
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1316 with editing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1317
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1318 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1319 * Buffer Type:: The basic object of editing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1320 * Marker Type:: A position in a buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1321 * Extent Type:: A range in a buffer or string, maybe with properties.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1322 * Window Type:: Buffers are displayed in windows.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1323 * Frame Type:: Windows subdivide frames.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1324 * Device Type:: Devices group all frames on a display.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1325 * Console Type:: Consoles group all devices with the same keyboard.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1326 * Window Configuration Type:: Recording the way a frame is subdivided.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1327 * Event Type:: An interesting occurrence in the system.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1328 * Process Type:: A process running on the underlying OS.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1329 * Stream Type:: Receive or send characters.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1330 * Keymap Type:: What function a keystroke invokes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1331 * Syntax Table Type:: What a character means.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1332 * Display Table Type:: How display tables are represented.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1333 * Database Type:: A connection to an external DBM or DB database.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1334 * Charset Type:: A character set (e.g. all Kanji characters),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1335 under XEmacs/MULE.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1336 * Coding System Type:: An object encapsulating a way of converting between
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1337 different textual encodings, under XEmacs/MULE.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1338 * ToolTalk Message Type:: A message, in the ToolTalk IPC protocol.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1339 * ToolTalk Pattern Type:: A pattern, in the ToolTalk IPC protocol.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1340 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1341
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1342 @node Buffer Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1343 @subsection Buffer Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1344
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1345 A @dfn{buffer} is an object that holds text that can be edited
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1346 (@pxref{Buffers}). Most buffers hold the contents of a disk file
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1347 (@pxref{Files}) so they can be edited, but some are used for other
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1348 purposes. Most buffers are also meant to be seen by the user, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1349 therefore displayed, at some time, in a window (@pxref{Windows}). But a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1350 buffer need not be displayed in any window.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1351
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1352 The contents of a buffer are much like a string, but buffers are not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1353 used like strings in XEmacs Lisp, and the available operations are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1354 different. For example, insertion of text into a buffer is very
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1355 efficient, whereas ``inserting'' text into a string requires
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1356 concatenating substrings, and the result is an entirely new string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1357 object.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1358
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1359 Each buffer has a designated position called @dfn{point}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1360 (@pxref{Positions}). At any time, one buffer is the @dfn{current
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1361 buffer}. Most editing commands act on the contents of the current
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1362 buffer in the neighborhood of point. Many of the standard Emacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1363 functions manipulate or test the characters in the current buffer; a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1364 whole chapter in this manual is devoted to describing these functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1365 (@pxref{Text}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1366
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1367 Several other data structures are associated with each buffer:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1368
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1369 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1370 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1371 a local syntax table (@pxref{Syntax Tables});
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1372
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1373 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1374 a local keymap (@pxref{Keymaps});
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1375
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1376 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1377 a local variable binding list (@pxref{Buffer-Local Variables});
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1378
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1379 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1380 a list of extents (@pxref{Extents});
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1381
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1382 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1383 and various other related properties.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1384 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1385
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1386 @noindent
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1387 The local keymap and variable list contain entries that individually
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1388 override global bindings or values. These are used to customize the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1389 behavior of programs in different buffers, without actually changing the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1390 programs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1391
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1392 A buffer may be @dfn{indirect}, which means it shares the text
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1393 of another buffer. @xref{Indirect Buffers}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1394
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1395 Buffers have no read syntax. They print in hash notation, showing the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1396 buffer name.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1397
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1398 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1399 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1400 (current-buffer)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1401 @result{} #<buffer "objects.texi">
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1402 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1403 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1404
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1405 @node Marker Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1406 @subsection Marker Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1407
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1408 A @dfn{marker} denotes a position in a specific buffer. Markers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1409 therefore have two components: one for the buffer, and one for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1410 position. Changes in the buffer's text automatically relocate the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1411 position value as necessary to ensure that the marker always points
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1412 between the same two characters in the buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1413
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1414 Markers have no read syntax. They print in hash notation, giving the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1415 current character position and the name of the buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1416
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1417 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1418 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1419 (point-marker)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1420 @result{} #<marker at 50661 in objects.texi>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1421 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1422 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1423
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1424 @xref{Markers}, for information on how to test, create, copy, and move
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1425 markers.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1426
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1427 @node Extent Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1428 @subsection Extent Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1429
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1430 An @dfn{extent} specifies temporary alteration of the display
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1431 appearance of a part of a buffer (or string). It contains markers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1432 delimiting a range of the buffer, plus a property list (a list whose
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1433 elements are alternating property names and values). Extents are used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1434 to present parts of the buffer temporarily in a different display style.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1435 They have no read syntax, and print in hash notation, giving the buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1436 name and range of positions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1437
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1438 Extents can exist over strings as well as buffers; the primary use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1439 of this is to preserve extent and text property information as text
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1440 is copied from one buffer to another or between different parts of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1441 a buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1442
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1443 Extents have no read syntax. They print in hash notation, giving the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1444 range of text they cover, the name of the buffer or string they are in,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1445 the address in core, and a summary of some of the properties attached to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1446 the extent.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1447
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1448 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1449 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1450 (extent-at (point))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1451 @result{} #<extent [51742, 51748) font-lock text-prop 0x90121e0 in buffer objects.texi>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1452 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1453 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1454
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1455 @xref{Extents}, for how to create and use extents.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1456
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1457 Extents are used to implement text properties. @xref{Text Properties}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1458
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1459 @node Window Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1460 @subsection Window Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1461
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1462 A @dfn{window} describes the portion of the frame that XEmacs uses to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1463 display a buffer. (In standard window-system usage, a @dfn{window} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1464 what XEmacs calls a @dfn{frame}; XEmacs confusingly uses the term
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1465 ``window'' to refer to what is called a @dfn{pane} in standard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1466 window-system usage.) Every window has one associated buffer, whose
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1467 contents appear in the window. By contrast, a given buffer may appear
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1468 in one window, no window, or several windows.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1469
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1470 Though many windows may exist simultaneously, at any time one window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1471 is designated the @dfn{selected window}. This is the window where the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1472 cursor is (usually) displayed when XEmacs is ready for a command. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1473 selected window usually displays the current buffer, but this is not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1474 necessarily the case.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1475
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1476 Windows are grouped on the screen into frames; each window belongs to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1477 one and only one frame. @xref{Frame Type}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1478
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1479 Windows have no read syntax. They print in hash notation, giving the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1480 name of the buffer being displayed and a unique number assigned at the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1481 time the window was created. (This number can be useful because the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1482 buffer displayed in any given window can change frequently.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1483
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1484 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1485 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1486 (selected-window)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1487 @result{} #<window on "objects.texi" 0x266c>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1488 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1489 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1490
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1491 @xref{Windows}, for a description of the functions that work on windows.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1492
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1493 @node Frame Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1494 @subsection Frame Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1495
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1496 A @var{frame} is a rectangle on the screen (a @dfn{window} in standard
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1497 window-system terminology) that contains one or more non-overlapping
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1498 Emacs windows (@dfn{panes} in standard window-system terminology). A
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1499 frame initially contains a single main window (plus perhaps a minibuffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1500 window) which you can subdivide vertically or horizontally into smaller
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1501 windows.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1502
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1503 Frames have no read syntax. They print in hash notation, giving the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1504 frame's type, name as used for resourcing, and a unique number assigned
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1505 at the time the frame was created.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1506
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1507 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1508 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1509 (selected-frame)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1510 @result{} #<x-frame "emacs" 0x9db>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1511 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1512 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1513
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1514 @xref{Frames}, for a description of the functions that work on frames.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1515
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1516 @node Device Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1517 @subsection Device Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1518
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1519 A @dfn{device} represents a single display on which frames exist.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1520 Normally, there is only one device object, but there may be more
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1521 than one if XEmacs is being run on a multi-headed display (e.g. an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1522 X server with attached color and mono screens) or if XEmacs is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1523 simultaneously driving frames attached to different consoles, e.g.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1524 an X display and a @sc{tty} connection.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1525
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1526 Devices do not have a read syntax. They print in hash notation,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1527 giving the device's type, connection name, and a unique number assigned
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1528 at the time the device was created.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1529
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1530 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1531 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1532 (selected-device)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1533 @result{} #<x-device on ":0.0" 0x5b9>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1534 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1535 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1536
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1537 @xref{Consoles and Devices}, for a description of several functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1538 related to devices.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1539
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1540 @node Console Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1541 @subsection Console Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1542
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1543 A @dfn{console} represents a single keyboard to which devices
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1544 (i.e. displays on which frames exist) are connected. Normally, there is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1545 only one console object, but there may be more than one if XEmacs is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1546 simultaneously driving frames attached to different X servers and/or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1547 @sc{tty} connections. (XEmacs is capable of driving multiple X and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1548 @sc{tty} connections at the same time, and provides a robust mechanism
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1549 for handling the differing display capabilities of such heterogeneous
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1550 environments. A buffer with embedded glyphs and multiple fonts and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1551 colors, for example, will display reasonably if it simultaneously
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1552 appears on a frame on a color X display, a frame on a mono X display,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1553 and a frame on a @sc{tty} connection.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1554
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1555 Consoles do not have a read syntax. They print in hash notation,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1556 giving the console's type, connection name, and a unique number assigned
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1557 at the time the console was created.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1558
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1559 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1560 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1561 (selected-console)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1562 @result{} #<x-console on "localhost:0" 0x5b7>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1563 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1564 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1565
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1566 @xref{Consoles and Devices}, for a description of several functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1567 related to consoles.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1568
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1569 @node Window Configuration Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1570 @subsection Window Configuration Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1571 @cindex screen layout
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1572
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1573 A @dfn{window configuration} stores information about the positions,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1574 sizes, and contents of the windows in a frame, so you can recreate the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1575 same arrangement of windows later.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1576
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1577 Window configurations do not have a read syntax. They print in hash
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1578 notation, giving a unique number assigned at the time the window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1579 configuration was created.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1580
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1581 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1582 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1583 (current-window-configuration)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1584 @result{} #<window-configuration 0x2db4>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1585 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1586 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1587
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1588 @xref{Window Configurations}, for a description of several functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1589 related to window configurations.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1590
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1591 @node Event Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1592 @subsection Event Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1593
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1594 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1595
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1596 @node Process Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1597 @subsection Process Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1598
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1599 The word @dfn{process} usually means a running program. XEmacs itself
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1600 runs in a process of this sort. However, in XEmacs Lisp, a process is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1601 Lisp object that designates a subprocess created by the XEmacs process.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1602 Programs such as shells, GDB, ftp, and compilers, running in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1603 subprocesses of XEmacs, extend the capabilities of XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1604
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1605 An Emacs subprocess takes textual input from Emacs and returns textual
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1606 output to Emacs for further manipulation. Emacs can also send signals
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1607 to the subprocess.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1608
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1609 Process objects have no read syntax. They print in hash notation,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1610 giving the name of the process, its associated process ID, and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1611 current state of the process:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1612
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1613 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1614 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1615 (process-list)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1616 @result{} (#<process "shell" pid 2909 state:run>)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1617 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1618 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1619
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1620 @xref{Processes}, for information about functions that create, delete,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1621 return information about, send input or signals to, and receive output
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1622 from processes.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1623
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1624 @node Stream Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1625 @subsection Stream Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1626
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1627 A @dfn{stream} is an object that can be used as a source or sink for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1628 characters---either to supply characters for input or to accept them as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1629 output. Many different types can be used this way: markers, buffers,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1630 strings, and functions. Most often, input streams (character sources)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1631 obtain characters from the keyboard, a buffer, or a file, and output
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1632 streams (character sinks) send characters to a buffer, such as a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1633 @file{*Help*} buffer, or to the echo area.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1634
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1635 The object @code{nil}, in addition to its other meanings, may be used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1636 as a stream. It stands for the value of the variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1637 @code{standard-input} or @code{standard-output}. Also, the object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1638 @code{t} as a stream specifies input using the minibuffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1639 (@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1640 Area}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1641
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1642 Streams have no special printed representation or read syntax, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1643 print as whatever primitive type they are.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1644
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1645 @xref{Read and Print}, for a description of functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1646 related to streams, including parsing and printing functions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1647
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1648 @node Keymap Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1649 @subsection Keymap Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1650
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1651 A @dfn{keymap} maps keys typed by the user to commands. This mapping
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1652 controls how the user's command input is executed.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1653
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1654 NOTE: In XEmacs, a keymap is a separate primitive type. In FSF GNU
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1655 Emacs, a keymap is actually a list whose @sc{car} is the symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1656 @code{keymap}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1657
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1658 @xref{Keymaps}, for information about creating keymaps, handling prefix
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1659 keys, local as well as global keymaps, and changing key bindings.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1660
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1661 @node Syntax Table Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1662 @subsection Syntax Table Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1663
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1664 Under XEmacs 20, a @dfn{syntax table} is a particular type of char
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1665 table. Under XEmacs 19, a syntax table a vector of 256 integers. In
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1666 both cases, each element defines how one character is interpreted when it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1667 appears in a buffer. For example, in C mode (@pxref{Major Modes}), the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1668 @samp{+} character is punctuation, but in Lisp mode it is a valid
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1669 character in a symbol. These modes specify different interpretations by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1670 changing the syntax table entry for @samp{+}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1671
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1672 Syntax tables are used only for scanning text in buffers, not for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1673 reading Lisp expressions. The table the Lisp interpreter uses to read
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1674 expressions is built into the XEmacs source code and cannot be changed;
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1675 thus, to change the list delimiters to be @samp{@{} and @samp{@}}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1676 instead of @samp{(} and @samp{)} would be impossible.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1677
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1678 @xref{Syntax Tables}, for details about syntax classes and how to make
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1679 and modify syntax tables.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1680
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1681 @node Display Table Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1682 @subsection Display Table Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1683
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1684 A @dfn{display table} specifies how to display each character code.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1685 Each buffer and each window can have its own display table. A display
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1686 table is actually a vector of length 256, although in XEmacs 20 this may
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1687 change to be a particular type of char table. @xref{Display Tables}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1688
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1689 @node Database Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1690 @subsection Database Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1691 @cindex database type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1692
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1693 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1694
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1695 @node Charset Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1696 @subsection Charset Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1697 @cindex charset type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1698
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1699 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1700
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1701 @node Coding System Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1702 @subsection Coding System Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1703 @cindex coding system type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1704
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1705 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1706
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1707 @node ToolTalk Message Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1708 @subsection ToolTalk Message Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1709
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1710 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1711
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1712 @node ToolTalk Pattern Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1713 @subsection ToolTalk Pattern Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1714
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1715 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1716
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1717 @node Window-System Types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1718 @section Window-System Types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1719 @cindex window system types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1720
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1721 XEmacs also has some types that represent objects such as faces
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1722 (collections of display characters), fonts, and pixmaps that are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1723 commonly found in windowing systems.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1724
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1725 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1726 * Face Type:: A collection of display characteristics.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1727 * Glyph Type:: An image appearing in a buffer or elsewhere.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1728 * Specifier Type:: A way of controlling display characteristics on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1729 a per-buffer, -frame, -window, or -device level.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1730 * Font Instance Type:: The way a font appears on a particular device.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1731 * Color Instance Type:: The way a color appears on a particular device.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1732 * Image Instance Type:: The way an image appears on a particular device.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1733 * Toolbar Button Type:: An object representing a button in a toolbar.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1734 * Subwindow Type:: An externally-controlled window-system window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1735 appearing in a buffer.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1736 * X Resource Type:: A miscellaneous X resource, if Epoch support was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1737 compiled into XEmacs.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1738 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1739
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1740 @node Face Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1741 @subsection Face Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1742 @cindex face type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1743
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1744 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1745
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1746 @node Glyph Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1747 @subsection Glyph Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1748 @cindex glyph type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1749
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1750 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1751
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1752 @node Specifier Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1753 @subsection Specifier Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1754 @cindex specifier type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1755
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1756 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1757
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1758 @node Font Instance Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1759 @subsection Font Instance Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1760 @cindex font instance type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1761
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1762 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1763
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1764 @node Color Instance Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1765 @subsection Color Instance Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1766 @cindex color instance type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1767
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1768 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1769
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1770 @node Image Instance Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1771 @subsection Image Instance Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1772 @cindex image instance type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1773
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1774 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1775
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1776 @node Toolbar Button Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1777 @subsection Toolbar Button Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1778 @cindex toolbar button type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1779
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1780 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1781
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1782 @node Subwindow Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1783 @subsection Subwindow Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1784 @cindex subwindow type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1785
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1786 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1787
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1788 @node X Resource Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1789 @subsection X Resource Type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1790 @cindex X resource type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1791
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1792 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1793
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1794 @node Type Predicates
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1795 @section Type Predicates
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1796 @cindex predicates
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1797 @cindex type checking
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1798 @kindex wrong-type-argument
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1799
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1800 The XEmacs Lisp interpreter itself does not perform type checking on
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1801 the actual arguments passed to functions when they are called. It could
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1802 not do so, since function arguments in Lisp do not have declared data
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1803 types, as they do in other programming languages. It is therefore up to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1804 the individual function to test whether each actual argument belongs to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1805 a type that the function can use.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1806
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1807 All built-in functions do check the types of their actual arguments
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1808 when appropriate, and signal a @code{wrong-type-argument} error if an
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1809 argument is of the wrong type. For example, here is what happens if you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1810 pass an argument to @code{+} that it cannot handle:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1811
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1812 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1813 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1814 (+ 2 'a)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1815 @error{} Wrong type argument: integer-or-marker-p, a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1816 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1817 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1818
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1819 @cindex type predicates
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1820 @cindex testing types
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1821 If you want your program to handle different types differently, you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1822 must do explicit type checking. The most common way to check the type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1823 of an object is to call a @dfn{type predicate} function. Emacs has a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1824 type predicate for each type, as well as some predicates for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1825 combinations of types.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1826
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1827 A type predicate function takes one argument; it returns @code{t} if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1828 the argument belongs to the appropriate type, and @code{nil} otherwise.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1829 Following a general Lisp convention for predicate functions, most type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1830 predicates' names end with @samp{p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1831
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1832 Here is an example which uses the predicates @code{listp} to check for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1833 a list and @code{symbolp} to check for a symbol.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1834
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1835 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1836 (defun add-on (x)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1837 (cond ((symbolp x)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1838 ;; If X is a symbol, put it on LIST.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1839 (setq list (cons x list)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1840 ((listp x)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1841 ;; If X is a list, add its elements to LIST.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1842 (setq list (append x list)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1843 @need 3000
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1844 (t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1845 ;; We only handle symbols and lists.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1846 (error "Invalid argument %s in add-on" x))))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1847 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1848
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1849 Here is a table of predefined type predicates, in alphabetical order,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1850 with references to further information.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1851
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1852 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1853 @item annotationp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1854 @xref{Annotation Primitives, annotationp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1855
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1856 @item arrayp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1857 @xref{Array Functions, arrayp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1858
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1859 @item atom
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1860 @xref{List-related Predicates, atom}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1861
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1862 @item bit-vector-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1863 @xref{Bit Vector Functions, bit-vector-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1864
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1865 @item bitp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1866 @xref{Bit Vector Functions, bitp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1867
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1868 @item boolean-specifier-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1869 @xref{Specifier Types, boolean-specifier-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1870
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1871 @item buffer-glyph-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1872 @xref{Glyph Types, buffer-glyph-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1873
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1874 @item buffer-live-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1875 @xref{Killing Buffers, buffer-live-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1876
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1877 @item bufferp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1878 @xref{Buffer Basics, bufferp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1879
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1880 @item button-event-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1881 @xref{Event Predicates, button-event-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1882
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1883 @item button-press-event-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1884 @xref{Event Predicates, button-press-event-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1885
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1886 @item button-release-event-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1887 @xref{Event Predicates, button-release-event-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1888
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1889 @item case-table-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1890 @xref{Case Tables, case-table-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1891
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1892 @item char-int-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1893 @xref{Character Codes, char-int-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1894
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1895 @item char-or-char-int-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1896 @xref{Character Codes, char-or-char-int-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1897
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1898 @item char-or-string-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1899 @xref{Predicates for Strings, char-or-string-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1900
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1901 @item char-table-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1902 @xref{Char Tables, char-table-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1903
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1904 @item characterp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1905 @xref{Predicates for Characters, characterp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1906
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1907 @item color-instance-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1908 @xref{Colors, color-instance-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1909
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1910 @item color-pixmap-image-instance-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1911 @xref{Image Instance Types, color-pixmap-image-instance-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1912
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1913 @item color-specifier-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1914 @xref{Specifier Types, color-specifier-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1915
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1916 @item commandp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1917 @xref{Interactive Call, commandp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1918
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1919 @item compiled-function-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1920 @xref{Compiled-Function Type, compiled-function-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1921
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1922 @item console-live-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1923 @xref{Connecting to a Console or Device, console-live-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1924
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1925 @item consolep
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1926 @xref{Consoles and Devices, consolep}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1927
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1928 @item consp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1929 @xref{List-related Predicates, consp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1930
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1931 @item database-live-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1932 @xref{Connecting to a Database, database-live-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1933
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1934 @item databasep
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1935 @xref{Databases, databasep}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1936
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1937 @item device-live-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1938 @xref{Connecting to a Console or Device, device-live-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1939
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1940 @item device-or-frame-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1941 @xref{Basic Device Functions, device-or-frame-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1942
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1943 @item devicep
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1944 @xref{Consoles and Devices, devicep}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1945
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1946 @item eval-event-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1947 @xref{Event Predicates, eval-event-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1948
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1949 @item event-live-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1950 @xref{Event Predicates, event-live-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1951
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1952 @item eventp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1953 @xref{Events, eventp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1954
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1955 @item extent-live-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1956 @xref{Creating and Modifying Extents, extent-live-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1957
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1958 @item extentp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1959 @xref{Extents, extentp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1960
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1961 @item face-boolean-specifier-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1962 @xref{Specifier Types, face-boolean-specifier-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1963
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1964 @item facep
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1965 @xref{Basic Face Functions, facep}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1966
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1967 @item floatp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1968 @xref{Predicates on Numbers, floatp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1969
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1970 @item font-instance-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1971 @xref{Fonts, font-instance-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1972
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1973 @item font-specifier-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1974 @xref{Specifier Types, font-specifier-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1975
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1976 @item frame-live-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1977 @xref{Deleting Frames, frame-live-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1978
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1979 @item framep
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1980 @xref{Frames, framep}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1981
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1982 @item functionp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1983 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1984
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1985 @item generic-specifier-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1986 @xref{Specifier Types, generic-specifier-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1987
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1988 @item glyphp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1989 @xref{Glyphs, glyphp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1990
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1991 @item hash-table-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1992 @xref{Hash Tables, hash-table-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1993
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1994 @item icon-glyph-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1995 @xref{Glyph Types, icon-glyph-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1996
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1997 @item image-instance-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1998 @xref{Images, image-instance-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1999
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2000 @item image-specifier-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2001 @xref{Specifier Types, image-specifier-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2002
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2003 @item integer-char-or-marker-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2004 @xref{Predicates on Markers, integer-char-or-marker-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2005
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2006 @item integer-or-char-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2007 @xref{Predicates for Characters, integer-or-char-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2008
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2009 @item integer-or-marker-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2010 @xref{Predicates on Markers, integer-or-marker-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2011
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2012 @item integer-specifier-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2013 @xref{Specifier Types, integer-specifier-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2014
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2015 @item integerp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2016 @xref{Predicates on Numbers, integerp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2017
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2018 @item itimerp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2019 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2020
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2021 @item key-press-event-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2022 @xref{Event Predicates, key-press-event-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2023
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2024 @item keymapp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2025 @xref{Creating Keymaps, keymapp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2026
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2027 @item keywordp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2028 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2029
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2030 @item listp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2031 @xref{List-related Predicates, listp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2032
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2033 @item markerp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2034 @xref{Predicates on Markers, markerp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2035
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2036 @item misc-user-event-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2037 @xref{Event Predicates, misc-user-event-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2038
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2039 @item mono-pixmap-image-instance-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2040 @xref{Image Instance Types, mono-pixmap-image-instance-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2041
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2042 @item motion-event-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2043 @xref{Event Predicates, motion-event-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2044
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2045 @item mouse-event-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2046 @xref{Event Predicates, mouse-event-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2047
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2048 @item natnum-specifier-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2049 @xref{Specifier Types, natnum-specifier-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2050
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2051 @item natnump
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2052 @xref{Predicates on Numbers, natnump}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2053
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2054 @item nlistp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2055 @xref{List-related Predicates, nlistp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2056
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2057 @item nothing-image-instance-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2058 @xref{Image Instance Types, nothing-image-instance-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2059
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2060 @item number-char-or-marker-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2061 @xref{Predicates on Markers, number-char-or-marker-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2062
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2063 @item number-or-marker-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2064 @xref{Predicates on Markers, number-or-marker-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2065
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2066 @item numberp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2067 @xref{Predicates on Numbers, numberp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2068
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2069 @item pointer-glyph-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2070 @xref{Glyph Types, pointer-glyph-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2071
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2072 @item pointer-image-instance-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2073 @xref{Image Instance Types, pointer-image-instance-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2074
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2075 @item process-event-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2076 @xref{Event Predicates, process-event-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2077
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2078 @item processp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2079 @xref{Processes, processp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2080
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2081 @item range-table-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2082 @xref{Range Tables, range-table-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2083
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2084 @item ringp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2085 (not yet documented)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2086
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2087 @item sequencep
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2088 @xref{Sequence Functions, sequencep}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2089
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2090 @item specifierp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2091 @xref{Specifiers, specifierp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2092
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2093 @item stringp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2094 @xref{Predicates for Strings, stringp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2095
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2096 @item subrp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2097 @xref{Function Cells, subrp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2098
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2099 @item subwindow-image-instance-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2100 @xref{Image Instance Types, subwindow-image-instance-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2101
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2102 @item subwindowp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2103 @xref{Subwindows, subwindowp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2104
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2105 @item symbolp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2106 @xref{Symbols, symbolp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2107
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2108 @item syntax-table-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2109 @xref{Syntax Tables, syntax-table-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2110
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2111 @item text-image-instance-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2112 @xref{Image Instance Types, text-image-instance-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2113
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2114 @item timeout-event-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2115 @xref{Event Predicates, timeout-event-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2116
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2117 @item toolbar-button-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2118 @xref{Toolbar, toolbar-button-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2119
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2120 @item toolbar-specifier-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2121 @xref{Toolbar, toolbar-specifier-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2122
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2123 @item user-variable-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2124 @xref{Defining Variables, user-variable-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2125
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2126 @item vectorp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2127 @xref{Vectors, vectorp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2128
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2129 @item weak-list-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2130 @xref{Weak Lists, weak-list-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2131
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2132 @ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2133 @item wholenump
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2134 @xref{Predicates on Numbers, wholenump}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2135 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2136
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2137 @item window-configuration-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2138 @xref{Window Configurations, window-configuration-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2139
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2140 @item window-live-p
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2141 @xref{Deleting Windows, window-live-p}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2142
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2143 @item windowp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2144 @xref{Basic Windows, windowp}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2145 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2146
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2147 The most general way to check the type of an object is to call the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2148 function @code{type-of}. Recall that each object belongs to one and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2149 only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2150 Data Types}). But @code{type-of} knows nothing about non-primitive
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2151 types. In most cases, it is more convenient to use type predicates than
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2152 @code{type-of}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2153
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2154 @defun type-of object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2155 This function returns a symbol naming the primitive type of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2156 @var{object}. The value is one of @code{bit-vector}, @code{buffer},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2157 @code{char-table}, @code{character}, @code{charset},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2158 @code{coding-system}, @code{cons}, @code{color-instance},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2159 @code{compiled-function}, @code{console}, @code{database},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2160 @code{device}, @code{event}, @code{extent}, @code{face}, @code{float},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2161 @code{font-instance}, @code{frame}, @code{glyph}, @code{hash-table},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2162 @code{image-instance}, @code{integer}, @code{keymap}, @code{marker},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2163 @code{process}, @code{range-table}, @code{specifier}, @code{string},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2164 @code{subr}, @code{subwindow}, @code{symbol}, @code{toolbar-button},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2165 @code{tooltalk-message}, @code{tooltalk-pattern}, @code{vector},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2166 @code{weak-list}, @code{window}, @code{window-configuration}, or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2167 @code{x-resource}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2168
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2169 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2170 (type-of 1)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2171 @result{} integer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2172 (type-of 'nil)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2173 @result{} symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2174 (type-of '()) ; @r{@code{()} is @code{nil}.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2175 @result{} symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2176 (type-of '(x))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2177 @result{} cons
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2178 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2179 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2180
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2181 @node Equality Predicates
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2182 @section Equality Predicates
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2183 @cindex equality
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2184
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2185 Here we describe two functions that test for equality between any two
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2186 objects. Other functions test equality between objects of specific
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2187 types, e.g., strings. For these predicates, see the appropriate chapter
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2188 describing the data type.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2189
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2190 @defun eq object1 object2
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2191 This function returns @code{t} if @var{object1} and @var{object2} are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2192 the same object, @code{nil} otherwise. The ``same object'' means that a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2193 change in one will be reflected by the same change in the other.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2194
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2195 @code{eq} returns @code{t} if @var{object1} and @var{object2} are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2196 integers with the same value. Also, since symbol names are normally
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2197 unique, if the arguments are symbols with the same name, they are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2198 @code{eq}. For other types (e.g., lists, vectors, strings), two
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2199 arguments with the same contents or elements are not necessarily
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2200 @code{eq} to each other: they are @code{eq} only if they are the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2201 object.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2202
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2203 (The @code{make-symbol} function returns an uninterned symbol that is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2204 not interned in the standard @code{obarray}. When uninterned symbols
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2205 are in use, symbol names are no longer unique. Distinct symbols with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2206 the same name are not @code{eq}. @xref{Creating Symbols}.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2207
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2208 NOTE: Under XEmacs 19, characters are really just integers, and thus
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2209 characters and integers are @code{eq}. Under XEmacs 20, it was
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2210 necessary to preserve remnants of this in function such as @code{old-eq}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2211 in order to maintain byte-code compatibility. Byte code compiled
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2212 under any Emacs 19 will automatically have calls to @code{eq} mapped
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2213 to @code{old-eq} when executed under XEmacs 20.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2214
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2215 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2216 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2217 (eq 'foo 'foo)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2218 @result{} t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2219 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2220
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2221 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2222 (eq 456 456)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2223 @result{} t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2224 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2225
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2226 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2227 (eq "asdf" "asdf")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2228 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2229 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2230
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2231 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2232 (eq '(1 (2 (3))) '(1 (2 (3))))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2233 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2234 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2235
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2236 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2237 (setq foo '(1 (2 (3))))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2238 @result{} (1 (2 (3)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2239 (eq foo foo)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2240 @result{} t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2241 (eq foo '(1 (2 (3))))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2242 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2243 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2244
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2245 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2246 (eq [(1 2) 3] [(1 2) 3])
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2247 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2248 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2249
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2250 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2251 (eq (point-marker) (point-marker))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2252 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2253 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2254 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2255
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2256 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2257
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 440
diff changeset
2258 @defun old-eq object1 object2
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2259 This function exists under XEmacs 20 and is exactly like @code{eq}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2260 except that it suffers from the char-int confoundance disease.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2261 In other words, it returns @code{t} if given a character and the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2262 equivalent integer, even though the objects are of different types!
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2263 You should @emph{not} ever call this function explicitly in your
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2264 code. However, be aware that all calls to @code{eq} in byte code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2265 compiled under version 19 map to @code{old-eq} in XEmacs 20.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2266 (Likewise for @code{old-equal}, @code{old-memq}, @code{old-member},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2267 @code{old-assq} and @code{old-assoc}.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2268
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2269 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2270 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2271 ;; @r{Remember, this does not apply under XEmacs 19.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2272 ?A
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2273 @result{} ?A
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2274 (char-int ?A)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2275 @result{} 65
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2276 (old-eq ?A 65)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2277 @result{} t ; @r{Eek, we've been infected.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2278 (eq ?A 65)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2279 @result{} nil ; @r{We are still healthy.}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2280 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2281 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2282 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2283
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2284 @defun equal object1 object2
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2285 This function returns @code{t} if @var{object1} and @var{object2} have
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2286 equal components, @code{nil} otherwise. Whereas @code{eq} tests if its
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2287 arguments are the same object, @code{equal} looks inside nonidentical
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2288 arguments to see if their elements are the same. So, if two objects are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2289 @code{eq}, they are @code{equal}, but the converse is not always true.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2290
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2291 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2292 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2293 (equal 'foo 'foo)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2294 @result{} t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2295 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2296
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2297 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2298 (equal 456 456)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2299 @result{} t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2300 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2301
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2302 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2303 (equal "asdf" "asdf")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2304 @result{} t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2305 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2306 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2307 (eq "asdf" "asdf")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2308 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2309 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2310
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2311 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2312 (equal '(1 (2 (3))) '(1 (2 (3))))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2313 @result{} t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2314 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2315 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2316 (eq '(1 (2 (3))) '(1 (2 (3))))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2317 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2318 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2319
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2320 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2321 (equal [(1 2) 3] [(1 2) 3])
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2322 @result{} t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2323 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2324 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2325 (eq [(1 2) 3] [(1 2) 3])
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2326 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2327 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2328
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2329 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2330 (equal (point-marker) (point-marker))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2331 @result{} t
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2332 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2333
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2334 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2335 (eq (point-marker) (point-marker))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2336 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2337 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2338 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2339
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2340 Comparison of strings is case-sensitive.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2341
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2342 Note that in FSF GNU Emacs, comparison of strings takes into account
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2343 their text properties, and you have to use @code{string-equal} if you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2344 want only the strings themselves compared. This difference does not
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2345 exist in XEmacs; @code{equal} and @code{string-equal} always return
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2346 the same value on the same strings.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2347
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2348 @ignore @c Not true in XEmacs
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2349 Comparison of strings is case-sensitive and takes account of text
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2350 properties as well as the characters in the strings. To compare
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2351 two strings' characters without comparing their text properties,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2352 use @code{string=} (@pxref{Text Comparison}).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2353 @end ignore
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2354
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2355 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2356 @group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2357 (equal "asdf" "ASDF")
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2358 @result{} nil
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2359 @end group
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2360 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2361
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2362 Two distinct buffers are never @code{equal}, even if their contents
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2363 are the same.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2364 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2365
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2366 The test for equality is implemented recursively, and circular lists may
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2367 therefore cause infinite recursion (leading to an error).