@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@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
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
+ 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. 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.
+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
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, the reader uses that
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
No obarray contains all symbols; in fact, some symbols are not in any
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
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
(setq sym1 (intern "foo" other-obarray))
@result{} foo
-(eq sym 'foo)
+(eq sym1 'foo)
@result{} nil
@end example
@end defun
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
@node Other Plists
@subsection Property Lists Outside Symbols
- These two functions are useful for manipulating property lists
+ These functions are useful for manipulating property lists
that are stored in places other than symbols:
@defun plist-get plist property
(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