1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Character Type, Next: Symbol Type, Prev: Floating Point Type, Up: Programming Types
58 In XEmacs version 19, and in all versions of FSF GNU Emacs, a
59 "character" in XEmacs Lisp is nothing more than an integer. This is
60 yet another holdover from XEmacs Lisp's derivation from vintage-1980
61 Lisps; modern versions of Lisp consider this equivalence a bad idea,
62 and have separate character types. In XEmacs version 20, the modern
63 convention is followed, and characters are their own primitive types.
64 (This change was necessary in order for MULE, i.e. Asian-language,
65 support to be correctly implemented.)
67 Even in XEmacs version 20, remnants of the equivalence between
68 characters and integers still exist; this is termed the "char-int
69 confoundance disease". In particular, many functions such as `eq',
70 `equal', and `memq' have equivalent functions (`old-eq', `old-equal',
71 `old-memq', etc.) that pretend like characters are integers are the
72 same. Byte code compiled under any version 19 Emacs will have all such
73 functions mapped to their `old-' equivalents when the byte code is read
74 into XEmacs 20. This is to preserve compatibility--Emacs 19 converts
75 all constant characters to the equivalent integer during
76 byte-compilation, and thus there is no other way to preserve byte-code
77 compatibility even if the code has specifically been written with the
78 distinction between characters and integers in mind.
80 Every character has an equivalent integer, called the "character
81 code". For example, the character `A' is represented as the
82 integer 65, following the standard ASCII representation of characters.
83 If XEmacs was not compiled with MULE support, the range of this integer
84 will always be 0 to 255--eight bits, or one byte. (Integers outside
85 this range are accepted but silently truncated; however, you should
86 most decidedly _not_ rely on this, because it will not work under
87 XEmacs with MULE support.) When MULE support is present, the range of
88 character codes is much larger. (Currently, 19 bits are used.)
90 FSF GNU Emacs uses kludgy character codes above 255 to represent
91 keyboard input of ASCII characters in combination with certain
92 modifiers. XEmacs does not use this (a more general mechanism is used
93 that does not distinguish between ASCII keys and other keys), so you
94 will never find character codes above 255 in a non-MULE XEmacs.
96 Individual characters are not often used in programs. It is far more
97 common to work with _strings_, which are sequences composed of
98 characters. *Note String Type::.
100 The read syntax for characters begins with a question mark, followed
101 by the character (if it's printable) or some symbolic representation of
102 it. In XEmacs 20, where characters are their own type, this is also the
103 print representation. In XEmacs 19, however, where characters are
104 really integers, the printed representation of a character is a decimal
105 number. This is also a possible read syntax for a character, but
106 writing characters that way in Lisp programs is a very bad idea. You
107 should _always_ use the special read syntax formats that XEmacs Lisp
108 provides for characters.
110 The usual read syntax for alphanumeric characters is a question mark
111 followed by the character; thus, `?A' for the character `A', `?B' for
112 the character `B', and `?a' for the character `a'.
122 You can use the same syntax for punctuation characters, but it is
123 often a good idea to add a `\' so that the Emacs commands for editing
124 Lisp code don't get confused. For example, `?\ ' is the way to write
125 the space character. If the character is `\', you _must_ use a second
126 `\' to quote it: `?\\'. XEmacs 20 always prints punctuation characters
127 with a `\' in front of them, to avoid confusion.
129 You can express the characters Control-g, backspace, tab, newline,
130 vertical tab, formfeed, return, and escape as `?\a', `?\b', `?\t',
131 `?\n', `?\v', `?\f', `?\r', `?\e', respectively. Their character codes
132 are 7, 8, 9, 10, 11, 12, 13, and 27 in decimal. Thus,
137 ?\b => ?\^H ; backspace, <BS>, `C-h'
139 ?\t => ?\t ; tab, <TAB>, `C-i'
141 ?\n => ?\n ; newline, <LFD>, `C-j'
142 ?\v => ?\^K ; vertical tab, `C-k'
143 ?\f => ?\^L ; formfeed character, `C-l'
144 ?\r => ?\r ; carriage return, <RET>, `C-m'
145 ?\e => ?\^[ ; escape character, <ESC>, `C-['
146 ?\\ => ?\\ ; backslash character, `\'
149 ?\b => 8 ; backspace, <BS>, `C-h'
150 ?\t => 9 ; tab, <TAB>, `C-i'
151 ?\n => 10 ; newline, <LFD>, `C-j'
152 ?\v => 11 ; vertical tab, `C-k'
153 ?\f => 12 ; formfeed character, `C-l'
154 ?\r => 13 ; carriage return, <RET>, `C-m'
155 ?\e => 27 ; escape character, <ESC>, `C-['
156 ?\\ => 92 ; backslash character, `\'
158 These sequences which start with backslash are also known as "escape
159 sequences", because backslash plays the role of an escape character;
160 this usage has nothing to do with the character <ESC>.
162 Control characters may be represented using yet another read syntax.
163 This consists of a question mark followed by a backslash, caret, and the
164 corresponding non-control character, in either upper or lower case. For
165 example, both `?\^I' and `?\^i' are valid read syntax for the character
166 `C-i', the character whose value is 9.
168 Instead of the `^', you can use `C-'; thus, `?\C-i' is equivalent to
169 `?\^I' and to `?\^i':
172 ?\^I => ?\t ?\C-I => ?\t
177 There is also a character read syntax beginning with `\M-'. This
178 sets the high bit of the character code (same as adding 128 to the
179 character code). For example, `?\M-A' stands for the character with
180 character code 193, or 128 plus 65. You should _not_ use this syntax
181 in your programs. It is a holdover of yet another confoundance disease
182 from earlier Emacsen. (This was used to represent keyboard input with
183 the <META> key set, thus the `M'; however, it conflicts with the
184 legitimate ISO-8859-1 interpretation of the character code. For
185 example, character code 193 is a lowercase `a' with an acute accent, in
188 Finally, the most general read syntax consists of a question mark
189 followed by a backslash and the character code in octal (up to three
190 octal digits); thus, `?\101' for the character `A', `?\001' for the
191 character `C-a', and `?\002' for the character `C-b'. Although this
192 syntax can represent any ASCII character, it is preferred only when the
193 precise octal value is more important than the ASCII representation.
196 ?\012 => ?\n ?\n => ?\n ?\C-j => ?\n
199 ?\012 => 10 ?\n => 10 ?\C-j => 10
202 A backslash is allowed, and harmless, preceding any character without
203 a special escape meaning; thus, `?\+' is equivalent to `?+'. There is
204 no reason to add a backslash before most characters. However, you
205 should add a backslash before any of the characters `()\|;'`"#.,' to
206 avoid confusing the Emacs commands for editing Lisp code. Also add a
207 backslash before whitespace characters such as space, tab, newline and
208 formfeed. However, it is cleaner to use one of the easily readable
209 escape sequences, such as `\t', instead of an actual whitespace
210 character such as a tab.
213 File: lispref.info, Node: Symbol Type, Next: Sequence Type, Prev: Character Type, Up: Programming Types
218 A "symbol" in XEmacs Lisp is an object with a name. The symbol name
219 serves as the printed representation of the symbol. In ordinary use,
220 the name is unique--no two symbols have the same name.
222 A symbol can serve as a variable, as a function name, or to hold a
223 property list. Or it may serve only to be distinct from all other Lisp
224 objects, so that its presence in a data structure may be recognized
225 reliably. In a given context, usually only one of these uses is
226 intended. But you can use one symbol in all of these ways,
229 A symbol name can contain any characters whatever. Most symbol names
230 are written with letters, digits, and the punctuation characters
231 `-+=*/'. Such names require no special punctuation; the characters of
232 the name suffice as long as the name does not look like a number. (If
233 it does, write a `\' at the beginning of the name to force
234 interpretation as a symbol.) The characters `_~!@$%^&:<>{}' are less
235 often used but also require no special punctuation. Any other
236 characters may be included in a symbol's name by escaping them with a
237 backslash. In contrast to its use in strings, however, a backslash in
238 the name of a symbol simply quotes the single character that follows the
239 backslash. For example, in a string, `\t' represents a tab character;
240 in the name of a symbol, however, `\t' merely quotes the letter `t'.
241 To have a symbol with a tab character in its name, you must actually
242 use a tab (preceded with a backslash). But it's rare to do such a
245 Common Lisp note: In Common Lisp, lower case letters are always
246 "folded" to upper case, unless they are explicitly escaped. In
247 Emacs Lisp, upper case and lower case letters are distinct.
249 Here are several examples of symbol names. Note that the `+' in the
250 fifth example is escaped to prevent it from being read as a number.
251 This is not necessary in the sixth example because the rest of the name
252 makes it invalid as a number.
254 foo ; A symbol named `foo'.
255 FOO ; A symbol named `FOO', different from `foo'.
256 char-to-string ; A symbol named `char-to-string'.
257 1+ ; A symbol named `1+'
258 ; (not `+1', which is an integer).
259 \+1 ; A symbol named `+1'
260 ; (not a very readable name).
261 \(*\ 1\ 2\) ; A symbol named `(* 1 2)' (a worse name).
262 +-*/_~!@$%^&=:<>{} ; A symbol named `+-*/_~!@$%^&=:<>{}'.
263 ; These characters need not be escaped.
266 File: lispref.info, Node: Sequence Type, Next: Cons Cell Type, Prev: Symbol Type, Up: Programming Types
271 A "sequence" is a Lisp object that represents an ordered set of
272 elements. There are two kinds of sequence in XEmacs Lisp, lists and
273 arrays. Thus, an object of type list or of type array is also
274 considered a sequence.
276 Arrays are further subdivided into strings, vectors, and bit vectors.
277 Vectors can hold elements of any type, but string elements must be
278 characters, and bit vector elements must be either 0 or 1. However, the
279 characters in a string can have extents (*note Extents::) and text
280 properties (*note Text Properties::) like characters in a buffer;
281 vectors do not support extents or text properties even when their
282 elements happen to be characters.
284 Lists, strings, vectors, and bit vectors are different, but they have
285 important similarities. For example, all have a length L, and all have
286 elements which can be indexed from zero to L minus one. Also, several
287 functions, called sequence functions, accept any kind of sequence. For
288 example, the function `elt' can be used to extract an element of a
289 sequence, given its index. *Note Sequences Arrays Vectors::.
291 It is impossible to read the same sequence twice, since sequences are
292 always created anew upon reading. If you read the read syntax for a
293 sequence twice, you get two sequences with equal contents. There is one
294 exception: the empty list `()' always stands for the same object, `nil'.
297 File: lispref.info, Node: Cons Cell Type, Next: Array Type, Prev: Sequence Type, Up: Programming Types
299 Cons Cell and List Types
300 ------------------------
302 A "cons cell" is an object comprising two pointers named the CAR and
303 the CDR. Each of them can point to any Lisp object.
305 A "list" is a series of cons cells, linked together so that the CDR
306 of each cons cell points either to another cons cell or to the empty
307 list. *Note Lists::, for functions that work on lists. Because most
308 cons cells are used as part of lists, the phrase "list structure" has
309 come to refer to any structure made out of cons cells.
311 The names CAR and CDR have only historical meaning now. The
312 original Lisp implementation ran on an IBM 704 computer which divided
313 words into two parts, called the "address" part and the "decrement";
314 CAR was an instruction to extract the contents of the address part of a
315 register, and CDR an instruction to extract the contents of the
316 decrement. By contrast, "cons cells" are named for the function `cons'
317 that creates them, which in turn is named for its purpose, the
318 construction of cells.
320 Because cons cells are so central to Lisp, we also have a word for
321 "an object which is not a cons cell". These objects are called "atoms".
323 The read syntax and printed representation for lists are identical,
324 and consist of a left parenthesis, an arbitrary number of elements, and
327 Upon reading, each object inside the parentheses becomes an element
328 of the list. That is, a cons cell is made for each element. The CAR
329 of the cons cell points to the element, and its CDR points to the next
330 cons cell of the list, which holds the next element in the list. The
331 CDR of the last cons cell is set to point to `nil'.
333 A list can be illustrated by a diagram in which the cons cells are
334 shown as pairs of boxes. (The Lisp reader cannot read such an
335 illustration; unlike the textual notation, which can be understood by
336 both humans and computers, the box illustrations can be understood only
337 by humans.) The following represents the three-element list `(rose
340 ___ ___ ___ ___ ___ ___
341 |___|___|--> |___|___|--> |___|___|--> nil
344 --> rose --> violet --> buttercup
346 In this diagram, each box represents a slot that can refer to any
347 Lisp object. Each pair of boxes represents a cons cell. Each arrow is
348 a reference to a Lisp object, either an atom or another cons cell.
350 In this example, the first box, the CAR of the first cons cell,
351 refers to or "contains" `rose' (a symbol). The second box, the CDR of
352 the first cons cell, refers to the next pair of boxes, the second cons
353 cell. The CAR of the second cons cell refers to `violet' and the CDR
354 refers to the third cons cell. The CDR of the third (and last) cons
355 cell refers to `nil'.
357 Here is another diagram of the same list, `(rose violet buttercup)',
358 sketched in a different manner:
360 --------------- ---------------- -------------------
361 | car | cdr | | car | cdr | | car | cdr |
362 | rose | o-------->| violet | o-------->| buttercup | nil |
364 --------------- ---------------- -------------------
366 A list with no elements in it is the "empty list"; it is identical
367 to the symbol `nil'. In other words, `nil' is both a symbol and a list.
369 Here are examples of lists written in Lisp syntax:
371 (A 2 "A") ; A list of three elements.
372 () ; A list of no elements (the empty list).
373 nil ; A list of no elements (the empty list).
374 ("A ()") ; A list of one element: the string `"A ()"'.
375 (A ()) ; A list of two elements: `A' and the empty list.
376 (A nil) ; Equivalent to the previous.
377 ((A B C)) ; A list of one element
378 ; (which is a list of three elements).
380 Here is the list `(A ())', or equivalently `(A nil)', depicted with
384 |___|___|--> |___|___|--> nil
391 * Dotted Pair Notation:: An alternative syntax for lists.
392 * Association List Type:: A specially constructed list.
395 File: lispref.info, Node: Dotted Pair Notation, Next: Association List Type, Up: Cons Cell Type
400 "Dotted pair notation" is an alternative syntax for cons cells that
401 represents the CAR and CDR explicitly. In this syntax, `(A . B)'
402 stands for a cons cell whose CAR is the object A, and whose CDR is the
403 object B. Dotted pair notation is therefore more general than list
404 syntax. In the dotted pair notation, the list `(1 2 3)' is written as
405 `(1 . (2 . (3 . nil)))'. For `nil'-terminated lists, the two
406 notations produce the same result, but list notation is usually clearer
407 and more convenient when it is applicable. When printing a list, the
408 dotted pair notation is only used if the CDR of a cell is not a list.
410 Here's how box notation can illustrate dotted pairs. This example
411 shows the pair `(rose . violet)':
419 Dotted pair notation can be combined with list notation to represent
420 a chain of cons cells with a non-`nil' final CDR. For example, `(rose
421 violet . buttercup)' is equivalent to `(rose . (violet . buttercup))'.
422 The object looks like this:
425 |___|___|--> |___|___|--> buttercup
430 These diagrams make it evident why `(rose . violet . buttercup)' is
431 invalid syntax; it would require a cons cell that has three parts
434 The list `(rose violet)' is equivalent to `(rose . (violet))' and
438 |___|___|--> |___|___|--> nil
443 Similarly, the three-element list `(rose violet buttercup)' is
444 equivalent to `(rose . (violet . (buttercup)))'. It looks like this:
446 ___ ___ ___ ___ ___ ___
447 |___|___|--> |___|___|--> |___|___|--> nil
450 --> rose --> violet --> buttercup
453 File: lispref.info, Node: Association List Type, Prev: Dotted Pair Notation, Up: Cons Cell Type
455 Association List Type
456 .....................
458 An "association list" or "alist" is a specially-constructed list
459 whose elements are cons cells. In each element, the CAR is considered
460 a "key", and the CDR is considered an "associated value". (In some
461 cases, the associated value is stored in the CAR of the CDR.)
462 Association lists are often used as stacks, since it is easy to add or
463 remove associations at the front of the list.
467 (setq alist-of-colors
468 '((rose . red) (lily . white) (buttercup . yellow)))
470 sets the variable `alist-of-colors' to an alist of three elements. In
471 the first element, `rose' is the key and `red' is the value.
473 *Note Association Lists::, for a further explanation of alists and
474 for functions that work on alists.
477 File: lispref.info, Node: Array Type, Next: String Type, Prev: Cons Cell Type, Up: Programming Types
482 An "array" is composed of an arbitrary number of slots for referring
483 to other Lisp objects, arranged in a contiguous block of memory.
484 Accessing any element of an array takes the same amount of time. In
485 contrast, accessing an element of a list requires time proportional to
486 the position of the element in the list. (Elements at the end of a
487 list take longer to access than elements at the beginning of a list.)
489 XEmacs defines three types of array, strings, vectors, and bit
490 vectors. A string is an array of characters, a vector is an array of
491 arbitrary objects, and a bit vector is an array of 1's and 0's. All are
492 one-dimensional. (Most other programming languages support
493 multidimensional arrays, but they are not essential; you can get the
494 same effect with an array of arrays.) Each type of array has its own
495 read syntax; see *Note String Type::, *Note Vector Type::, and *Note
498 An array may have any length up to the largest integer; but once
499 created, it has a fixed size. The first element of an array has index
500 zero, the second element has index 1, and so on. This is called
501 "zero-origin" indexing. For example, an array of four elements has
502 indices 0, 1, 2, and 3.
504 The array type is contained in the sequence type and contains the
505 string type, the vector type, and the bit vector type.
508 File: lispref.info, Node: String Type, Next: Vector Type, Prev: Array Type, Up: Programming Types
513 A "string" is an array of characters. Strings are used for many
514 purposes in XEmacs, as can be expected in a text editor; for example, as
515 the names of Lisp symbols, as messages for the user, and to represent
516 text extracted from buffers. Strings in Lisp are constants: evaluation
517 of a string returns the same string.
519 The read syntax for strings is a double-quote, an arbitrary number of
520 characters, and another double-quote, `"like this"'. The Lisp reader
521 accepts the same formats for reading the characters of a string as it
522 does for reading single characters (without the question mark that
523 begins a character literal). You can enter a nonprinting character such
524 as tab or `C-a' using the convenient escape sequences, like this: `"\t,
525 \C-a"'. You can include a double-quote in a string by preceding it
526 with a backslash; thus, `"\""' is a string containing just a single
527 double-quote character. (*Note Character Type::, for a description of
528 the read syntax for characters.)
530 The printed representation of a string consists of a double-quote,
531 the characters it contains, and another double-quote. However, you must
532 escape any backslash or double-quote characters in the string with a
533 backslash, like this: `"this \" is an embedded quote"'.
535 The newline character is not special in the read syntax for strings;
536 if you write a new line between the double-quotes, it becomes a
537 character in the string. But an escaped newline--one that is preceded
538 by `\'--does not become part of the string; i.e., the Lisp reader
539 ignores an escaped newline while reading a string.
541 "It is useful to include newlines
542 in documentation strings,
545 => "It is useful to include newlines
546 in documentation strings,
547 but the newline is ignored if escaped."
549 A string can hold extents and properties of the text it contains, in
550 addition to the characters themselves. This enables programs that copy
551 text between strings and buffers to preserve the extents and properties
552 with no special effort. *Note Extents::, *Note Text Properties::.
554 Note that FSF GNU Emacs has a special read and print syntax for
555 strings with text properties, but XEmacs does not currently implement
556 this. It was judged better not to include this in XEmacs because it
557 entails that `equal' return `nil' when passed a string with text
558 properties and the equivalent string without text properties, which is
559 often counter-intuitive.
561 *Note Strings and Characters::, for functions that work on strings.
564 File: lispref.info, Node: Vector Type, Next: Bit Vector Type, Prev: String Type, Up: Programming Types
569 A "vector" is a one-dimensional array of elements of any type. It
570 takes a constant amount of time to access any element of a vector. (In
571 a list, the access time of an element is proportional to the distance of
572 the element from the beginning of the list.)
574 The printed representation of a vector consists of a left square
575 bracket, the elements, and a right square bracket. This is also the
576 read syntax. Like numbers and strings, vectors are considered constants
579 [1 "two" (three)] ; A vector of three elements.
582 *Note Vectors::, for functions that work with vectors.
585 File: lispref.info, Node: Bit Vector Type, Next: Function Type, Prev: Vector Type, Up: Programming Types
590 A "bit vector" is a one-dimensional array of 1's and 0's. It takes
591 a constant amount of time to access any element of a bit vector, as for
592 vectors. Bit vectors have an extremely compact internal representation
593 (one machine bit per element), which makes them ideal for keeping track
594 of unordered sets, large collections of boolean values, etc.
596 The printed representation of a bit vector consists of `#*' followed
597 by the bits in the vector. This is also the read syntax. Like
598 numbers, strings, and vectors, bit vectors are considered constants for
601 #*00101000 ; A bit vector of eight elements.
604 *Note Bit Vectors::, for functions that work with bit vectors.
607 File: lispref.info, Node: Function Type, Next: Macro Type, Prev: Bit Vector Type, Up: Programming Types
612 Just as functions in other programming languages are executable,
613 "Lisp function" objects are pieces of executable code. However,
614 functions in Lisp are primarily Lisp objects, and only secondarily the
615 text which represents them. These Lisp objects are lambda expressions:
616 lists whose first element is the symbol `lambda' (*note Lambda
619 In most programming languages, it is impossible to have a function
620 without a name. In Lisp, a function has no intrinsic name. A lambda
621 expression is also called an "anonymous function" (*note Anonymous
622 Functions::). A named function in Lisp is actually a symbol with a
623 valid function in its function cell (*note Defining Functions::).
625 Most of the time, functions are called when their names are written
626 in Lisp expressions in Lisp programs. However, you can construct or
627 obtain a function object at run time and then call it with the primitive
628 functions `funcall' and `apply'. *Note Calling Functions::.
631 File: lispref.info, Node: Macro Type, Next: Primitive Function Type, Prev: Function Type, Up: Programming Types
636 A "Lisp macro" is a user-defined construct that extends the Lisp
637 language. It is represented as an object much like a function, but with
638 different parameter-passing semantics. A Lisp macro has the form of a
639 list whose first element is the symbol `macro' and whose CDR is a Lisp
640 function object, including the `lambda' symbol.
642 Lisp macro objects are usually defined with the built-in `defmacro'
643 function, but any list that begins with `macro' is a macro as far as
644 XEmacs is concerned. *Note Macros::, for an explanation of how to
648 File: lispref.info, Node: Primitive Function Type, Next: Compiled-Function Type, Prev: Macro Type, Up: Programming Types
650 Primitive Function Type
651 -----------------------
653 A "primitive function" is a function callable from Lisp but written
654 in the C programming language. Primitive functions are also called
655 "subrs" or "built-in functions". (The word "subr" is derived from
656 "subroutine".) Most primitive functions evaluate all their arguments
657 when they are called. A primitive function that does not evaluate all
658 its arguments is called a "special form" (*note Special Forms::).
660 It does not matter to the caller of a function whether the function
661 is primitive. However, this does matter if you try to substitute a
662 function written in Lisp for a primitive of the same name. The reason
663 is that the primitive function may be called directly from C code.
664 Calls to the redefined function from Lisp will use the new definition,
665 but calls from C code may still use the built-in definition.
667 The term "function" refers to all Emacs functions, whether written
668 in Lisp or C. *Note Function Type::, for information about the
669 functions written in Lisp.
671 Primitive functions have no read syntax and print in hash notation
672 with the name of the subroutine.
674 (symbol-function 'car) ; Access the function cell
677 (subrp (symbol-function 'car)) ; Is this a primitive function?
681 File: lispref.info, Node: Compiled-Function Type, Next: Autoload Type, Prev: Primitive Function Type, Up: Programming Types
683 Compiled-Function Type
684 ----------------------
686 The byte compiler produces "compiled-function objects". The
687 evaluator handles this data type specially when it appears as a function
688 to be called. *Note Byte Compilation::, for information about the byte
691 The printed representation for a compiled-function object is normally
692 `#<compiled-function...>'. If `print-readably' is true, however, it is
696 File: lispref.info, Node: Autoload Type, Next: Char Table Type, Prev: Compiled-Function Type, Up: Programming Types
701 An "autoload object" is a list whose first element is the symbol
702 `autoload'. It is stored as the function definition of a symbol as a
703 placeholder for the real definition; it says that the real definition
704 is found in a file of Lisp code that should be loaded when necessary.
705 The autoload object contains the name of the file, plus some other
706 information about the real definition.
708 After the file has been loaded, the symbol should have a new function
709 definition that is not an autoload object. The new definition is then
710 called as if it had been there to begin with. From the user's point of
711 view, the function call works as expected, using the function definition
714 An autoload object is usually created with the function `autoload',
715 which stores the object in the function cell of a symbol. *Note
716 Autoload::, for more details.
719 File: lispref.info, Node: Char Table Type, Next: Hash Table Type, Prev: Autoload Type, Up: Programming Types
727 File: lispref.info, Node: Hash Table Type, Next: Range Table Type, Prev: Char Table Type, Up: Programming Types
732 A "hash table" is a table providing an arbitrary mapping from one
733 Lisp object to another, using an internal indexing method called
734 "hashing". Hash tables are very fast (much more efficient that using
735 an association list, when there are a large number of elements in the
738 Hash tables have a special read syntax beginning with
739 `#s(hash-table' (this is an example of "structure" read syntax. This
740 notation is also used for printing when `print-readably' is `t'.
742 Otherwise they print in hash notation (The "hash" in "hash notation"
743 has nothing to do with the "hash" in "hash table"), giving the number
744 of elements, total space allocated for elements, and a unique number
745 assigned at the time the hash table was created. (Hash tables
746 automatically resize as necessary so there is no danger of running out
747 of space for elements.)
749 (make-hash-table :size 50)
750 => #<hash-table 0/107 0x313a>
752 *Note Hash Tables::, for information on how to create and work with
756 File: lispref.info, Node: Range Table Type, Next: Weak List Type, Prev: Hash Table Type, Up: Programming Types
761 A "range table" is a table that maps from ranges of integers to
762 arbitrary Lisp objects. Range tables automatically combine overlapping
763 ranges that map to the same Lisp object, and operations are provided
764 for mapping over all of the ranges in a range table.
766 Range tables have a special read syntax beginning with
767 `#s(range-table' (this is an example of "structure" read syntax, which
768 is also used for char tables and faces).
770 (setq x (make-range-table))
771 (put-range-table 20 50 'foo x)
772 (put-range-table 100 200 "bar" x)
774 => #s(range-table data ((20 50) foo (100 200) "bar"))
776 *Note Range Tables::, for information on how to create and work with
780 File: lispref.info, Node: Weak List Type, Prev: Range Table Type, Up: Programming Types
788 File: lispref.info, Node: Editing Types, Next: Window-System Types, Prev: Programming Types, Up: Lisp Data Types
793 The types in the previous section are common to many Lisp dialects.
794 XEmacs Lisp provides several additional data types for purposes
795 connected with editing.
799 * Buffer Type:: The basic object of editing.
800 * Marker Type:: A position in a buffer.
801 * Extent Type:: A range in a buffer or string, maybe with properties.
802 * Window Type:: Buffers are displayed in windows.
803 * Frame Type:: Windows subdivide frames.
804 * Device Type:: Devices group all frames on a display.
805 * Console Type:: Consoles group all devices with the same keyboard.
806 * Window Configuration Type:: Recording the way a frame is subdivided.
807 * Event Type:: An interesting occurrence in the system.
808 * Process Type:: A process running on the underlying OS.
809 * Stream Type:: Receive or send characters.
810 * Keymap Type:: What function a keystroke invokes.
811 * Syntax Table Type:: What a character means.
812 * Display Table Type:: How display tables are represented.
813 * Database Type:: A connection to an external DBM or DB database.
814 * Charset Type:: A character set (e.g. all Kanji characters),
816 * Coding System Type:: An object encapsulating a way of converting between
817 different textual encodings, under XEmacs/MULE.
818 * ToolTalk Message Type:: A message, in the ToolTalk IPC protocol.
819 * ToolTalk Pattern Type:: A pattern, in the ToolTalk IPC protocol.
822 File: lispref.info, Node: Buffer Type, Next: Marker Type, Up: Editing Types
827 A "buffer" is an object that holds text that can be edited (*note
828 Buffers::). Most buffers hold the contents of a disk file (*note
829 Files::) so they can be edited, but some are used for other purposes.
830 Most buffers are also meant to be seen by the user, and therefore
831 displayed, at some time, in a window (*note Windows::). But a buffer
832 need not be displayed in any window.
834 The contents of a buffer are much like a string, but buffers are not
835 used like strings in XEmacs Lisp, and the available operations are
836 different. For example, insertion of text into a buffer is very
837 efficient, whereas "inserting" text into a string requires
838 concatenating substrings, and the result is an entirely new string
841 Each buffer has a designated position called "point" (*note
842 Positions::). At any time, one buffer is the "current buffer". Most
843 editing commands act on the contents of the current buffer in the
844 neighborhood of point. Many of the standard Emacs functions manipulate
845 or test the characters in the current buffer; a whole chapter in this
846 manual is devoted to describing these functions (*note Text::).
848 Several other data structures are associated with each buffer:
850 * a local syntax table (*note Syntax Tables::);
852 * a local keymap (*note Keymaps::);
854 * a local variable binding list (*note Buffer-Local Variables::);
856 * a list of extents (*note Extents::);
858 * and various other related properties.
860 The local keymap and variable list contain entries that individually
861 override global bindings or values. These are used to customize the
862 behavior of programs in different buffers, without actually changing the
865 A buffer may be "indirect", which means it shares the text of
866 another buffer. *Note Indirect Buffers::.
868 Buffers have no read syntax. They print in hash notation, showing
872 => #<buffer "objects.texi">
875 File: lispref.info, Node: Marker Type, Next: Extent Type, Prev: Buffer Type, Up: Editing Types
880 A "marker" denotes a position in a specific buffer. Markers
881 therefore have two components: one for the buffer, and one for the
882 position. Changes in the buffer's text automatically relocate the
883 position value as necessary to ensure that the marker always points
884 between the same two characters in the buffer.
886 Markers have no read syntax. They print in hash notation, giving the
887 current character position and the name of the buffer.
890 => #<marker at 50661 in objects.texi>
892 *Note Markers::, for information on how to test, create, copy, and
896 File: lispref.info, Node: Extent Type, Next: Window Type, Prev: Marker Type, Up: Editing Types
901 An "extent" specifies temporary alteration of the display appearance
902 of a part of a buffer (or string). It contains markers delimiting a
903 range of the buffer, plus a property list (a list whose elements are
904 alternating property names and values). Extents are used to present
905 parts of the buffer temporarily in a different display style. They
906 have no read syntax, and print in hash notation, giving the buffer name
907 and range of positions.
909 Extents can exist over strings as well as buffers; the primary use
910 of this is to preserve extent and text property information as text is
911 copied from one buffer to another or between different parts of a
914 Extents have no read syntax. They print in hash notation, giving the
915 range of text they cover, the name of the buffer or string they are in,
916 the address in core, and a summary of some of the properties attached to
920 => #<extent [51742, 51748) font-lock text-prop 0x90121e0 in buffer objects.texi>
922 *Note Extents::, for how to create and use extents.
924 Extents are used to implement text properties. *Note Text
928 File: lispref.info, Node: Window Type, Next: Frame Type, Prev: Extent Type, Up: Editing Types
933 A "window" describes the portion of the frame that XEmacs uses to
934 display a buffer. (In standard window-system usage, a "window" is what
935 XEmacs calls a "frame"; XEmacs confusingly uses the term "window" to
936 refer to what is called a "pane" in standard window-system usage.)
937 Every window has one associated buffer, whose contents appear in the
938 window. By contrast, a given buffer may appear in one window, no
939 window, or several windows.
941 Though many windows may exist simultaneously, at any time one window
942 is designated the "selected window". This is the window where the
943 cursor is (usually) displayed when XEmacs is ready for a command. The
944 selected window usually displays the current buffer, but this is not
945 necessarily the case.
947 Windows are grouped on the screen into frames; each window belongs to
948 one and only one frame. *Note Frame Type::.
950 Windows have no read syntax. They print in hash notation, giving the
951 name of the buffer being displayed and a unique number assigned at the
952 time the window was created. (This number can be useful because the
953 buffer displayed in any given window can change frequently.)
956 => #<window on "objects.texi" 0x266c>
958 *Note Windows::, for a description of the functions that work on
962 File: lispref.info, Node: Frame Type, Next: Device Type, Prev: Window Type, Up: Editing Types
967 A FRAME is a rectangle on the screen (a "window" in standard
968 window-system terminology) that contains one or more non-overlapping
969 Emacs windows ("panes" in standard window-system terminology). A frame
970 initially contains a single main window (plus perhaps a minibuffer
971 window) which you can subdivide vertically or horizontally into smaller
974 Frames have no read syntax. They print in hash notation, giving the
975 frame's type, name as used for resourcing, and a unique number assigned
976 at the time the frame was created.
979 => #<x-frame "emacs" 0x9db>
981 *Note Frames::, for a description of the functions that work on
985 File: lispref.info, Node: Device Type, Next: Console Type, Prev: Frame Type, Up: Editing Types
990 A "device" represents a single display on which frames exist.
991 Normally, there is only one device object, but there may be more than
992 one if XEmacs is being run on a multi-headed display (e.g. an X server
993 with attached color and mono screens) or if XEmacs is simultaneously
994 driving frames attached to different consoles, e.g. an X display and a
997 Devices do not have a read syntax. They print in hash notation,
998 giving the device's type, connection name, and a unique number assigned
999 at the time the device was created.
1002 => #<x-device on ":0.0" 0x5b9>
1004 *Note Consoles and Devices::, for a description of several functions
1008 File: lispref.info, Node: Console Type, Next: Window Configuration Type, Prev: Device Type, Up: Editing Types
1013 A "console" represents a single keyboard to which devices (i.e.
1014 displays on which frames exist) are connected. Normally, there is only
1015 one console object, but there may be more than one if XEmacs is
1016 simultaneously driving frames attached to different X servers and/or
1017 TTY connections. (XEmacs is capable of driving multiple X and TTY
1018 connections at the same time, and provides a robust mechanism for
1019 handling the differing display capabilities of such heterogeneous
1020 environments. A buffer with embedded glyphs and multiple fonts and
1021 colors, for example, will display reasonably if it simultaneously
1022 appears on a frame on a color X display, a frame on a mono X display,
1023 and a frame on a TTY connection.)
1025 Consoles do not have a read syntax. They print in hash notation,
1026 giving the console's type, connection name, and a unique number assigned
1027 at the time the console was created.
1030 => #<x-console on "localhost:0" 0x5b7>
1032 *Note Consoles and Devices::, for a description of several functions
1033 related to consoles.
1036 File: lispref.info, Node: Window Configuration Type, Next: Event Type, Prev: Console Type, Up: Editing Types
1038 Window Configuration Type
1039 -------------------------
1041 A "window configuration" stores information about the positions,
1042 sizes, and contents of the windows in a frame, so you can recreate the
1043 same arrangement of windows later.
1045 Window configurations do not have a read syntax. They print in hash
1046 notation, giving a unique number assigned at the time the window
1047 configuration was created.
1049 (current-window-configuration)
1050 => #<window-configuration 0x2db4>
1052 *Note Window Configurations::, for a description of several functions
1053 related to window configurations.
1056 File: lispref.info, Node: Event Type, Next: Process Type, Prev: Window Configuration Type, Up: Editing Types
1061 (not yet documented)
1064 File: lispref.info, Node: Process Type, Next: Stream Type, Prev: Event Type, Up: Editing Types
1069 The word "process" usually means a running program. XEmacs itself
1070 runs in a process of this sort. However, in XEmacs Lisp, a process is a
1071 Lisp object that designates a subprocess created by the XEmacs process.
1072 Programs such as shells, GDB, ftp, and compilers, running in
1073 subprocesses of XEmacs, extend the capabilities of XEmacs.
1075 An Emacs subprocess takes textual input from Emacs and returns
1076 textual output to Emacs for further manipulation. Emacs can also send
1077 signals to the subprocess.
1079 Process objects have no read syntax. They print in hash notation,
1080 giving the name of the process, its associated process ID, and the
1081 current state of the process:
1084 => (#<process "shell" pid 2909 state:run>)
1086 *Note Processes::, for information about functions that create,
1087 delete, return information about, send input or signals to, and receive
1088 output from processes.
1091 File: lispref.info, Node: Stream Type, Next: Keymap Type, Prev: Process Type, Up: Editing Types
1096 A "stream" is an object that can be used as a source or sink for
1097 characters--either to supply characters for input or to accept them as
1098 output. Many different types can be used this way: markers, buffers,
1099 strings, and functions. Most often, input streams (character sources)
1100 obtain characters from the keyboard, a buffer, or a file, and output
1101 streams (character sinks) send characters to a buffer, such as a
1102 `*Help*' buffer, or to the echo area.
1104 The object `nil', in addition to its other meanings, may be used as
1105 a stream. It stands for the value of the variable `standard-input' or
1106 `standard-output'. Also, the object `t' as a stream specifies input
1107 using the minibuffer (*note Minibuffers::) or output in the echo area
1108 (*note The Echo Area::).
1110 Streams have no special printed representation or read syntax, and
1111 print as whatever primitive type they are.
1113 *Note Read and Print::, for a description of functions related to
1114 streams, including parsing and printing functions.
1117 File: lispref.info, Node: Keymap Type, Next: Syntax Table Type, Prev: Stream Type, Up: Editing Types
1122 A "keymap" maps keys typed by the user to commands. This mapping
1123 controls how the user's command input is executed.
1125 NOTE: In XEmacs, a keymap is a separate primitive type. In FSF GNU
1126 Emacs, a keymap is actually a list whose CAR is the symbol `keymap'.
1128 *Note Keymaps::, for information about creating keymaps, handling
1129 prefix keys, local as well as global keymaps, and changing key bindings.
1132 File: lispref.info, Node: Syntax Table Type, Next: Display Table Type, Prev: Keymap Type, Up: Editing Types
1137 Under XEmacs 20, a "syntax table" is a particular type of char
1138 table. Under XEmacs 19, a syntax table a vector of 256 integers. In
1139 both cases, each element defines how one character is interpreted when
1140 it appears in a buffer. For example, in C mode (*note Major Modes::),
1141 the `+' character is punctuation, but in Lisp mode it is a valid
1142 character in a symbol. These modes specify different interpretations by
1143 changing the syntax table entry for `+'.
1145 Syntax tables are used only for scanning text in buffers, not for
1146 reading Lisp expressions. The table the Lisp interpreter uses to read
1147 expressions is built into the XEmacs source code and cannot be changed;
1148 thus, to change the list delimiters to be `{' and `}' instead of `('
1149 and `)' would be impossible.
1151 *Note Syntax Tables::, for details about syntax classes and how to
1152 make and modify syntax tables.
1155 File: lispref.info, Node: Display Table Type, Next: Database Type, Prev: Syntax Table Type, Up: Editing Types
1160 A "display table" specifies how to display each character code.
1161 Each buffer and each window can have its own display table. A display
1162 table is actually a vector of length 256, although in XEmacs 20 this may
1163 change to be a particular type of char table. *Note Display Tables::.
1166 File: lispref.info, Node: Database Type, Next: Charset Type, Prev: Display Table Type, Up: Editing Types
1171 (not yet documented)
1174 File: lispref.info, Node: Charset Type, Next: Coding System Type, Prev: Database Type, Up: Editing Types
1179 (not yet documented)
1182 File: lispref.info, Node: Coding System Type, Next: ToolTalk Message Type, Prev: Charset Type, Up: Editing Types
1187 (not yet documented)
1190 File: lispref.info, Node: ToolTalk Message Type, Next: ToolTalk Pattern Type, Prev: Coding System Type, Up: Editing Types
1192 ToolTalk Message Type
1193 ---------------------
1195 (not yet documented)
1198 File: lispref.info, Node: ToolTalk Pattern Type, Prev: ToolTalk Message Type, Up: Editing Types
1200 ToolTalk Pattern Type
1201 ---------------------
1203 (not yet documented)
1206 File: lispref.info, Node: Window-System Types, Next: Type Predicates, Prev: Editing Types, Up: Lisp Data Types
1211 XEmacs also has some types that represent objects such as faces
1212 (collections of display characters), fonts, and pixmaps that are
1213 commonly found in windowing systems.
1217 * Face Type:: A collection of display characteristics.
1218 * Glyph Type:: An image appearing in a buffer or elsewhere.
1219 * Specifier Type:: A way of controlling display characteristics on
1220 a per-buffer, -frame, -window, or -device level.
1221 * Font Instance Type:: The way a font appears on a particular device.
1222 * Color Instance Type:: The way a color appears on a particular device.
1223 * Image Instance Type:: The way an image appears on a particular device.
1224 * Toolbar Button Type:: An object representing a button in a toolbar.
1225 * Subwindow Type:: An externally-controlled window-system window
1226 appearing in a buffer.
1227 * X Resource Type:: A miscellaneous X resource, if Epoch support was
1228 compiled into XEmacs.
1231 File: lispref.info, Node: Face Type, Next: Glyph Type, Up: Window-System Types
1236 (not yet documented)
1239 File: lispref.info, Node: Glyph Type, Next: Specifier Type, Prev: Face Type, Up: Window-System Types
1244 (not yet documented)
projects / chise / xemacs-chise.git.1 / blob