"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "man/lispref/symbols.texi" between
xemacs-21.4.22.tar.gz and xemacs-21.4.24.tar.bz2

About: XEmacs (an alternative to GNU Emacs) is a highly customizable open source text editor and application development system (current version).

symbols.texi  (xemacs-21.4.22):symbols.texi  (xemacs-21.4.24.tar.bz2)
skipping to change at line 34 skipping to change at line 34
@menu @menu
* Symbol Components:: Symbols have names, values, function definitions * Symbol Components:: Symbols have names, values, function definitions
and property lists. and property lists.
* Definitions:: A definition says how a symbol will be used. * Definitions:: A definition says how a symbol will be used.
* Creating Symbols:: How symbols are kept unique. * Creating Symbols:: How symbols are kept unique.
* Symbol Properties:: Each symbol has a property list * Symbol Properties:: Each symbol has a property list
for recording miscellaneous information. for recording miscellaneous information.
@end menu @end menu
@node Symbol Components @node Symbol Components, Definitions, Symbols, Symbols
@section Symbol Components @section Symbol Components
@cindex symbol components @cindex symbol components
Each symbol has four components (or ``cells''), each of which Each symbol has four components (or ``cells''), each of which
references another object: references another object:
@table @asis @table @asis
@item Print name @item Print name
@cindex print name cell @cindex print name cell
The @dfn{print name cell} holds a string that names the symbol for The @dfn{print name cell} holds a string that names the symbol for
skipping to change at line 131 skipping to change at line 131
29529)} which tells the documentation functions where to find the 29529)} which tells the documentation functions where to find the
documentation string for the variable @code{buffer-file-name} in the documentation string for the variable @code{buffer-file-name} in the
@file{DOC} file. (29529 is the offset from the beginning of the @file{DOC} file. (29529 is the offset from the beginning of the
@file{DOC} file to where that documentation string begins.) The @file{DOC} file to where that documentation string begins.) The
function cell contains the function for returning the name of the file. function cell contains the function for returning the name of the file.
@code{buffer-file-name} names a primitive function, which has no read @code{buffer-file-name} names a primitive function, which has no read
syntax and prints in hash notation (@pxref{Primitive Function Type}). A syntax and prints in hash notation (@pxref{Primitive Function Type}). A
symbol naming a function written in Lisp would have a lambda expression symbol naming a function written in Lisp would have a lambda expression
(or a byte-code object) in this cell. (or a byte-code object) in this cell.
@node Definitions @node Definitions, Creating Symbols, Symbol Components, Symbols
@section Defining Symbols @section Defining Symbols
@cindex definition of a symbol @cindex definition of a symbol
A @dfn{definition} in Lisp is a special form that announces your A @dfn{definition} in Lisp is a special form that announces your
intention to use a certain symbol in a particular way. In XEmacs Lisp, intention to use a certain symbol in a particular way. In XEmacs Lisp,
you can define a symbol as a variable, or define it as a function (or you can define a symbol as a variable, or define it as a function (or
macro), or both independently. macro), or both independently.
A definition construct typically specifies a value or meaning for the A definition construct typically specifies a value or meaning for the
symbol for one kind of use, plus documentation for its meaning when used symbol for one kind of use, plus documentation for its meaning when used
skipping to change at line 176 skipping to change at line 176
In XEmacs Lisp, a definition is not required in order to use a symbol In XEmacs Lisp, a definition is not required in order to use a symbol
as a variable or function. Thus, you can make a symbol a global as a variable or function. Thus, you can make a symbol a global
variable with @code{setq}, whether you define it first or not. The real variable with @code{setq}, whether you define it first or not. The real
purpose of definitions is to guide programmers and programming tools. purpose of definitions is to guide programmers and programming tools.
They inform programmers who read the code that certain symbols are They inform programmers who read the code that certain symbols are
@emph{intended} to be used as variables, or as functions. In addition, @emph{intended} to be used as variables, or as functions. In addition,
utilities such as @file{etags} and @file{make-docfile} recognize utilities such as @file{etags} and @file{make-docfile} recognize
definitions, and add appropriate information to tag tables and the definitions, and add appropriate information to tag tables and the
@file{DOC} file. @xref{Accessing Documentation}. @file{DOC} file. @xref{Accessing Documentation}.
@node Creating Symbols @node Creating Symbols, Symbol Properties, Definitions, Symbols
@section Creating and Interning Symbols @section Creating and Interning Symbols
@cindex reading symbols @cindex reading symbols
To understand how symbols are created in XEmacs Lisp, you must know To understand how symbols are created in XEmacs Lisp, you must know
how Lisp reads them. Lisp must ensure that it finds the same symbol how Lisp reads them. Lisp must ensure that it finds the same symbol
every time it reads the same set of characters. Failure to do so would every time it reads the same set of characters. Failure to do so would
cause complete confusion. cause complete confusion.
@cindex symbol name hashing @cindex symbol name hashing
@cindex hashing @cindex hashing
skipping to change at line 376 skipping to change at line 376
If you provide a string instead of a symbol as @var{symbol}, it stands If you provide a string instead of a symbol as @var{symbol}, it stands
for a symbol name. Then @code{unintern} deletes the symbol (if any) in for a symbol name. Then @code{unintern} deletes the symbol (if any) in
the obarray which has that name. If there is no such symbol, the obarray which has that name. If there is no such symbol,
@code{unintern} does nothing. @code{unintern} does nothing.
If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise
it returns @code{nil}. it returns @code{nil}.
@end defun @end defun
@node Symbol Properties @node Symbol Properties, , Creating Symbols, Symbols
@section Symbol Properties @section Symbol Properties
@cindex property list, symbol @cindex property list, symbol
@cindex plist, symbol @cindex plist, symbol
A @dfn{property list} (@dfn{plist} for short) is a list of paired 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, often stored in the property list cell of a symbol. Each of
the pairs associates a property name (usually a symbol) with a property the pairs associates a property name (usually a symbol) with a property
or value. Property lists are generally used to record information about 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 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 where it was defined, or perhaps even the grammatical class of the
skipping to change at line 413 skipping to change at line 413
Here @code{lisp-indent-function} and @code{byte-compile} are property Here @code{lisp-indent-function} and @code{byte-compile} are property
names, and the other two elements are the corresponding values. names, and the other two elements are the corresponding values.
@menu @menu
* Plists and Alists:: Comparison of the advantages of property * Plists and Alists:: Comparison of the advantages of property
lists and association lists. lists and association lists.
* Object Plists:: Functions to access objects' property lists. * Object Plists:: Functions to access objects' property lists.
* Other Plists:: Accessing property lists stored elsewhere. * Other Plists:: Accessing property lists stored elsewhere.
@end menu @end menu
@node Plists and Alists @node Plists and Alists, Object Plists, Symbol Properties, Symbol Properties
@subsection Property Lists and Association Lists @subsection Property Lists and Association Lists
@cindex property lists vs association lists @cindex property lists vs association lists
Association lists (@pxref{Association Lists}) are very similar to Association lists (@pxref{Association Lists}) are very similar to
property lists. In contrast to association lists, the order of the property lists. In contrast to association lists, the order of the
pairs in the property list is not significant since the property names pairs in the property list is not significant since the property names
must be distinct. must be distinct.
Property lists are better than association lists for attaching Property lists are better than association lists for attaching
information to various Lisp function names or variables. If all the information to various Lisp function names or variables. If all the
skipping to change at line 445 skipping to change at line 445
your application, it may be faster to add an association to the front of your application, it may be faster to add an association to the front of
an association list than to update a property. All properties for a an association list than to update a property. All properties for a
symbol are stored in the same property list, so there is a possibility symbol are stored in the same property list, so there is a possibility
of a conflict between different uses of a property name. (For this of a conflict between different uses of a property name. (For this
reason, it is a good idea to choose property names that are probably reason, it is a good idea to choose property names that are probably
unique, such as by including the name of the library in the property 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 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 are pushed on the front of the list and later discarded; this is not
possible with a property list. possible with a property list.
@node Object Plists @node Object Plists, Other Plists, Plists and Alists, Symbol Properties
@subsection Property List Functions for Objects @subsection Property List Functions for Objects
Once upon a time, only symbols had property lists. Now, several other Once upon a time, only symbols had property lists. Now, several other
object types, including strings, extents, faces and glyphs also have object types, including strings, extents, faces and glyphs also have
property lists. property lists.
@defun symbol-plist symbol @defun symbol-plist symbol
This function returns the property list of @var{symbol}. This function returns the property list of @var{symbol}.
@end defun @end defun
skipping to change at line 520 skipping to change at line 520
This function removes the entry for @var{property} from the property This function removes the entry for @var{property} from the property
list of @var{object}. It returns @code{t} if the property was 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. indeed found and removed, or @code{nil} if there was no such property.
(This function was probably omitted from Emacs originally because, (This function was probably omitted from Emacs originally because,
since @code{get} did not allow a @var{default}, it was very difficult since @code{get} did not allow a @var{default}, it was very difficult
to distinguish between a missing property and a property whose value to distinguish between a missing property and a property whose value
was @code{nil}; thus, setting a property to @code{nil} was close was @code{nil}; thus, setting a property to @code{nil} was close
enough to @code{remprop} for most purposes.) enough to @code{remprop} for most purposes.)
@end defun @end defun
@node Other Plists @node Other Plists, , Object Plists, Symbol Properties
@subsection Property Lists Not Associated with Objects @subsection Property Lists Not Associated with Objects
These functions are useful for manipulating property lists These functions are useful for manipulating property lists
that are stored in places other than symbols: that are stored in places other than symbols:
@defun getf plist property &optional default @defun getf plist property &optional default
This returns the value of the @var{property} property This returns the value of the @var{property} property
stored in the property list @var{plist}. For example, stored in the property list @var{plist}. For example,
@example @example
 End of changes. 7 change blocks. 
7 lines changed or deleted 7 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)