@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/symbols
-@node Symbols, Evaluation, Sequences Arrays Vectors, Top
+@node Symbols, Evaluation, Hash Tables, Top
@chapter Symbols
@cindex symbol
@table @asis
@item Print name
@cindex print name cell
-The @dfn{print name cell} holds a string which names the symbol for
+The @dfn{print name cell} holds a string that names the symbol for
reading and printing. See @code{symbol-name} in @ref{Creating Symbols}.
@item Value
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 and function names do
+has separate value and function cells, variables names and function names do
not conflict. See @code{symbol-function} in @ref{Function Cells}.
@item Property list
this lookup uses a hashing algorithm and an obarray; see @ref{Creating
Symbols}.)
- In normal usage, the function cell usually contains a function or
-macro, as that is what the Lisp interpreter expects to see there
-(@pxref{Evaluation}). Keyboard macros (@pxref{Keyboard Macros}),
-keymaps (@pxref{Keymaps}) and autoload objects (@pxref{Autoloading}) are
-also sometimes stored in the function cell of symbols. We often refer
-to ``the function @code{foo}'' when we really mean the function stored
-in the function cell of the symbol @code{foo}. We make the distinction
-only when necessary.
+ The value cell holds the symbol's value as a variable
+(@pxref{Variables}). That is what you get if you evaluate the symbol as
+a Lisp expression (@pxref{Evaluation}). Any Lisp object is a legitimate
+value. Certain symbols have values that cannot be changed; these
+include @code{nil} and @code{t}, and any symbol whose name starts with
+@samp{:} (those are called @dfn{keywords}). @xref{Constant Variables}.
+
+ We often refer to ``the function @code{foo}'' when we really mean
+the function stored in the function cell of the symbol @code{foo}. We
+make the distinction explicit only when necessary. In normal
+usage, the function cell usually contains a function
+(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the
+Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard
+macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and
+autoload objects (@pxref{Autoloading}) are also sometimes stored in
+the function cells of symbols.
The property list cell normally should hold a correctly formatted
property list (@pxref{Property Lists}), as a number of functions expect
The function cell or the value cell may be @dfn{void}, which means
that the cell does not reference any object. (This is not the same
thing as holding the symbol @code{void}, nor the same as holding the
-symbol @code{nil}.) Examining a cell which is void results in an error,
-such as @samp{Symbol's value as variable is void}.
+symbol @code{nil}.) Examining a function or value cell that is void
+results in an error, such as @samp{Symbol's value as variable is void}.
The four functions @code{symbol-name}, @code{symbol-value},
@code{symbol-plist}, and @code{symbol-function} return the contents of
@result{} "buffer-file-name"
(symbol-value 'buffer-file-name)
@result{} "/gnu/elisp/symbols.texi"
-(symbol-plist 'buffer-file-name)
- @result{} (variable-documentation 29529)
(symbol-function 'buffer-file-name)
@result{} #<subr buffer-file-name>
+(symbol-plist 'buffer-file-name)
+ @result{} (variable-documentation 29529)
@end example
@noindent
The property list cell contains the list @code{(variable-documentation
29529)} which tells the documentation functions where to find the
documentation string for the variable @code{buffer-file-name} in the
-@file{DOC} file. (29529 is the offset from the beginning of the
-@file{DOC} file to where that documentation string begins.) The
-function cell contains the function for returning the name of the file.
+@file{DOC-@var{version}} file. (29529 is the offset from the beginning
+of the @file{DOC-@var{version}} file to where that documentation string
+begins---see @ref{Documentation Basics}.) The function cell contains
+the function for returning the name of the file.
@code{buffer-file-name} names a primitive function, which has no read
syntax and prints in hash notation (@pxref{Primitive Function Type}). A
symbol naming a function written in Lisp would have a lambda expression
@code{defvar} and @code{defconst} are special forms that define a
symbol as a global variable. They are documented in detail in
-@ref{Defining Variables}.
+@ref{Defining Variables}. For defining user option variables that can
+be customized, use @code{defcustom} (@pxref{Customization}).
@code{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 @code{defun} gives the symbol its
-definition as a function.) @xref{Functions}.
+definition as a function.) @code{defsubst} and @code{defalias} are two
+other ways of defining a function. @xref{Functions}.
@code{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
that cell can hold only one Lisp object at any given time.
@xref{Macros}.
- In GNU 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
+ 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 @code{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
@emph{intended} to be used as variables, or as functions. In addition,
utilities such as @file{etags} and @file{make-docfile} recognize
definitions, and add appropriate information to tag tables and the
-@file{emacs/etc/DOC-@var{version}} file. @xref{Accessing Documentation}.
+@file{DOC-@var{version}} file. @xref{Accessing Documentation}.
@node Creating Symbols, Property Lists, Definitions, Symbols
@section Creating and Interning Symbols
and go from there. That is a simple version of hashing. Each element
of the obarray is a @dfn{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.
+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 @ref{Hash Tables}.)
@cindex interning
- If a symbol with the desired name is found, then it is used. If no
-such symbol is found, then a new symbol is created and added to the
-obarray bucket. Adding a symbol to an obarray is called @dfn{interning}
-it, and the symbol is then called an @dfn{interned symbol}.
+ 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 @dfn{interning} it, and the
+symbol is then called an @dfn{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 @kbd{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.
@cindex symbol equality
@cindex uninterned symbol
- If a symbol is not in the obarray, then there is no way for Lisp to
-find it when its name is read. Such a symbol is called an
-@dfn{uninterned symbol} relative to the obarray. An uninterned symbol
-has all the other characteristics of interned symbols; it has the same
-four cells and they work in the usual way.
+ No obarray contains all symbols; in fact, some symbols are not in any
+obarray. They are called @dfn{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
find all the symbols in an obarray except using @code{mapatoms} (below).
The order of symbols in a bucket is not significant.
- In an empty obarray, every element is 0, and you can create an obarray
+ In an empty obarray, every element is 0, so you can create an obarray
with @code{(make-vector @var{length} 0)}. @strong{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
@strong{Do not try to put symbols in an obarray yourself.} This does
not work---only @code{intern} can enter a symbol in an obarray properly.
-@strong{Do not try to intern one symbol in two obarrays.} This would
-garble both obarrays, because a symbol has just one slot to hold the
-following symbol in the obarray bucket. The results would be
-unpredictable.
-
- It is possible for two different symbols to have the same name in
-different obarrays; these symbols are not @code{eq} or @code{equal}.
-However, this normally happens only as part of the abbrev mechanism
-(@pxref{Abbrevs}).
@cindex CL note---symbol in obarrays
@quotation
-@b{Common Lisp note:} in Common Lisp, a single symbol may be interned in
+@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
several obarrays.
@end quotation
@end group
@end example
-Changing the string by substituting characters, etc, does change the
-name of the symbol, but fails to update the obarray, so don't do it!
+@strong{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!
@end defun
@defun make-symbol name
(setq sym1 (intern "foo" other-obarray))
@result{} foo
-(eq sym 'foo)
+(eq sym1 'foo)
@result{} nil
@end example
@end defun
+@cindex CL note---interning existing symbol
+@quotation
+@b{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 @code{intern} must be a string, not a symbol.
+@end quotation
+
@defun intern-soft name &optional obarray
This function returns the symbol in @var{obarray} whose name is
@var{name}, or @code{nil} if @var{obarray} has no symbol with that name.
a given name is already interned. If @var{obarray} is omitted, the
value of the global variable @code{obarray} is used.
+The argument @var{name} may also be a symbol; in that case,
+the function returns @var{name} if @var{name} is interned
+in the specified obarray, and otherwise @code{nil}.
+
@smallexample
(intern-soft "frazzle") ; @r{No such symbol exists.}
@result{} nil
(make-symbol "frazzle") ; @r{Create an uninterned one.}
@result{} frazzle
+@group
(intern-soft "frazzle") ; @r{That one cannot be found.}
@result{} nil
+@end group
+@group
(setq sym (intern "frazzle")) ; @r{Create an interned one.}
@result{} frazzle
+@end group
+@group
(intern-soft "frazzle") ; @r{That one can be found!}
@result{} frazzle
+@end group
@group
(eq sym 'frazzle) ; @r{And it is the same one.}
@result{} t
@end defvar
@defun mapatoms function &optional obarray
-This function call @var{function} for each symbol in the obarray
-@var{obarray}. It returns @code{nil}. If @var{obarray} is omitted, it
-defaults to the value of @code{obarray}, the standard obarray for
-ordinary symbols.
+@anchor{Definition of mapatoms}
+This function calls @var{function} once with each symbol in the obarray
+@var{obarray}. Then it returns @code{nil}. If @var{obarray} is
+omitted, it defaults to the value of @code{obarray}, the standard
+obarray for ordinary symbols.
@smallexample
(setq count 0)
example using @code{mapatoms}.
@end defun
+@defun unintern symbol &optional obarray
+This function deletes @var{symbol} from the obarray @var{obarray}. If
+@code{symbol} is not actually in the obarray, @code{unintern} does
+nothing. If @var{obarray} is @code{nil}, the current obarray is used.
+
+If you provide a string instead of a symbol as @var{symbol}, it stands
+for a symbol name. Then @code{unintern} deletes the symbol (if any) in
+the obarray which has that name. If there is no such symbol,
+@code{unintern} does nothing.
+
+If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise
+it returns @code{nil}.
+@end defun
+
@node Property Lists,, Creating Symbols, Symbols
@section Property Lists
@cindex property list
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 how to compile it, 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.
+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.
@xref{Text Properties}.
The property names and values in a property list can be any Lisp
-objects, but the names are usually symbols. They are compared using
-@code{eq}. Here is an example of a property list, found on the symbol
-@code{progn} when the compiler is loaded:
+objects, but the names are usually symbols. Property list functions
+compare the property names using @code{eq}. Here is an example of a
+property list, found on the symbol @code{progn} when the compiler is
+loaded:
@example
(lisp-indent-function 0 byte-compile byte-compile-progn)
Here @code{lisp-indent-function} and @code{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.
+@end menu
+
+@node Plists and Alists
+@subsection Property Lists and Association Lists
+
@cindex property lists vs association lists
Association lists (@pxref{Association Lists}) are very similar to
property lists. In contrast to association lists, the order of the
must be distinct.
Property lists are better than association lists for attaching
-information to various Lisp function names or variables. If all the
-associations are recorded in one association list, the program will need
-to search that entire list each time a function or variable is to be
-operated on. By contrast, if the information is recorded 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 @code{variable-documentation}. The byte compiler
-likewise uses properties to record those functions needing special
-treatment.
+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 @code{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
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 including the name of the library in the property
-name.) 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.
+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.
+
+@node Symbol Plists
+@subsection Property List Functions for Symbols
@defun symbol-plist symbol
This function returns the property list of @var{symbol}.
@end defun
@defun setplist symbol plist
- This function sets @var{symbol}'s property list to @var{plist}.
+This function sets @var{symbol}'s property list to @var{plist}.
Normally, @var{plist} should be a well-formed property list, but this is
-not enforced.
+not enforced. The return value is @var{plist}.
@smallexample
(setplist 'foo '(a 1 b (2 3) c nil))
@result{} (verb transitive noun (a buzzing little bug))
@end smallexample
@end defun
+
+@node Other Plists
+@subsection Property Lists Outside Symbols
+
+ These functions are useful for manipulating property lists
+that are stored in places other than symbols:
+
+@defun plist-get plist property
+This returns the value of the @var{property} property
+stored in the property list @var{plist}. For example,
+
+@example
+(plist-get '(foo 4) 'foo)
+ @result{} 4
+(plist-get '(foo 4 bad) 'foo)
+ @result{} 4
+(plist-get '(foo 4 bad) 'bar)
+ @result{} @code{wrong-type-argument} error
+@end example
+
+It accepts a malformed @var{plist} argument and always returns @code{nil}
+if @var{property} is not found in the @var{plist}. For example,
+
+@example
+(plist-get '(foo 4 bad) 'bar)
+ @result{} nil
+@end example
+@end defun
+
+@defun plist-put plist property value
+This stores @var{value} as the value of the @var{property} property in
+the property list @var{plist}. It may modify @var{plist} destructively,
+or it may construct a new list structure without altering the old. The
+function returns the modified property list, so you can store that back
+in the place where you got @var{plist}. For example,
+
+@example
+(setq my-plist '(bar t foo 4))
+ @result{} (bar t foo 4)
+(setq my-plist (plist-put my-plist 'foo 69))
+ @result{} (bar t foo 69)
+(setq my-plist (plist-put my-plist 'quux '(a)))
+ @result{} (bar t foo 69 quux (a))
+@end example
+@end defun
+
+ You could define @code{put} in terms of @code{plist-put} as follows:
+
+@example
+(defun put (symbol prop value)
+ (setplist symbol
+ (plist-put (symbol-plist symbol) prop value)))
+@end example
+
+@defun lax-plist-get plist property
+Like @code{plist-get} except that it compares properties
+using @code{equal} instead of @code{eq}.
+@end defun
+
+@defun lax-plist-put plist property value
+Like @code{plist-put} except that it compares properties
+using @code{equal} instead of @code{eq}.
+@end defun
+
+@defun plist-member plist property
+@tindex plist-member
+This returns non-@code{nil} if @var{plist} contains the given
+@var{property}. Unlike @code{plist-get}, this allows you to distinguish
+between a missing property and a property with the value @code{nil}.
+The value is actually the tail of @var{plist} whose @code{car} is
+@var{property}.
+@end defun
+
+@ignore
+ arch-tag: 8750b7d2-de4c-4923-809a-d35fc39fd8ce
+@end ignore
HCoop / bpt / emacs.git / blobdiff