xemacs-beta: man/lispref/symbols.texi comparison

comparison man/lispref/symbols.texi @ 412:697ef44129c6 r21-2-14

Import from CVS: tag r21-2-14

author	cvs
date	Mon, 13 Aug 2007 11:20:41 +0200
parents	74fd4e045ea6
children

comparison

equal deleted inserted replaced

-:12e008d41344
+:697ef44129c6
 @section Symbol Properties
 @cindex property list, symbol
 @cindex plist, symbol
 A @dfn{property list} (@dfn{plist} for short) is a list of paired
-elements, often stored in the property list cell of a symbol.  Each of
+elements stored in the property list cell of a symbol.  Each of the
-the pairs associates a property name (usually a symbol) with a property
+pairs associates a property name (usually a symbol) with a property or
-or value.  Property lists are generally used to record information about
+value.  Property lists are generally used to record information about a
-a symbol, such as its documentation as a variable, the name of the file
+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.
-Some objects which are not symbols also have property lists associated
+Many objects other than symbols can have property lists associated
 with them, and XEmacs provides a full complement of functions for
 working with property lists.  @xref{Property Lists}.
 The property names and values in a property list can be any Lisp
 objects, but the names are usually symbols.  They are compared using
 names, and the other two elements are the corresponding values.
 @menu
 * Plists and Alists::           Comparison of the advantages of property
 lists and association lists.
-* Object Plists::               Functions to access objects' property 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
 unique, such as by including the name of the library in the property
 name.)  An association list may be used like a stack where associations
 are pushed on the front of the list and later discarded; this is not
 possible with a property list.
-@node Object Plists
+@node Symbol Plists
-@subsection Property List Functions for Objects
+@subsection Property List Functions for Symbols
-Once upon a time, only symbols had property lists.  Now, several other
-object types, including strings, extents, faces and glyphs also have
-property lists.
 @defun symbol-plist symbol
 This function returns the property list of @var{symbol}.
-@end defun
-@defun object-plist object
-This function returns the property list of @var{object}.  If
-@var{object} is a symbol, this is identical to @code{symbol-plist}.
 @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
 @end smallexample
 For symbols in special obarrays, which are not used for ordinary
 purposes, it may make sense to use the property list cell in a
 nonstandard fashion; in fact, the abbrev mechanism does so
-(@pxref{Abbrevs}).  But generally, its use is discouraged.  Use
+(@pxref{Abbrevs}).
-@code{put} instead.  @code{setplist} can only be used with symbols, not
+@end defun
-other object types.
-@end defun
+@defun get symbol property
-@defun get object property &optional default
 This function finds the value of the property named @var{property} in
-@var{object}'s property list.  If there is no such property,
+@var{symbol}'s property list.  If there is no such property, @code{nil}
-@code{default} (which itself defaults to @code{nil}) is returned.
+is returned.  Thus, there is no distinction between a value of
+@code{nil} and the absence of the property.
-@var{property} is compared with the existing properties using @code{eq},
-so any object is a legitimate property.
+The name @var{property} is compared with the existing property names
+using @code{eq}, so any object is a legitimate property.
 See @code{put} for an example.
 @end defun
-@defun put object property value
+@defun put symbol property value
-This function puts @var{value} onto @var{object}'s property list under
+This function puts @var{value} onto @var{symbol}'s property list under
 the property name @var{property}, replacing any previous property value.
 The @code{put} function returns @var{value}.
 @smallexample
 (put 'fly 'verb 'transitive)
 @result{}'transitive
 (put 'fly 'noun '(a buzzing little bug))
 @result{} (a buzzing little bug)
 (get 'fly 'verb)
 @result{} transitive
-(object-plist 'fly)
+(symbol-plist 'fly)
 @result{} (verb transitive noun (a buzzing little bug))
 @end smallexample
 @end defun
-@defun remprop object property
-This function removes the entry for @var{property} from the property
-list of @var{object}.  It returns @code{t} if the property was
-indeed found and removed, or @code{nil} if there was no such property.
-(This function was probably omitted from Emacs originally because,
-since @code{get} did not allow a @var{default}, it was very difficult
-to distinguish between a missing property and a property whose value
-was @code{nil}; thus, setting a property to @code{nil} was close
-enough to @code{remprop} for most purposes.)
-@end defun
 @node Other Plists
-@subsection Property Lists Not Associated with Objects
+@subsection Property Lists Outside Symbols
 These functions are useful for manipulating property lists
 that are stored in places other than symbols:
 @defun getf plist property &optional default

Mercurial > hg > xemacs-beta

comparison man/lispref/symbols.texi @ 412:697ef44129c6 r21-2-14