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