--- /dev/null
+@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 See the file lispref.texi for copying conditions.
+@setfilename ../../info/symbols.info
+@node Symbols, Evaluation, Sequences Arrays Vectors, Top
+@chapter Symbols
+@cindex symbol
+
+ A @dfn{symbol} is an object with a unique name. This chapter
+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 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}:
+
+@defun symbolp object
+This function returns @code{t} if @var{object} is a symbol, @code{nil}
+otherwise.
+@end defun
+
+@menu
+* Symbol Components:: Symbols have names, values, function definitions
+ and property lists.
+* Definitions:: A definition says how a symbol will be used.
+* Creating Symbols:: How symbols are kept unique.
+* Symbol Properties:: Each symbol has a property list
+ for recording miscellaneous information.
+@end menu
+
+@node Symbol Components
+@section Symbol Components
+@cindex symbol components
+
+ Each symbol has four components (or ``cells''), each of which
+references another object:
+
+@table @asis
+@item Print name
+@cindex print name cell
+The @dfn{print name cell} holds a string that names the symbol for
+reading and printing. See @code{symbol-name} in @ref{Creating Symbols}.
+
+@item Value
+@cindex value cell
+The @dfn{value cell} holds the current value of the symbol as a
+variable. When a symbol is used as a form, the value of the form is the
+contents of the symbol's value cell. See @code{symbol-value} in
+@ref{Accessing Variables}.
+
+@item Function
+@cindex function cell
+The @dfn{function cell} holds the function definition of the symbol.
+When a symbol is used as a function, its function definition is used in
+its place. This cell is also used to make a symbol stand for a keymap
+or a keyboard macro, for editor command execution. Because each symbol
+has separate value and function cells, variables and function names do
+not conflict. See @code{symbol-function} in @ref{Function Cells}.
+
+@item Property list
+@cindex property list cell (symbol)
+The @dfn{property list cell} holds the property list of the symbol. See
+@code{symbol-plist} in @ref{Symbol Properties}.
+@end table
+
+ The print name cell always holds a string, and cannot be changed. The
+other three cells can be set individually to any specified Lisp object.
+
+ The print name cell holds the string that is the name of the symbol.
+Since symbols are represented textually by their names, it is important
+not to have two symbols with the same name. The Lisp reader ensures
+this: every time it reads a symbol, it looks for an existing symbol with
+the specified name before it creates a new one. (In XEmacs Lisp,
+this lookup uses a hashing algorithm and an obarray; see @ref{Creating
+Symbols}.)
+
+ In normal usage, the function cell usually contains a function or
+macro, as that is what the Lisp interpreter expects to see there
+(@pxref{Evaluation}). Keyboard macros (@pxref{Keyboard Macros}),
+keymaps (@pxref{Keymaps}) and autoload objects (@pxref{Autoloading}) are
+also sometimes stored in the function cell of symbols. We often refer
+to ``the function @code{foo}'' when we really mean the function stored
+in the function cell of the symbol @code{foo}. We make the distinction
+only when necessary.
+
+ The property list cell normally should hold a correctly formatted
+property list (@pxref{Property Lists}), as a number of functions expect
+to see a property list there.
+
+ The function cell or the value cell may be @dfn{void}, which means
+that the cell does not reference any object. (This is not the same
+thing as holding the symbol @code{void}, nor the same as holding the
+symbol @code{nil}.) Examining a cell that is void results in an error,
+such as @samp{Symbol's value as variable is void}.
+
+ The four functions @code{symbol-name}, @code{symbol-value},
+@code{symbol-plist}, and @code{symbol-function} return the contents of
+the four cells of a symbol. Here as an example we show the contents of
+the four cells of the symbol @code{buffer-file-name}:
+
+@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
+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
+@file{DOC} file. (29529 is the offset from the beginning of the
+@file{DOC} file to where that documentation string begins.) The
+function cell contains the function for returning the name of the file.
+@code{buffer-file-name} names a primitive function, which has no read
+syntax and prints in hash notation (@pxref{Primitive Function Type}). A
+symbol naming a function written in Lisp would have a lambda expression
+(or a byte-code object) in this cell.
+
+@node Definitions
+@section Defining Symbols
+@cindex definition of a symbol
+
+ 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,
+you can define a symbol as a variable, or define it as a function (or
+macro), or both independently.
+
+ A definition construct typically specifies a value or meaning for the
+symbol for one kind of use, plus documentation for its meaning when used
+in this way. Thus, when you define a symbol as a variable, you can
+supply an initial value for the variable, plus documentation for the
+variable.
+
+ @code{defvar} and @code{defconst} are special forms that define a
+symbol as a global variable. They are documented in detail in
+@ref{Defining Variables}.
+
+ @code{defun} defines a symbol as a function, creating a lambda
+expression and storing it in the function cell of the symbol. This
+lambda expression thus becomes the function definition of the symbol.
+(The term ``function definition'', meaning the contents of the function
+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 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
+given symbol can be a macro or a function, but not both at once, because
+both macro and function definitions are kept in the function cell, and
+that cell can hold only one Lisp object at any given time.
+@xref{Macros}.
+
+ 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
+variable with @code{setq}, whether you define it first or not. The real
+purpose of definitions is to guide programmers and programming tools.
+They inform programmers who read the code that certain symbols are
+@emph{intended} to be used as variables, or as functions. In addition,
+utilities such as @file{etags} and @file{make-docfile} recognize
+definitions, and add appropriate information to tag tables and the
+@file{DOC} file. @xref{Accessing Documentation}.
+
+@node Creating Symbols
+@section Creating and Interning Symbols
+@cindex reading symbols
+
+ 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
+every time it reads the same set of characters. Failure to do so would
+cause complete confusion.
+
+@cindex symbol name hashing
+@cindex hashing
+@cindex obarray
+@cindex bucket (in obarray)
+ When the Lisp reader encounters a symbol, it reads all the characters
+of the name. Then it ``hashes'' those characters to find an index in a
+table called an @dfn{obarray}. Hashing is an efficient method of
+looking something up. For example, instead of searching a telephone
+book cover to cover when looking up Jan Jones, you start with the J's
+and go from there. That is a simple version of hashing. Each element
+of the obarray is a @dfn{bucket} which holds all the symbols with a
+given hash code; to look for a given name, it is sufficient to look
+through all the symbols in the bucket for that name's hash code.
+
+@cindex interning
+ If a symbol with the desired name is found, the reader uses that
+symbol. If the obarray does not contain a symbol with that name, the
+reader makes a new symbol and adds it to the obarray. Finding or adding
+a symbol with a certain name is called @dfn{interning} it, and the
+symbol is then called an @dfn{interned symbol}.
+
+ Interning ensures that each obarray has just one symbol with any
+particular name. Other like-named symbols may exist, but not in the
+same obarray. Thus, the reader gets the same symbols for the same
+names, as long as you keep reading with the same obarray.
+
+@cindex symbol equality
+@cindex uninterned symbol
+ No obarray contains all symbols; in fact, some symbols are not in any
+obarray. They are called @dfn{uninterned symbols}. An uninterned
+symbol has the same four cells as other symbols; however, the only way
+to gain access to it is by finding it in some other object or as the
+value of a variable.
+
+ In XEmacs Lisp, an obarray is actually a vector. Each element of the
+vector is a bucket; its value is either an interned symbol whose name
+hashes to that bucket, or 0 if the bucket is empty. Each interned
+symbol has an internal link (invisible to the user) to the next symbol
+in the bucket. Because these links are invisible, there is no way to
+find all the symbols in an obarray except using @code{mapatoms} (below).
+The order of symbols in a bucket is not significant.
+
+ In an empty obarray, every element is 0, and you can create an obarray
+with @code{(make-vector @var{length} 0)}. @strong{This is the only
+valid way to create an obarray.} Prime numbers as lengths tend
+to result in good hashing; lengths one less than a power of two are also
+good.
+
+ @strong{Do not try to put symbols in an obarray yourself.} This does
+not work---only @code{intern} can enter a symbol in an obarray properly.
+@strong{Do not try to intern one symbol in two obarrays.} This would
+garble both obarrays, because a symbol has just one slot to hold the
+following symbol in the obarray bucket. The results would be
+unpredictable.
+
+ It is possible for two different symbols to have the same name in
+different obarrays; these symbols are not @code{eq} or @code{equal}.
+However, this normally happens only as part of the abbrev mechanism
+(@pxref{Abbrevs}).
+
+@cindex CL note---symbol in obarrays
+@quotation
+@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
+several obarrays.
+@end quotation
+
+ Most of the functions below take a name and sometimes an obarray as
+arguments. A @code{wrong-type-argument} error is signaled if the name
+is not a string, or if the obarray is not a vector.
+
+@defun symbol-name symbol
+This function returns the string that is @var{symbol}'s name. For example:
+
+@example
+@group
+(symbol-name 'foo)
+ @result{} "foo"
+@end group
+@end example
+
+Changing the string by substituting characters, etc, does change the
+name of the symbol, but fails to update the obarray, so don't do it!
+@end defun
+
+@defun make-symbol name
+This function returns a newly-allocated, uninterned symbol whose name is
+@var{name} (which must be a string). Its value and function definition
+are void, and its property list is @code{nil}. In the example below,
+the value of @code{sym} is not @code{eq} to @code{foo} because it is a
+distinct uninterned symbol whose name is also @samp{foo}.
+
+@example
+(setq sym (make-symbol "foo"))
+ @result{} foo
+(eq sym 'foo)
+ @result{} nil
+@end example
+@end defun
+
+@defun intern name &optional obarray
+This function returns the interned symbol whose name is @var{name}. If
+there is no such symbol in the obarray @var{obarray}, @code{intern}
+creates a new one, adds it to the obarray, and returns it. If
+@var{obarray} is omitted, the value of the global variable
+@code{obarray} is used.
+
+@example
+(setq sym (intern "foo"))
+ @result{} foo
+(eq sym 'foo)
+ @result{} t
+
+(setq sym1 (intern "foo" other-obarray))
+ @result{} foo
+(eq sym 'foo)
+ @result{} nil
+@end example
+@end defun
+
+@defun intern-soft name &optional obarray
+This function returns the symbol in @var{obarray} whose name is
+@var{name}, or @code{nil} if @var{obarray} has no symbol with that name.
+Therefore, you can use @code{intern-soft} to test whether a symbol with
+a given name is already interned. If @var{obarray} is omitted, the
+value of the global variable @code{obarray} is used.
+
+@smallexample
+(intern-soft "frazzle") ; @r{No such symbol exists.}
+ @result{} nil
+(make-symbol "frazzle") ; @r{Create an uninterned one.}
+ @result{} frazzle
+@group
+(intern-soft "frazzle") ; @r{That one cannot be found.}
+ @result{} nil
+@end group
+@group
+(setq sym (intern "frazzle")) ; @r{Create an interned one.}
+ @result{} frazzle
+@end group
+@group
+(intern-soft "frazzle") ; @r{That one can be found!}
+ @result{} frazzle
+@end group
+@group
+(eq sym 'frazzle) ; @r{And it is the same one.}
+ @result{} t
+@end group
+@end smallexample
+@end defun
+
+@defvar obarray
+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} for each symbol in the obarray
+@var{obarray}. It returns @code{nil}. If @var{obarray} is omitted, it
+defaults to the value of @code{obarray}, the standard obarray for
+ordinary symbols.
+
+@smallexample
+(setq count 0)
+ @result{} 0
+(defun count-syms (s)
+ (setq count (1+ count)))
+ @result{} count-syms
+(mapatoms 'count-syms)
+ @result{} nil
+count
+ @result{} 1871
+@end smallexample
+
+See @code{documentation} in @ref{Accessing Documentation}, for another
+example using @code{mapatoms}.
+@end defun
+
+@defun unintern symbol &optional obarray
+This function deletes @var{symbol} from the obarray @var{obarray}. If
+@code{symbol} is not actually in the obarray, @code{unintern} does
+nothing. If @var{obarray} is @code{nil}, the current obarray is used.
+
+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
+the obarray which has that name. If there is no such symbol,
+@code{unintern} does nothing.
+
+If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise
+it returns @code{nil}.
+@end defun
+
+@node Symbol Properties
+@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
+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.
+
+ 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
+@code{eq}. Here is an example of a property list, found on the symbol
+@code{progn} when the compiler is loaded:
+
+@example
+(lisp-indent-function 0 byte-compile byte-compile-progn)
+@end example
+
+@noindent
+Here @code{lisp-indent-function} and @code{byte-compile} are property
+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.
+* Other Plists:: Accessing property lists stored elsewhere.
+@end menu
+
+@node Plists and Alists
+@subsection Property Lists and Association Lists
+
+@cindex property lists vs association lists
+ Association lists (@pxref{Association Lists}) are very similar to
+property lists. In contrast to association lists, the order of the
+pairs in the property list is not significant since the property names
+must be distinct.
+
+ Property lists are better than association lists for attaching
+information to various Lisp function names or variables. If all the
+associations are recorded in one association list, the program will need
+to search that entire list each time a function or variable is to be
+operated on. By contrast, if the information is recorded in the
+property lists of the function names or variables themselves, each
+search will scan only the length of one property list, which is usually
+short. This is why the documentation for a variable is recorded in a
+property named @code{variable-documentation}. The byte compiler
+likewise uses properties to record those functions needing special
+treatment.
+
+ However, association lists have their own advantages. Depending on
+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
+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
+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
+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
+@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
+not enforced.
+
+@smallexample
+(setplist 'foo '(a 1 b (2 3) c nil))
+ @result{} (a 1 b (2 3) c nil)
+(symbol-plist 'foo)
+ @result{} (a 1 b (2 3) c nil)
+@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
+@code{put} instead. @code{setplist} can only be used with symbols, not
+other object types.
+@end defun
+
+@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,
+@code{default} (which itself defaults to @code{nil}) is returned.
+
+@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 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}.
+
+@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)
+ @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
+
+ These functions are useful for manipulating property lists
+that are stored in places other than symbols:
+
+@defun getf plist property &optional default
+This returns the value of the @var{property} property
+stored in the property list @var{plist}. For example,
+
+@example
+(getf '(foo 4) 'foo)
+ @result{} 4
+@end example
+@end defun
+
+@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
+function returns the modified property list, so you can store that back
+in the place where you got @var{plist}. For example,
+
+@example
+(setq my-plist '(bar t foo 4))
+ @result{} (bar t foo 4)
+(setq my-plist (putf my-plist 'foo 69))
+ @result{} (bar t foo 69)
+(setq my-plist (putf my-plist 'quux '(a)))
+ @result{} (quux (a) bar t foo 5)
+@end example
+@end defmac
+
+@defun plists-eq a b
+This function returns non-@code{nil} if property lists @var{a} and @var{b}
+are @code{eq}. This means that the property lists have the same values
+for all the same properties, where comparison between values is done using
+@code{eq}.
+@end defun
+
+@defun plists-equal a b
+This function returns non-@code{nil} if property lists @var{a} and @var{b}
+are @code{equal}.
+@end defun
+
+Both of the above functions do order-insensitive comparisons.
+
+@example
+(plists-eq '(a 1 b 2 c nil) '(b 2 a 1))
+ @result{} t
+(plists-eq '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
+ @result{} nil
+(plists-equal '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
+ @result{} t
+@end example
+
+
+
projects / chise / xemacs-chise.git- / blobdiff