@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, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007 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
@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
documentation string for the variable @code{buffer-file-name} in the
@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---@pxref{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 (or a byte-code object)
-in this cell.
+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
+(or a byte-code object) in this cell.
@node Definitions, Creating Symbols, Symbol Components, Symbols
@section Defining Symbols
-@cindex definition of a symbol
+@cindex definitions of symbols
A @dfn{definition} in Lisp is a special form that announces your
intention to use a certain symbol in a particular way. In Emacs Lisp,
@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
+(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.) @code{defsubst} and @code{defalias} are two
other ways of defining a function. @xref{Functions}.
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
@end defvar
@defun mapatoms function &optional obarray
+@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
@node Plists and Alists
@subsection Property Lists and Association Lists
+@cindex plist vs. alist
+@cindex alist vs. plist
@cindex property lists vs association lists
Association lists (@pxref{Association Lists}) are very similar to
@defun setplist symbol 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))
@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
@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
(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
+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