@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
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,
+symbol @code{nil}.) Examining a 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},
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
through all the symbols in the bucket for that name's hash code.
@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.
@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.
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
@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
@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
+This function calls @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.
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}.
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
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.
@result{} (verb transitive noun (a buzzing little bug))
@end smallexample
@end defun
+
+@node Other Plists
+@subsection Property Lists Outside Symbols
+
+ These two 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
+@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{} (quux (a) bar t foo 5)
+@end example
+@end defun
+