X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/1621af1ec5b5367ce3c0f47bc71432ab56ee8351..8d892d7fef218001fa8ef828db4a5a864448f950:/lispref/symbols.texi

diff --git a/lispref/symbols.texi b/lispref/symbols.texi
index 39f1bbcb80..9e4b482cfa 100644
--- a/lispref/symbols.texi
+++ b/lispref/symbols.texi
@@ -1,9 +1,10 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
+@c   2004, 2005 Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/symbols
-@node Symbols, Evaluation, Sequences Arrays Vectors, Top
+@node Symbols, Evaluation, Hash Tables, Top
 @chapter Symbols
 @cindex symbol
 
@@ -41,7 +42,7 @@ references another object:
 @table @asis
 @item Print name
 @cindex print name cell
-The @dfn{print name cell} holds a string which names the symbol for
+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
@@ -57,7 +58,7 @@ 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
+has separate value and function cells, variables names and function names do
 not conflict.  See @code{symbol-function} in @ref{Function Cells}.
 
 @item Property list
@@ -77,14 +78,22 @@ the specified name before it creates a new one.  (In GNU Emacs 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 value cell holds the symbol's value as a variable
+(@pxref{Variables}).  That is what you get if you evaluate the symbol as
+a Lisp expression (@pxref{Evaluation}).  Any Lisp object is a legitimate
+value.  Certain symbols have values that cannot be changed; these
+include @code{nil} and @code{t}, and any symbol whose name starts with
+@samp{:} (those are called @dfn{keywords}).  @xref{Constant Variables}.
+
+  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 explicit only when necessary.  In normal
+usage, the function cell usually contains a function
+(@pxref{Functions}) or a macro (@pxref{Macros}), 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 cells of symbols.
 
   The property list cell normally should hold a correctly formatted
 property list (@pxref{Property Lists}), as a number of functions expect
@@ -93,8 +102,8 @@ 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 which is void results in an error,
-such as @samp{Symbol's value as variable is void}.
+symbol @code{nil}.)  Examining a function or value 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
@@ -106,10 +115,10 @@ the four cells of the symbol @code{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>
+(symbol-plist 'buffer-file-name)
+     @result{} (variable-documentation 29529)
 @end example
 
 @noindent
@@ -119,9 +128,10 @@ the name of the source file of this chapter of the Emacs Lisp 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.
+@file{DOC-@var{version}} file.  (29529 is the offset from the beginning
+of the @file{DOC-@var{version}} file to where that documentation string
+begins---see @ref{Documentation Basics}.)  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
@@ -144,14 +154,16 @@ 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}.
+@ref{Defining Variables}.  For defining user option variables that can
+be customized, use @code{defcustom} (@pxref{Customization}).
 
   @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.)  @xref{Functions}.
+definition as a function.)  @code{defsubst} and @code{defalias} are two
+other ways of defining a function.  @xref{Functions}.
 
   @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
@@ -160,15 +172,15 @@ 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 GNU Emacs 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
+  In Emacs 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{emacs/etc/DOC-@var{version}} file. @xref{Accessing Documentation}.
+@file{DOC-@var{version}} file.  @xref{Accessing Documentation}.
 
 @node Creating Symbols, Property Lists, Definitions, Symbols
 @section Creating and Interning Symbols
@@ -191,21 +203,38 @@ 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.
+through all the symbols in the bucket for that name's hash code.  (The
+same idea is used for general Emacs hash tables, but they are a
+different data type; see @ref{Hash Tables}.)
 
 @cindex interning
-  If a symbol with the desired name is found, then it is used.  If no
-such symbol is found, then a new symbol is created and added to the
-obarray bucket.  Adding a symbol to an obarray is called @dfn{interning}
-it, and the symbol is then called an @dfn{interned symbol}.
+  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.
+
+  Interning usually happens automatically in the reader, but sometimes
+other programs need to do it.  For example, after the @kbd{M-x} command
+obtains the command name as a string using the minibuffer, it then
+interns the string, to get the interned symbol with that name.
 
 @cindex symbol equality
 @cindex uninterned symbol
-  If a symbol is not in the obarray, then there is no way for Lisp to
-find it when its name is read.  Such a symbol is called an
-@dfn{uninterned symbol} relative to the obarray.  An uninterned symbol
-has all the other characteristics of interned symbols; it has the same
-four cells and they work in the usual way.
+  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.
+
+  Creating an uninterned symbol is useful in generating Lisp code,
+because an uninterned symbol used as a variable in the code you generate
+cannot clash with any variables used in other Lisp programs.
 
   In Emacs Lisp, an obarray is actually a vector.  Each element of the
 vector is a bucket; its value is either an interned symbol whose name
@@ -215,7 +244,7 @@ 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
+  In an empty obarray, every element is 0, so 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
@@ -223,19 +252,10 @@ 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
+@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
 several obarrays.
 @end quotation
 
@@ -253,8 +273,9 @@ This function returns the string that is @var{symbol}'s name.  For example:
 @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!
+@strong{Warning:} Changing the string by substituting characters does
+change the name of the symbol, but fails to update the obarray, so don't
+do it!
 @end defun
 
 @defun make-symbol name
@@ -287,11 +308,18 @@ creates a new one, adds it to the obarray, and returns it.  If
 
 (setq sym1 (intern "foo" other-obarray))
      @result{} foo
-(eq sym 'foo)
+(eq sym1 'foo)
      @result{} nil
 @end example
 @end defun
 
+@cindex CL note---interning existing symbol
+@quotation
+@b{Common Lisp note:} In Common Lisp, you can intern an existing symbol
+in an obarray.  In Emacs Lisp, you cannot do this, because the argument
+to @code{intern} must be a string, not a symbol.
+@end quotation
+
 @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.
@@ -299,17 +327,27 @@ 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.
 
+The argument @var{name} may also be a symbol; in that case,
+the function returns @var{name} if @var{name} is interned
+in the specified obarray, and otherwise @code{nil}.
+
 @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
@@ -323,10 +361,11 @@ This variable is the standard obarray for use by @code{intern} and
 @end defvar
 
 @defun mapatoms function &optional obarray
-This function call @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.
+@anchor{Definition of mapatoms}
+This function calls @var{function} once with each symbol in the obarray
+@var{obarray}.  Then 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)
@@ -344,6 +383,20 @@ 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 Property Lists,, Creating Symbols, Symbols
 @section Property Lists
 @cindex property list
@@ -353,17 +406,18 @@ example using @code{mapatoms}.
 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 how to compile it, 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.
+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.
 
   Character positions in a string or buffer can also have property lists.
 @xref{Text Properties}.
 
   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:
+objects, but the names are usually symbols.  Property list functions
+compare the property names 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)
@@ -373,6 +427,16 @@ objects, but the names are usually symbols.  They are compared using
 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.
+* 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
+
 @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
@@ -380,16 +444,16 @@ 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.
+information to various Lisp function names or variables.  If your
+program keeps all of its associations in one association list, it will
+typically need to search that entire list each time it checks for an
+association.  This could be slow.  By contrast, if you keep the same
+information 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
@@ -397,19 +461,22 @@ 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.
+unique, such as by beginning the property name with the program's usual
+name-prefix for variables and functions.)  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
 
 @defun symbol-plist symbol
 This function returns the property list of @var{symbol}.
 @end defun
 
 @defun setplist symbol plist
-  This function sets @var{symbol}'s property list to @var{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.
+not enforced.  The return value is @var{plist}.
 
 @smallexample
 (setplist 'foo '(a 1 b (2 3) c nil))
@@ -452,3 +519,79 @@ The @code{put} function returns @var{value}.
      @result{} (verb transitive noun (a buzzing little bug))
 @end smallexample
 @end defun
+
+@node Other Plists
+@subsection Property Lists Outside Symbols
+
+  These functions are useful for manipulating property lists
+that are stored in places other than symbols:
+
+@defun plist-get plist property
+This returns the value of the @var{property} property
+stored in the property list @var{plist}.  For example,
+
+@example
+(plist-get '(foo 4) 'foo)
+     @result{} 4
+(plist-get '(foo 4 bad) 'foo)
+     @result{} 4
+(plist-get '(foo 4 bad) 'bar)
+     @result{} @code{wrong-type-argument} error
+@end example
+
+It accepts a malformed @var{plist} argument and always returns @code{nil}
+if @var{property} is not found in the @var{plist}.  For example,
+
+@example
+(plist-get '(foo 4 bad) 'bar)
+     @result{} nil
+@end example
+@end defun
+
+@defun plist-put 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 (plist-put my-plist 'foo 69))
+     @result{} (bar t foo 69)
+(setq my-plist (plist-put my-plist 'quux '(a)))
+     @result{} (bar t foo 69 quux (a))
+@end example
+@end defun
+
+  You could define @code{put} in terms of @code{plist-put} as follows:
+
+@example
+(defun put (symbol prop value)
+  (setplist symbol
+            (plist-put (symbol-plist symbol) prop value)))
+@end example
+
+@defun lax-plist-get plist property
+Like @code{plist-get} except that it compares properties
+using @code{equal} instead of @code{eq}.
+@end defun
+
+@defun lax-plist-put plist property value
+Like @code{plist-put} except that it compares properties
+using @code{equal} instead of @code{eq}.
+@end defun
+
+@defun plist-member plist property
+@tindex plist-member
+This returns non-@code{nil} if @var{plist} contains the given
+@var{property}.  Unlike @code{plist-get}, this allows you to distinguish
+between a missing property and a property with the value @code{nil}.
+The value is actually the tail of @var{plist} whose @code{car} is
+@var{property}.
+@end defun
+
+@ignore
+   arch-tag: 8750b7d2-de4c-4923-809a-d35fc39fd8ce
+@end ignore