comparison lispref/symbols.texi @ 88155:d7ddb3e565de

sync with trunk

88154:8ce476d3ba36

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@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, Hash Tables, Top
@chapter Symbols
@cindex symbol

@example
(symbol-name 'buffer-file-name)
     @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>
@end example

@noindent
Because this symbol is the variable which holds the name of the file
being visited in the current buffer, the value cell contents we see are

This variable is the standard obarray for use by @code{intern} and
@code{read}.
@end defvar

@defun mapatoms function &optional obarray
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.

@end defun

@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.

@smallexample
(setplist 'foo '(a 1 b (2 3) c nil))
     @result{} (a 1 b (2 3) c nil)
(symbol-plist 'foo)

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

@example
(defun put (symbol prop value)
  (setplist symbol
            (plist-put (symbol-plist symbol) prop value)))
@end example

@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

88155:d7ddb3e565de

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
@c   2004, 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/symbols
@node Symbols, Evaluation, Hash Tables, Top
@chapter Symbols
@cindex symbol

@example
(symbol-name 'buffer-file-name)
     @result{} "buffer-file-name"
(symbol-value 'buffer-file-name)
     @result{} "/gnu/elisp/symbols.texi"
(symbol-function 'buffer-file-name)
     @result{} #<subr buffer-file-name>
(symbol-plist 'buffer-file-name)
     @result{} (variable-documentation 29529)
@end example

@noindent
Because this symbol is the variable which holds the name of the file
being visited in the current buffer, the value cell contents we see are

This variable is the standard obarray for use by @code{intern} and
@code{read}.
@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
obarray for ordinary symbols.

@end defun

@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.  The return value is @var{plist}.

@smallexample
(setplist 'foo '(a 1 b (2 3) c nil))
     @result{} (a 1 b (2 3) c nil)
(symbol-plist 'foo)

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

@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