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