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

comparison man/lispref/symbols.texi @ 442:abe6d1db359e r21-2-36

Import from CVS: tag r21-2-36

author	cvs
date	Mon, 13 Aug 2007 11:35:02 +0200
parents	3ecd8885ac67
children	576fb035e263

comparison

equal deleted inserted replaced

-:72a7cfa4a488
+:abe6d1db359e
 @section Symbol Properties
 @cindex property list, symbol
 @cindex plist, symbol
 A @dfn{property list} (@dfn{plist} for short) is a list of paired
-elements stored in the property list cell of a symbol.  Each of the
+elements, often stored in the property list cell of a symbol.  Each of
-pairs associates a property name (usually a symbol) with a property or
+the pairs associates a property name (usually a symbol) with a property
-value.  Property lists are generally used to record information about a
+or value.  Property lists are generally used to record information about
-symbol, such as its documentation as a variable, the name of the file
+a 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.
-Many objects other than symbols can have property lists associated
+Some objects which are not symbols also 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.
-* Symbol Plists::               Functions to access symbols' property lists.
+* Object Plists::               Functions to access objects' 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 Symbol Plists
+@node Object Plists
-@subsection Property List Functions for Symbols
+@subsection Property List Functions for Objects
+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}).
+(@pxref{Abbrevs}).  But generally, its use is discouraged.  Use
-@end defun
+@code{put} instead.  @code{setplist} can only be used with symbols, not
+other object types.
-@defun get symbol property
+@end defun
+@defun get object property &optional default
 This function finds the value of the property named @var{property} in
-@var{symbol}'s property list.  If there is no such property, @code{nil}
+@var{object}'s property list.  If there is no such property,
-is returned.  Thus, there is no distinction between a value of
+@code{default} (which itself defaults to @code{nil}) is returned.
-@code{nil} and the absence of the property.
+@var{property} is compared with the existing properties using @code{eq},
-The name @var{property} is compared with the existing property names
+so any object is a legitimate property.
-using @code{eq}, so any object is a legitimate property.
 See @code{put} for an example.
 @end defun
-@defun put symbol property value
+@defun put object property value
-This function puts @var{value} onto @var{symbol}'s property list under
+This function puts @var{value} onto @var{object}'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
-(symbol-plist 'fly)
+(object-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 Outside Symbols
+@subsection Property Lists Not Associated with Objects
 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 @ 442:abe6d1db359e r21-2-36