This is elisp, produced by makeinfo version 4.0f from ./elisp.texi. INFO-DIR-SECTION Editors START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY This Info file contains edition 2.8 of the GNU Emacs Lisp Reference Manual, corresponding to Emacs version 21.2. Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "Copying", with the Front-Cover texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License". (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."  File: elisp, Node: Sequence Functions, Next: Arrays, Up: Sequences Arrays Vectors Sequences ========= In Emacs Lisp, a "sequence" is either a list or an array. The common property of all sequences is that they are ordered collections of elements. This section describes functions that accept any kind of sequence. - Function: sequencep object Returns `t' if OBJECT is a list, vector, or string, `nil' otherwise. - Function: length sequence This function returns the number of elements in SEQUENCE. If SEQUENCE is a cons cell that is not a list (because the final CDR is not `nil'), a `wrong-type-argument' error is signaled. *Note List Elements::, for the related function `safe-length'. (length '(1 2 3)) => 3 (length ()) => 0 (length "foobar") => 6 (length [1 2 3]) => 3 (length (make-bool-vector 5 nil)) => 5 - Function: elt sequence index This function returns the element of SEQUENCE indexed by INDEX. Legitimate values of INDEX are integers ranging from 0 up to one less than the length of SEQUENCE. If SEQUENCE is a list, then out-of-range values of INDEX return `nil'; otherwise, they trigger an `args-out-of-range' error. (elt [1 2 3 4] 2) => 3 (elt '(1 2 3 4) 2) => 3 ;; We use `string' to show clearly which character `elt' returns. (string (elt "1234" 2)) => "3" (elt [1 2 3 4] 4) error--> Args out of range: [1 2 3 4], 4 (elt [1 2 3 4] -1) error--> Args out of range: [1 2 3 4], -1 This function generalizes `aref' (*note Array Functions::) and `nth' (*note List Elements::). - Function: copy-sequence sequence Returns a copy of SEQUENCE. The copy is the same type of object as the original sequence, and it has the same elements in the same order. Storing a new element into the copy does not affect the original SEQUENCE, and vice versa. However, the elements of the new sequence are not copies; they are identical (`eq') to the elements of the original. Therefore, changes made within these elements, as found via the copied sequence, are also visible in the original sequence. If the sequence is a string with text properties, the property list in the copy is itself a copy, not shared with the original's property list. However, the actual values of the properties are shared. *Note Text Properties::. See also `append' in *Note Building Lists::, `concat' in *Note Creating Strings::, and `vconcat' in *Note Vectors::, for other ways to copy sequences. (setq bar '(1 2)) => (1 2) (setq x (vector 'foo bar)) => [foo (1 2)] (setq y (copy-sequence x)) => [foo (1 2)] (eq x y) => nil (equal x y) => t (eq (elt x 1) (elt y 1)) => t ;; Replacing an element of one sequence. (aset x 0 'quux) x => [quux (1 2)] y => [foo (1 2)] ;; Modifying the inside of a shared element. (setcar (aref x 1) 69) x => [quux (69 2)] y => [foo (69 2)]  File: elisp, Node: Arrays, Next: Array Functions, Prev: Sequence Functions, Up: Sequences Arrays Vectors Arrays ====== An "array" object has slots that hold a number of other Lisp objects, called the elements of the array. Any element of an array may be accessed in constant time. In contrast, an element of a list requires access time that is proportional to the position of the element in the list. Emacs defines four types of array, all one-dimensional: "strings", "vectors", "bool-vectors" and "char-tables". A vector is a general array; its elements can be any Lisp objects. A string is a specialized array; its elements must be characters. Each type of array has its own read syntax. *Note String Type::, and *Note Vector Type::. All four kinds of array share these characteristics: * The first element of an array has index zero, the second element has index 1, and so on. This is called "zero-origin" indexing. For example, an array of four elements has indices 0, 1, 2, and 3. * The length of the array is fixed once you create it; you cannot change the length of an existing array. * The array is a constant, for evaluation--in other words, it evaluates to itself. * The elements of an array may be referenced or changed with the functions `aref' and `aset', respectively (*note Array Functions::). When you create an array, other than a char-table, you must specify its length. You cannot specify the length of a char-table, because that is determined by the range of character codes. In principle, if you want an array of text characters, you could use either a string or a vector. In practice, we always choose strings for such applications, for four reasons: * They occupy one-fourth the space of a vector of the same elements. * Strings are printed in a way that shows the contents more clearly as text. * Strings can hold text properties. *Note Text Properties::. * Many of the specialized editing and I/O facilities of Emacs accept only strings. For example, you cannot insert a vector of characters into a buffer the way you can insert a string. *Note Strings and Characters::. By contrast, for an array of keyboard input characters (such as a key sequence), a vector may be necessary, because many keyboard input characters are outside the range that will fit in a string. *Note Key Sequence Input::.  File: elisp, Node: Array Functions, Next: Vectors, Prev: Arrays, Up: Sequences Arrays Vectors Functions that Operate on Arrays ================================ In this section, we describe the functions that accept all types of arrays. - Function: arrayp object This function returns `t' if OBJECT is an array (i.e., a vector, a string, a bool-vector or a char-table). (arrayp [a]) => t (arrayp "asdf") => t (arrayp (syntax-table)) ;; A char-table. => t - Function: aref array index This function returns the INDEXth element of ARRAY. The first element is at index zero. (setq primes [2 3 5 7 11 13]) => [2 3 5 7 11 13] (aref primes 4) => 11 (aref "abcdefg" 1) => 98 ; `b' is ASCII code 98. See also the function `elt', in *Note Sequence Functions::. - Function: aset array index object This function sets the INDEXth element of ARRAY to be OBJECT. It returns OBJECT. (setq w [foo bar baz]) => [foo bar baz] (aset w 0 'fu) => fu w => [fu bar baz] (setq x "asdfasfd") => "asdfasfd" (aset x 3 ?Z) => 90 x => "asdZasfd" If ARRAY is a string and OBJECT is not a character, a `wrong-type-argument' error results. The function converts a unibyte string to multibyte if necessary to insert a character. - Function: fillarray array object This function fills the array ARRAY with OBJECT, so that each element of ARRAY is OBJECT. It returns ARRAY. (setq a [a b c d e f g]) => [a b c d e f g] (fillarray a 0) => [0 0 0 0 0 0 0] a => [0 0 0 0 0 0 0] (setq s "When in the course") => "When in the course" (fillarray s ?-) => "------------------" If ARRAY is a string and OBJECT is not a character, a `wrong-type-argument' error results. The general sequence functions `copy-sequence' and `length' are often useful for objects known to be arrays. *Note Sequence Functions::.  File: elisp, Node: Vectors, Next: Vector Functions, Prev: Array Functions, Up: Sequences Arrays Vectors Vectors ======= Arrays in Lisp, like arrays in most languages, are blocks of memory whose elements can be accessed in constant time. A "vector" is a general-purpose array of specified length; its elements can be any Lisp objects. (By contrast, a string can hold only characters as elements.) Vectors in Emacs are used for obarrays (vectors of symbols), and as part of keymaps (vectors of commands). They are also used internally as part of the representation of a byte-compiled function; if you print such a function, you will see a vector in it. In Emacs Lisp, the indices of the elements of a vector start from zero and count up from there. Vectors are printed with square brackets surrounding the elements. Thus, a vector whose elements are the symbols `a', `b' and `a' is printed as `[a b a]'. You can write vectors in the same way in Lisp input. A vector, like a string or a number, is considered a constant for evaluation: the result of evaluating it is the same vector. This does not evaluate or even examine the elements of the vector. *Note Self-Evaluating Forms::. Here are examples illustrating these principles: (setq avector [1 two '(three) "four" [five]]) => [1 two (quote (three)) "four" [five]] (eval avector) => [1 two (quote (three)) "four" [five]] (eq avector (eval avector)) => t  File: elisp, Node: Vector Functions, Next: Char-Tables, Prev: Vectors, Up: Sequences Arrays Vectors Functions for Vectors ===================== Here are some functions that relate to vectors: - Function: vectorp object This function returns `t' if OBJECT is a vector. (vectorp [a]) => t (vectorp "asdf") => nil - Function: vector &rest objects This function creates and returns a vector whose elements are the arguments, OBJECTS. (vector 'foo 23 [bar baz] "rats") => [foo 23 [bar baz] "rats"] (vector) => [] - Function: make-vector length object This function returns a new vector consisting of LENGTH elements, each initialized to OBJECT. (setq sleepy (make-vector 9 'Z)) => [Z Z Z Z Z Z Z Z Z] - Function: vconcat &rest sequences This function returns a new vector containing all the elements of the SEQUENCES. The arguments SEQUENCES may be any kind of arrays, including lists, vectors, or strings. If no SEQUENCES are given, an empty vector is returned. The value is a newly constructed vector that is not `eq' to any existing vector. (setq a (vconcat '(A B C) '(D E F))) => [A B C D E F] (eq a (vconcat a)) => nil (vconcat) => [] (vconcat [A B C] "aa" '(foo (6 7))) => [A B C 97 97 foo (6 7)] The `vconcat' function also allows byte-code function objects as arguments. This is a special feature to make it easy to access the entire contents of a byte-code function object. *Note Byte-Code Objects::. The `vconcat' function also allows integers as arguments. It converts them to strings of digits, making up the decimal print representation of the integer, and then uses the strings instead of the original integers. *Don't use this feature; we plan to eliminate it. If you already use this feature, change your programs now!* The proper way to convert an integer to a decimal number in this way is with `format' (*note Formatting Strings::) or `number-to-string' (*note String Conversion::). For other concatenation functions, see `mapconcat' in *Note Mapping Functions::, `concat' in *Note Creating Strings::, and `append' in *Note Building Lists::. The `append' function provides a way to convert a vector into a list with the same elements (*note Building Lists::): (setq avector [1 two (quote (three)) "four" [five]]) => [1 two (quote (three)) "four" [five]] (append avector nil) => (1 two (quote (three)) "four" [five])  File: elisp, Node: Char-Tables, Next: Bool-Vectors, Prev: Vector Functions, Up: Sequences Arrays Vectors Char-Tables =========== A char-table is much like a vector, except that it is indexed by character codes. Any valid character code, without modifiers, can be used as an index in a char-table. You can access a char-table's elements with `aref' and `aset', as with any array. In addition, a char-table can have "extra slots" to hold additional data not associated with particular character codes. Char-tables are constants when evaluated. Each char-table has a "subtype" which is a symbol. The subtype has two purposes: to distinguish char-tables meant for different uses, and to control the number of extra slots. For example, display tables are char-tables with `display-table' as the subtype, and syntax tables are char-tables with `syntax-table' as the subtype. A valid subtype must have a `char-table-extra-slots' property which is an integer between 0 and 10. This integer specifies the number of "extra slots" in the char-table. A char-table can have a "parent", which is another char-table. If it does, then whenever the char-table specifies `nil' for a particular character C, it inherits the value specified in the parent. In other words, `(aref CHAR-TABLE C)' returns the value from the parent of CHAR-TABLE if CHAR-TABLE itself specifies `nil'. A char-table can also have a "default value". If so, then `(aref CHAR-TABLE C)' returns the default value whenever the char-table does not specify any other non-`nil' value. - Function: make-char-table subtype &optional init Return a newly created char-table, with subtype SUBTYPE. Each element is initialized to INIT, which defaults to `nil'. You cannot alter the subtype of a char-table after the char-table is created. There is no argument to specify the length of the char-table, because all char-tables have room for any valid character code as an index. - Function: char-table-p object This function returns `t' if OBJECT is a char-table, otherwise `nil'. - Function: char-table-subtype char-table This function returns the subtype symbol of CHAR-TABLE. - Function: set-char-table-default char-table new-default This function sets the default value of CHAR-TABLE to NEW-DEFAULT. There is no special function to access the default value of a char-table. To do that, use `(char-table-range CHAR-TABLE nil)'. - Function: char-table-parent char-table This function returns the parent of CHAR-TABLE. The parent is always either `nil' or another char-table. - Function: set-char-table-parent char-table new-parent This function sets the parent of CHAR-TABLE to NEW-PARENT. - Function: char-table-extra-slot char-table n This function returns the contents of extra slot N of CHAR-TABLE. The number of extra slots in a char-table is determined by its subtype. - Function: set-char-table-extra-slot char-table n value This function stores VALUE in extra slot N of CHAR-TABLE. A char-table can specify an element value for a single character code; it can also specify a value for an entire character set. - Function: char-table-range char-table range This returns the value specified in CHAR-TABLE for a range of characters RANGE. Here are the possibilities for RANGE: `nil' Refers to the default value. CHAR Refers to the element for character CHAR (supposing CHAR is a valid character code). CHARSET Refers to the value specified for the whole character set CHARSET (*note Character Sets::). GENERIC-CHAR A generic character stands for a character set; specifying the generic character as argument is equivalent to specifying the character set name. *Note Splitting Characters::, for a description of generic characters. - Function: set-char-table-range char-table range value This function sets the value in CHAR-TABLE for a range of characters RANGE. Here are the possibilities for RANGE: `nil' Refers to the default value. `t' Refers to the whole range of character codes. CHAR Refers to the element for character CHAR (supposing CHAR is a valid character code). CHARSET Refers to the value specified for the whole character set CHARSET (*note Character Sets::). GENERIC-CHAR A generic character stands for a character set; specifying the generic character as argument is equivalent to specifying the character set name. *Note Splitting Characters::, for a description of generic characters. - Function: map-char-table function char-table This function calls FUNCTION for each element of CHAR-TABLE. FUNCTION is called with two arguments, a key and a value. The key is a possible RANGE argument for `char-table-range'--either a valid character or a generic character--and the value is `(char-table-range CHAR-TABLE KEY)'. Overall, the key-value pairs passed to FUNCTION describe all the values stored in CHAR-TABLE. The return value is always `nil'; to make this function useful, FUNCTION should have side effects. For example, here is how to examine each element of the syntax table: (let (accumulator) (map-char-table #'(lambda (key value) (setq accumulator (cons (list key value) accumulator))) (syntax-table)) accumulator) => ((475008 nil) (474880 nil) (474752 nil) (474624 nil) ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))  File: elisp, Node: Bool-Vectors, Prev: Char-Tables, Up: Sequences Arrays Vectors Bool-vectors ============ A bool-vector is much like a vector, except that it stores only the values `t' and `nil'. If you try to store any non-`nil' value into an element of the bool-vector, the effect is to store `t' there. As with all arrays, bool-vector indices start from 0, and the length cannot be changed once the bool-vector is created. Bool-vectors are constants when evaluated. There are two special functions for working with bool-vectors; aside from that, you manipulate them with same functions used for other kinds of arrays. - Function: make-bool-vector length initial Return a new bool-vector of LENGTH elements, each one initialized to INITIAL. - Function: bool-vector-p object This returns `t' if OBJECT is a bool-vector, and `nil' otherwise. Here is an example of creating, examining, and updating a bool-vector. Note that the printed form represents up to 8 boolean values as a single character. (setq bv (make-bool-vector 5 t)) => #&5"^_" (aref bv 1) => t (aset bv 3 nil) => nil bv => #&5"^W" These results make sense because the binary codes for control-_ and control-W are 11111 and 10111, respectively.  File: elisp, Node: Hash Tables, Next: Symbols, Prev: Sequences Arrays Vectors, Up: Top Hash Tables *********** A hash table is a very fast kind of lookup table, somewhat like an alist in that it maps keys to corresponding values. It differs from an alist in these ways: * Lookup in a hash table is extremely fast for large tables--in fact, the time required is essentially _independent_ of how many elements are stored in the table. For smaller tables (a few tens of elements) alists may still be faster because hash tables have a more-or-less constant overhead. * The correspondences in a hash table are in no particular order. * There is no way to share structure between two hash tables, the way two alists can share a common tail. Emacs Lisp (starting with Emacs 21) provides a general-purpose hash table data type, along with a series of functions for operating on them. Hash tables have no read syntax, and print in hash notation, like this: (make-hash-table) => # (The term "hash notation" refers to the initial `#' character--*note Printed Representation::--and has nothing to do with the term "hash table.") Obarrays are also a kind of hash table, but they are a different type of object and are used only for recording interned symbols (*note Creating Symbols::). * Menu: * Creating Hash:: * Hash Access:: * Defining Hash:: * Other Hash::  File: elisp, Node: Creating Hash, Next: Hash Access, Up: Hash Tables Creating Hash Tables ==================== The principal function for creating a hash table is `make-hash-table'. - Function: make-hash-table &rest keyword-args This function creates a new hash table according to the specified arguments. The arguments should consist of alternating keywords (particular symbols recognized specially) and values corresponding to them. Several keywords make sense in `make-hash-table', but the only two that you really need to know about are `:test' and `:weakness'. `:test TEST' This specifies the method of key lookup for this hash table. The default is `eql'; `eq' and `equal' are other alternatives: `eql' Keys which are numbers are "the same" if they are equal in value; otherwise, two distinct objects are never "the same". `eq' Any two distinct Lisp objects are "different" as keys. `equal' Two Lisp objects are "the same", as keys, if they are equal according to `equal'. You can use `define-hash-table-test' (*note Defining Hash::) to define additional possibilities for TEST. `:weakness WEAK' The weakness of a hash table specifies whether the presence of a key or value in the hash table preserves it from garbage collection. The value, WEAK, must be one of `nil', `key', `value', `key-or-value', `key-and-value', or `t' which is an alias for `key-and-value'. If WEAK is `key' then the hash table does not prevent its keys from being collected as garbage (if they are not referenced anywhere else); if a particular key does get collected, the corresponding association is removed from the hash table. If WEAK is `value', then the hash table does not prevent values from being collected as garbage (if they are not referenced anywhere else); if a particular value does get collected, the corresponding association is removed from the hash table. If WEAK is `key-or-value' or `t', the hash table does not protect either keys or values from garbage collection; if either one is collected as garbage, the association is removed. If WEAK is `key-and-value', associations are removed from the hash table when both their key and value would be collected as garbage, again not considering references to the key and value from weak hash tables. The default for WEAK is `nil', so that all keys and values referenced in the hash table are preserved from garbage collection. If WEAK is `t', neither keys nor values are protected (that is, both are weak). `:size SIZE' This specifies a hint for how many associations you plan to store in the hash table. If you know the approximate number, you can make things a little more efficient by specifying it this way. If you specify too small a size, the hash table will grow automatically when necessary, but doing that takes some extra time. The default size is 65. `:rehash-size REHASH-SIZE' When you add an association to a hash table and the table is "full," it grows automatically. This value specifies how to make the hash table larger, at that time. If REHASH-SIZE is an integer, it should be positive, and the hash table grows by adding that much to the nominal size. If REHASH-SIZE is a floating point number, it had better be greater than 1, and the hash table grows by multiplying the old size by that number. The default value is 1.5. `:rehash-threshold THRESHOLD' This specifies the criterion for when the hash table is "full." The value, THRESHOLD, should be a positive floating point number, no greater than 1. The hash table is "full" whenever the actual number of entries exceeds this fraction of the nominal size. The default for THRESHOLD is 0.8. - Function: makehash &optional test This is equivalent to `make-hash-table', but with a different style argument list. The argument TEST specifies the method of key lookup. If you want to specify other parameters, you should use `make-hash-table'.  File: elisp, Node: Hash Access, Next: Defining Hash, Prev: Creating Hash, Up: Hash Tables Hash Table Access ================= This section describes the functions for accessing and storing associations in a hash table. - Function: gethash key table &optional default This function looks up KEY in TABLE, and returns its associated VALUE--or DEFAULT, if KEY has no association in TABLE. - Function: puthash key value table This function enters an association for KEY in TABLE, with value VALUE. If KEY already has an association in TABLE, VALUE replaces the old associated value. - Function: remhash key table This function removes the association for KEY from TABLE, if there is one. If KEY has no association, `remhash' does nothing. - Function: clrhash table This function removes all the associations from hash table TABLE, so that it becomes empty. This is also called "clearing" the hash table. - Function: maphash function table This function calls FUNCTION once for each of the associations in TABLE. The function FUNCTION should accept two arguments--a KEY listed in TABLE, and its associated VALUE.  File: elisp, Node: Defining Hash, Next: Other Hash, Prev: Hash Access, Up: Hash Tables Defining Hash Comparisons ========================= You can define new methods of key lookup by means of `define-hash-table-test'. In order to use this feature, you need to understand how hash tables work, and what a "hash code" means. You can think of a hash table conceptually as a large array of many slots, each capable of holding one association. To look up a key, `gethash' first computes an integer, the hash code, from the key. It reduces this integer modulo the length of the array, to produce an index in the array. Then it looks in that slot, and if necessary in other nearby slots, to see if it has found the key being sought. Thus, to define a new method of key lookup, you need to specify both a function to compute the hash code from a key, and a function to compare two keys directly. - Function: define-hash-table-test name test-fn hash-fn This function defines a new hash table test, named NAME. After defining NAME in this way, you can use it as the TEST argument in `make-hash-table'. When you do that, the hash table will use TEST-FN to compare key values, and HASH-FN to compute a "hash code" from a key value. The function TEST-FN should accept two arguments, two keys, and return non-`nil' if they are considered "the same." The function HASH-FN should accept one argument, a key, and return an integer that is the "hash code" of that key. For good results, the function should use the whole range of integer values for hash codes, including negative integers. The specified functions are stored in the property list of NAME under the property `hash-table-test'; the property value's form is `(TEST-FN HASH-FN)'. - Function: sxhash obj This function returns a hash code for Lisp object OBJ. This is an integer which reflects the contents of OBJ and the other Lisp objects it points to. If two objects OBJ1 and OBJ2 are equal, then `(sxhash OBJ1)' and `(sxhash OBJ2)' are the same integer. If the two objects are not equal, the values returned by `sxhash' are usually different, but not always; but once in a rare while, by luck, you will encounter two distinct-looking objects that give the same result from `sxhash'. This example creates a hash table whose keys are strings that are compared case-insensitively. (defun case-fold-string= (a b) (compare-strings a nil nil b nil nil t)) (defun case-fold-string-hash (a) (sxhash (upcase a))) (define-hash-table-test 'case-fold 'case-fold-string= 'case-fold-string-hash)) (make-hash-table :test 'case-fold) Here is how you could define a hash table test equivalent to the predefined test value `equal'. The keys can be any Lisp object, and equal-looking objects are considered the same key. (define-hash-table-test 'contents-hash 'equal 'sxhash) (make-hash-table :test 'contents-hash)  File: elisp, Node: Other Hash, Prev: Defining Hash, Up: Hash Tables Other Hash Table Functions ========================== Here are some other functions for working with hash tables. - Function: hash-table-p table This returns non-`nil' if TABLE is a hash table object. - Function: copy-hash-table table This function creates and returns a copy of TABLE. Only the table itself is copied--the keys and values are shared. - Function: hash-table-count table This function returns the actual number of entries in TABLE. - Function: hash-table-test table This returns the TEST value that was given when TABLE was created, to specify how to hash and compare keys. See `make-hash-table' (*note Creating Hash::). - Function: hash-table-weakness table This function returns the WEAK value that was specified for hash table TABLE. - Function: hash-table-rehash-size table This returns the rehash size of TABLE. - Function: hash-table-rehash-threshold table This returns the rehash threshold of TABLE. - Function: hash-table-size table This returns the current nominal size of TABLE.  File: elisp, Node: Symbols, Next: Evaluation, Prev: Hash Tables, Up: Top Symbols ******* A "symbol" is an object with a unique name. This chapter describes symbols, their components, their property lists, and how they are created and interned. Separate chapters describe the use of symbols as variables and as function names; see *Note Variables::, and *Note Functions::. For the precise read syntax for symbols, see *Note Symbol Type::. You can test whether an arbitrary Lisp object is a symbol with `symbolp': - Function: symbolp object This function returns `t' if OBJECT is a symbol, `nil' otherwise. * Menu: * Symbol Components:: Symbols have names, values, function definitions and property lists. * Definitions:: A definition says how a symbol will be used. * Creating Symbols:: How symbols are kept unique. * Property Lists:: Each symbol has a property list for recording miscellaneous information.  File: elisp, Node: Symbol Components, Next: Definitions, Prev: Symbols, Up: Symbols Symbol Components ================= Each symbol has four components (or "cells"), each of which references another object: Print name The "print name cell" holds a string that names the symbol for reading and printing. See `symbol-name' in *Note Creating Symbols::. Value The "value cell" holds the current value of the symbol as a variable. When a symbol is used as a form, the value of the form is the contents of the symbol's value cell. See `symbol-value' in *Note Accessing Variables::. Function The "function cell" holds the function definition of the symbol. When a symbol is used as a function, its function definition is used in its place. This cell is also used to make a symbol stand for a keymap or a keyboard macro, for editor command execution. Because each symbol has separate value and function cells, variables names and function names do not conflict. See `symbol-function' in *Note Function Cells::. Property list The "property list cell" holds the property list of the symbol. See `symbol-plist' in *Note Property Lists::. The print name cell always holds a string, and cannot be changed. The other three cells can be set individually to any specified Lisp object. The print name cell holds the string that is the name of the symbol. Since symbols are represented textually by their names, it is important not to have two symbols with the same name. The Lisp reader ensures this: every time it reads a symbol, it looks for an existing symbol with the specified name before it creates a new one. (In GNU Emacs Lisp, this lookup uses a hashing algorithm and an obarray; see *Note Creating Symbols::.) The value cell holds the symbol's value as a variable (*note Variables::). That is what you get if you evaluate the symbol as a Lisp expression (*note Evaluation::). Any Lisp object is a legitimate value. Certain symbols have values that cannot be changed; these include `nil' and `t', and any symbol whose name starts with `:' (those are called "keywords"). *Note Constant Variables::. We often refer to "the function `foo'" when we really mean the function stored in the function cell of the symbol `foo'. We make the distinction explicit only when necessary. In normal usage, the function cell usually contains a function (*note Functions::) or a macro (*note Macros::), as that is what the Lisp interpreter expects to see there (*note Evaluation::). Keyboard macros (*note Keyboard Macros::), keymaps (*note Keymaps::) and autoload objects (*note Autoloading::) are also sometimes stored in the function cells of symbols. The property list cell normally should hold a correctly formatted property list (*note Property Lists::), as a number of functions expect to see a property list there. The function cell or the value cell may be "void", which means that the cell does not reference any object. (This is not the same thing as holding the symbol `void', nor the same as holding the symbol `nil'.) Examining a function or value cell that is void results in an error, such as `Symbol's value as variable is void'. The four functions `symbol-name', `symbol-value', `symbol-plist', and `symbol-function' return the contents of the four cells of a symbol. Here as an example we show the contents of the four cells of the symbol `buffer-file-name': (symbol-name 'buffer-file-name) => "buffer-file-name" (symbol-value 'buffer-file-name) => "/gnu/elisp/symbols.texi" (symbol-plist 'buffer-file-name) => (variable-documentation 29529) (symbol-function 'buffer-file-name) => # Because this symbol is the variable which holds the name of the file being visited in the current buffer, the value cell contents we see are the name of the source file of this chapter of the Emacs Lisp Manual. The property list cell contains the list `(variable-documentation 29529)' which tells the documentation functions where to find the documentation string for the variable `buffer-file-name' in the `DOC-VERSION' file. (29529 is the offset from the beginning of the `DOC-VERSION' file to where that documentation string begins--see *Note Documentation Basics::.) The function cell contains the function for returning the name of the file. `buffer-file-name' names a primitive function, which has no read syntax and prints in hash notation (*note Primitive Function Type::). A symbol naming a function written in Lisp would have a lambda expression (or a byte-code object) in this cell.  File: elisp, Node: Definitions, Next: Creating Symbols, Prev: Symbol Components, Up: Symbols Defining Symbols ================ A "definition" in Lisp is a special form that announces your intention to use a certain symbol in a particular way. In Emacs Lisp, you can define a symbol as a variable, or define it as a function (or macro), or both independently. A definition construct typically specifies a value or meaning for the symbol for one kind of use, plus documentation for its meaning when used in this way. Thus, when you define a symbol as a variable, you can supply an initial value for the variable, plus documentation for the variable. `defvar' and `defconst' are special forms that define a symbol as a global variable. They are documented in detail in *Note Defining Variables::. For defining user option variables that can be customized, use `defcustom' (*note Customization::). `defun' defines a symbol as a function, creating a lambda expression and storing it in the function cell of the symbol. This lambda expression thus becomes the function definition of the symbol. (The term "function definition", meaning the contents of the function cell, is derived from the idea that `defun' gives the symbol its definition as a function.) `defsubst' and `defalias' are two other ways of defining a function. *Note Functions::. `defmacro' defines a symbol as a macro. It creates a macro object and stores it in the function cell of the symbol. Note that a given symbol can be a macro or a function, but not both at once, because both macro and function definitions are kept in the function cell, and that cell can hold only one Lisp object at any given time. *Note Macros::. In Emacs Lisp, a definition is not required in order to use a symbol as a variable or function. Thus, you can make a symbol a global variable with `setq', whether you define it first or not. The real purpose of definitions is to guide programmers and programming tools. They inform programmers who read the code that certain symbols are _intended_ to be used as variables, or as functions. In addition, utilities such as `etags' and `make-docfile' recognize definitions, and add appropriate information to tag tables and the `DOC-VERSION' file. *Note Accessing Documentation::.  File: elisp, Node: Creating Symbols, Next: Property Lists, Prev: Definitions, Up: Symbols Creating and Interning Symbols ============================== To understand how symbols are created in GNU Emacs Lisp, you must know how Lisp reads them. Lisp must ensure that it finds the same symbol every time it reads the same set of characters. Failure to do so would cause complete confusion. When the Lisp reader encounters a symbol, it reads all the characters of the name. Then it "hashes" those characters to find an index in a table called an "obarray". Hashing is an efficient method of looking something up. For example, instead of searching a telephone book cover to cover when looking up Jan Jones, you start with the J's and go from there. That is a simple version of hashing. Each element of the obarray is a "bucket" which holds all the symbols with a given hash code; to look for a given name, it is sufficient to look through all the symbols in the bucket for that name's hash code. (The same idea is used for general Emacs hash tables, but they are a different data type; see *Note Hash Tables::.) If a symbol with the desired name is found, the reader uses that symbol. If the obarray does not contain a symbol with that name, the reader makes a new symbol and adds it to the obarray. Finding or adding a symbol with a certain name is called "interning" it, and the symbol is then called an "interned symbol". Interning ensures that each obarray has just one symbol with any particular name. Other like-named symbols may exist, but not in the same obarray. Thus, the reader gets the same symbols for the same names, as long as you keep reading with the same obarray. Interning usually happens automatically in the reader, but sometimes other programs need to do it. For example, after the `M-x' command obtains the command name as a string using the minibuffer, it then interns the string, to get the interned symbol with that name. No obarray contains all symbols; in fact, some symbols are not in any obarray. They are called "uninterned symbols". An uninterned symbol has the same four cells as other symbols; however, the only way to gain access to it is by finding it in some other object or as the value of a variable. Creating an uninterned symbol is useful in generating Lisp code, because an uninterned symbol used as a variable in the code you generate cannot clash with any variables used in other Lisp programs. In Emacs Lisp, an obarray is actually a vector. Each element of the vector is a bucket; its value is either an interned symbol whose name hashes to that bucket, or 0 if the bucket is empty. Each interned symbol has an internal link (invisible to the user) to the next symbol in the bucket. Because these links are invisible, there is no way to find all the symbols in an obarray except using `mapatoms' (below). The order of symbols in a bucket is not significant. In an empty obarray, every element is 0, so you can create an obarray with `(make-vector LENGTH 0)'. *This is the only valid way to create an obarray.* Prime numbers as lengths tend to result in good hashing; lengths one less than a power of two are also good. *Do not try to put symbols in an obarray yourself.* This does not work--only `intern' can enter a symbol in an obarray properly. Common Lisp note: In Common Lisp, a single symbol may be interned in several obarrays. Most of the functions below take a name and sometimes an obarray as arguments. A `wrong-type-argument' error is signaled if the name is not a string, or if the obarray is not a vector. - Function: symbol-name symbol This function returns the string that is SYMBOL's name. For example: (symbol-name 'foo) => "foo" *Warning:* Changing the string by substituting characters does change the name of the symbol, but fails to update the obarray, so don't do it! - Function: make-symbol name This function returns a newly-allocated, uninterned symbol whose name is NAME (which must be a string). Its value and function definition are void, and its property list is `nil'. In the example below, the value of `sym' is not `eq' to `foo' because it is a distinct uninterned symbol whose name is also `foo'. (setq sym (make-symbol "foo")) => foo (eq sym 'foo) => nil - Function: intern name &optional obarray This function returns the interned symbol whose name is NAME. If there is no such symbol in the obarray OBARRAY, `intern' creates a new one, adds it to the obarray, and returns it. If OBARRAY is omitted, the value of the global variable `obarray' is used. (setq sym (intern "foo")) => foo (eq sym 'foo) => t (setq sym1 (intern "foo" other-obarray)) => foo (eq sym1 'foo) => nil Common Lisp note: In Common Lisp, you can intern an existing symbol in an obarray. In Emacs Lisp, you cannot do this, because the argument to `intern' must be a string, not a symbol. - Function: intern-soft name &optional obarray This function returns the symbol in OBARRAY whose name is NAME, or `nil' if OBARRAY has no symbol with that name. Therefore, you can use `intern-soft' to test whether a symbol with a given name is already interned. If OBARRAY is omitted, the value of the global variable `obarray' is used. The argument NAME may also be a symbol; in that case, the function returns NAME if NAME is interned in the specified obarray, and otherwise `nil'. (intern-soft "frazzle") ; No such symbol exists. => nil (make-symbol "frazzle") ; Create an uninterned one. => frazzle (intern-soft "frazzle") ; That one cannot be found. => nil (setq sym (intern "frazzle")) ; Create an interned one. => frazzle (intern-soft "frazzle") ; That one can be found! => frazzle (eq sym 'frazzle) ; And it is the same one. => t - Variable: obarray This variable is the standard obarray for use by `intern' and `read'. - Function: mapatoms function &optional obarray This function calls FUNCTION once with each symbol in the obarray OBARRAY. Then it returns `nil'. If OBARRAY is omitted, it defaults to the value of `obarray', the standard obarray for ordinary symbols. (setq count 0) => 0 (defun count-syms (s) (setq count (1+ count))) => count-syms (mapatoms 'count-syms) => nil count => 1871 See `documentation' in *Note Accessing Documentation::, for another example using `mapatoms'. - Function: unintern symbol &optional obarray This function deletes SYMBOL from the obarray OBARRAY. If `symbol' is not actually in the obarray, `unintern' does nothing. If OBARRAY is `nil', the current obarray is used. If you provide a string instead of a symbol as SYMBOL, it stands for a symbol name. Then `unintern' deletes the symbol (if any) in the obarray which has that name. If there is no such symbol, `unintern' does nothing. If `unintern' does delete a symbol, it returns `t'. Otherwise it returns `nil'.  File: elisp, Node: Property Lists, Prev: Creating Symbols, Up: Symbols Property Lists ============== A "property list" ("plist" for short) is a list of paired elements stored in the property list cell of a symbol. Each of the pairs associates a property name (usually a symbol) with a property or value. Property lists are generally used to record information about a symbol, such as its documentation as a variable, the name of the file where it was defined, or perhaps even the grammatical class of the symbol (representing a word) in a language-understanding system. Character positions in a string or buffer can also have property lists. *Note Text Properties::. The property names and values in a property list can be any Lisp objects, but the names are usually symbols. Property list functions compare the property names using `eq'. Here is an example of a property list, found on the symbol `progn' when the compiler is loaded: (lisp-indent-function 0 byte-compile byte-compile-progn) Here `lisp-indent-function' and `byte-compile' are property names, and the other two elements are the corresponding values. * Menu: * Plists and Alists:: Comparison of the advantages of property lists and association lists. * Symbol Plists:: Functions to access symbols' property lists. * Other Plists:: Accessing property lists stored elsewhere.  File: elisp, Node: Plists and Alists, Next: Symbol Plists, Up: Property Lists Property Lists and Association Lists ------------------------------------ Association lists (*note Association Lists::) are very similar to property lists. In contrast to association lists, the order of the pairs in the property list is not significant since the property names must be distinct. Property lists are better than association lists for attaching information to various Lisp function names or variables. If your program keeps all of its associations in one association list, it will typically need to search that entire list each time it checks for an association. This could be slow. By contrast, if you keep the same information in the property lists of the function names or variables themselves, each search will scan only the length of one property list, which is usually short. This is why the documentation for a variable is recorded in a property named `variable-documentation'. The byte compiler likewise uses properties to record those functions needing special treatment. However, association lists have their own advantages. Depending on your application, it may be faster to add an association to the front of an association list than to update a property. All properties for a symbol are stored in the same property list, so there is a possibility of a conflict between different uses of a property name. (For this reason, it is a good idea to choose property names that are probably unique, such as by beginning the property name with the program's usual name-prefix for variables and functions.) An association list may be used like a stack where associations are pushed on the front of the list and later discarded; this is not possible with a property list.