@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, 2002, 2003,
+@c 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/symbols
@node Symbols, Evaluation, Hash Tables, Top
include @code{nil} and @code{t}, and any symbol whose name starts with
@samp{:} (those are called @dfn{keywords}). @xref{Constant Variables}.
- In normal usage, the function cell usually contains a function
+ 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
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
@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
+@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