X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=man%2Flispref%2Fsymbols.texi;h=9fb7a92b7bca67377dff1d86b23d9ff5125919b8;hb=435c8d229de2c717831181791e718f1651a43058;hp=87315d52812b2617af1cde22576c00c20126f888;hpb=6883ee56ec887c2c48abe5b06b5e66aa74031910;p=chise%2Fxemacs-chise.git.1 diff --git a/man/lispref/symbols.texi b/man/lispref/symbols.texi index 87315d5..9fb7a92 100644 --- a/man/lispref/symbols.texi +++ b/man/lispref/symbols.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the XEmacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. @c See the file lispref.texi for copying conditions. @setfilename ../../info/symbols.info @node Symbols, Evaluation, Sequences Arrays Vectors, Top @@ -11,8 +11,8 @@ describes symbols, their components, their property lists, and how they are created and interned. Separate chapters describe the use of symbols as variables and as function names; see @ref{Variables}, and -@ref{Functions}. For the precise read syntax for symbols, see -@ref{Symbol Type}. +@ref{Functions and Commands}. For the precise read syntax for symbols, +see @ref{Symbol Type}. You can test whether an arbitrary Lisp object is a symbol with @code{symbolp}: @@ -115,7 +115,8 @@ the four cells of the symbol @code{buffer-file-name}: @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 -the name of the source file of this chapter of the XEmacs Lisp Manual. +the name of the source file of this chapter of the XEmacs Lisp Reference +Manual. The property list cell contains the list @code{(variable-documentation 29529)} which tells the documentation functions where to find the documentation string for the variable @code{buffer-file-name} in the @@ -153,7 +154,7 @@ lambda expression thus becomes the function definition of the symbol. cell, is derived from the idea that @code{defun} gives the symbol its definition as a function.) @code{defsubst}, @code{define-function} and @code{defalias} are other ways of defining a function. -@xref{Functions}. +@xref{Functions and Commands}. @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 @@ -378,14 +379,14 @@ it returns @code{nil}. @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 -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 its documentation as a variable, the name of the file +elements, often 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 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}. @@ -405,7 +406,7 @@ 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 @@ -441,13 +442,22 @@ 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 -@subsection Property List Functions for Symbols +@node Object Plists +@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 @@ -463,23 +473,24 @@ not enforced. 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 +@code{put} instead. @code{setplist} can only be used with symbols, not +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{symbol}'s property list. If there is no such property, @code{nil} -is returned. Thus, there is no distinction between a value of -@code{nil} and the absence of the property. +@var{object}'s property list. If there is no such property, +@code{default} (which itself defaults to @code{nil}) is returned. -The name @var{property} is compared with the existing property names -using @code{eq}, so any object is a legitimate property. +@var{property} is compared with the existing properties using @code{eq}, +so any object is a legitimate property. See @code{put} for an example. @end defun -@defun put symbol property value -This function puts @var{value} onto @var{symbol}'s property list under +@defun put object property value +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}. @@ -490,13 +501,24 @@ The @code{put} function returns @var{value}. @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: @@ -511,7 +533,7 @@ stored in the property list @var{plist}. For example, @end example @end defun -@defun putf plist property value +@defmac putf 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 @@ -526,7 +548,7 @@ in the place where you got @var{plist}. For example, (setq my-plist (putf my-plist 'quux '(a))) @result{} (quux (a) bar t foo 5) @end example -@end defun +@end defmac @defun plists-eq a b This function returns non-@code{nil} if property lists @var{a} and @var{b}