⟦4b59108ff⟧

TextFile

@setfilename ../info/symbols
@node Symbols, Variables, Sequences Arrays Vectors, Top
@chapter Symbols

  This chapter describes how symbols may be used, what the components of
symbols are, and how symbols are created and interned.  Property lists are
also described here.

  A @dfn{symbol} is a unique name which may be used in several ways
simultaneously.  These are listed below with references to were these
uses are described.

@itemize @bullet

@item
A symbol can be used simply as a unique entity.
@xref{Creating and Interning Symbols}

@item
A symbol can be used as a global variable.
@xref{Global Variables}

@item
A symbol can be used as a local variable.
@xref{Local Variables}

@item
A symbol can be used to reference a function or macro.
@xref{Functions}, and @pxref{Macros}.

@item
A symbol can be used to reference a property list of global information.
@xref{Property Lists}

@end itemize

  You may 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::   
* Definitions and Declarations::        
* Creating and Interning Symbols::      
* Property Lists::      
* Lisp Symbol Completion::
@end menu

@node Symbol Components, Definitions and Declarations, Symbols, Symbols
@section Symbol Components

@cindex symbol components
@cindex symbol cells
  To support the above mentioned uses, each symbol has four components
(or attributes or cells), each of which references another object.

@cindex print name cell
  The print name cell is described elsewhere (@pxref{Symbol Type}).

  One essential aspect of symbols is that a symbol with a given print
name is unique: no other symbol can have the same print name.  The Lisp
reader ensures that every time it reads a name, it looks for an existing
symbol with that name before it creates a new one.  (In GNU Emacs Lisp,
this is done with a hashing algorithm that uses an obarray;
@pxref{Creating and Interning Symbols}.)

@cindex value cell
@cindex function cell
  The other three cells of a symbol @emph{may} reference any Lisp object
whatsoever.  In normal usage, if the symbol is used as the name of a
function, the function cell usually contains a reference to a function
as that is what the Lisp interpreter expects to see there.
(@xref{Evaluation}.)  Keyboard macros (@pxref{Keyboard Macros}) and
keymaps (@pxref{Keymaps}) may also be stored in the function cell of
symbols.

@cindex property list cell
  Likewise, the property list cell normally references a correctly formatted
property list (@pxref{Property Lists}), as a number of functions will expect
to see a property list there.  The value cell contains the symbol's global
value, if any, and that may be any Lisp object (@pxref{Global Variables}).

  Quite often, we will refer to the function @code{foo} when we really mean
the function referenced by the function cell of the symbol @code{foo}.
Similarly for the value cell and property list cell.  The distinction will
only be made when necessary.

  Here is a summary of the components of a symbol.

@table @b
@item Name
  The string of characters used to identify the symbol when reading or
printing.  See @code{symbol-name} in @ref{Creating and Interning Symbols}.

@item Value
  The global value of a symbol.  See @code{symbol-value} in
@ref{Accessing Variables}.

@item Function
  The function that is called when the symbol appears in the function
position of a form being evaluated, or as the first argument to
@code{funcall}, @code{apply}, etc.  This cell is also used by keymaps
and keyboard macros.  See @code{symbol-function} in @ref{Function Cells}.

@item Property List
  The property list is used by several functions to look up values that are
associated with the symbol and a property symbol.  See @code{symbol-plist} in
@ref{Property Lists}.
@end table

@node Definitions and Declarations, Creating and Interning Symbols, Symbol Components, Symbols
@section Definitions and Declarations

  A @dfn{definition} or @dfn{declaration} is a special form that
establishes a relationship between a symbol and some object.  There are
four definition constructs in GNU Emacs Lisp.

  @code{defvar} and @code{defconst} as definitions both establish a
symbol as a global variable.  As @dfn{declarations}, they serve only to
inform the person reading the code of the intended use of a symbol, and
do not in any way affect whether the global value may be changed.
@code{defvar} and @code{defconst} are documented in @ref{Variables}.

  @code{defun} and @code{defmacro} definitions create @code{lambda} and
@code{macro} expressions respectively and bind them to the function cell
value of the symbol being defined.  @code{defun} and @code{defmacro} are
documented in separate chapters (@pxref{Functions} and @pxref{Macros}).

  In GNU Emacs Lisp, definitions serve several purposes.  First, they
inform the user who reads the code that certain constructs (typically
variables or functions) are @emph{intended} to be used in the specified
ways.  Utilities such as @file{etags} and @file{make-docfile} can
recognize these declarations also, and add the appropriate information
to tag tables and the @file{etc/DOC} file.  Second, they inform Lisp of
the same thing, allowing it to ensure that the desired uses are made
possible.

@quotation
@cindex Common Lisp declarations
@b{Common Lisp Note:} In most Lisp systems, declarations supply
information to the compiler, allowing it to output more optimal code
than would otherwise be possible.  The GNU Emacs Lisp compiler does not
presently make use of any declarations to optimize code.
@end quotation

@node Creating and Interning Symbols, Property Lists, Definitions and Declarations, Symbols
@section Creating and Interning Symbols

@cindex reading symbols
  To understand how symbols are created in GNU Emacs Lisp, it is necessary
to know how Lisp reads them.  It is essential to ensure that every time
Lisp reads the same set of characters, it finds the same symbol.
Failure to do so would be disastrous.

@cindex symbol name hashing
  When the Lisp reader encounters a symbol, it reads
in all the characters in a name.  Then it ``hashes'' those
characters into a vector called an @dfn{obarray}.  Hashing is just an
efficient method of looking something up.  Instead of searching a
telephone book cover to cover when looking up Jan Jones, you start with
the @samp{J}s and go from there.  That is a simple version of hashing.
A number of symbols might all hash to the same element in that
obarray, that is, they hash to the same @dfn{bucket}, and Lisp just looks
through the bucket to see if one of the symbols has the name in question.

  If such a symbol is found, then it is returned.  If no such symbol is
found, then a new symbol is created and added to the obarray.
Adding a symbol to an obarray is called @dfn{interning} it, and the
symbol may then be called an @dfn{interned symbol}.
A symbol may be interned in only one obarray.

@cindex symbol equality
  If a symbol is not in an obarray, then there is no way for Lisp ever 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 properties of symbols.  It is possible, though
uncommon, for two different symbols to have the same name in different
obarrays; they are not @code{eq} or @code{equal}.

  The functions below all take a name and sometimes an obarray as
arguments.  It is a @code{wrong-type-argument} error if the name is not
a string, or if the obarray is not a vector.

@defun symbol-name symbol
@cindex print name
  This function returns the string that is @var{symbol}'s name.  Changing
the name cell of a symbol will change the name of the symbol.
Changing the string by substituting characters, etc, will also change
the name of the symbol.  Don't do either of these things.  Rather,
create a new symbol with the desired name.

@example
(symbol-name 'foo)
     @result{} "foo"
@end example
@end defun

@defun make-symbol name
@cindex uninterned symbol
  Return 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 the string was not interned.

@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 symbol whose name is @var{name}.  
If the symbol is not in the obarray, it is added.  If
@var{obarray} is supplied, it specifies the obarray to use; otherwise
the value of the global variable @code{obarray} is used.

@example
(setq sym (intern "foo"))
     @result{} foo
(eq sym 'foo)
     @result{} t
@end example
@end defun

@defun intern-soft name &optional obarray
  This function returns the symbol whose name is @var{name}, or @code{nil}
if a symbol with that name is not found in the obarray.  Therefore, you
can use @code{intern-soft} to test whether a symbol with a given name is
interned.  If @var{obarray} is supplied, it specifies the obarray to
use; otherwise the value of the global variable @code{obarray} is used.

@example
(intern-soft "frazzle")                ; @r{No such symbol exists.}
     @result{} nil
(make-symbol "frazzle")                ; @r{Create an uninterned one.}
     @result{} frazzle
(intern-soft "frazzle")                ; @r{That one cannot be found.}
     @result{} nil
(setq sym (intern "frazzle"))          ; @r{Create an interned one.}
     @result{} frazzle
(intern-soft "frazzle")                ; @r{That one can be found!}
     @result{} frazzle
(eq sym 'frazzle)                      ; @r{And it is the same one.}
     @result{} t
@end example
@end defun

@defvar obarray
  This global variable is the standard obarray for use by @code{intern} and
@code{read}.  It is a vector whose length ought to be prime for best
results (presently 511).  Each element is an interned symbol whose name
hashes to that bucket.  That symbol (if any) has an internal link (invisible
to the user) to the next symbol that hashes to that bucket.  The order of
symbols in a bucket is unimportant.
@end defvar

@defun mapatoms function &optional obarray
  This function applies @var{function} to every symbol in @var{obarray}.
It returns @code{nil}.  If @var{obarray} is not supplied, it defaults
to the value of @code{obarray}; the normal obarray of all symbols.

See @code{documentation} in @ref{Documentation Strings}, for another
example using @code{mapatoms}.

@example
(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 example
@end defun

@node Property Lists, Lisp Symbol Completion, Creating and Interning Symbols, Symbols
@section Property Lists

  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 associate a property name (usually a symbol) with some property or
value.  Property lists are generally used to record information about a
symbol, such as the name of the file in which it received a function
definition in, or the grammatical class the name of the symbol belongs
in a language understanding system.

  The property names (or keys) and property values may be any Lisp objects.
The property names are compared using @code{eq}.

@cindex property lists vs association lists
  Association lists (@pxref{Association Lists}) are very similar to
property lists.  But unlike association lists, the order in which the
pairs of elements occur is not important since each property name can
appear only once in the property list (as a key).  Thus a property list
is usually more space efficient than an association list.  Another
factor in favor of using a property list is that it is quickly
accessable through the global symbol while an association list may be
stored as a variable value which is accessed by a search up the run-time
stack.

  There are several reasons for using an association list over a property
list.  Depending on your application, it may be faster to add a pair 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 best to name properties in some unique
fashion such as including the name of your extension package in the
property name.)  An association list may be used like a stack where
pairs are pushed on the top of the stack and later popped off; this is
not possible with a property list.

@defun symbol-plist symbol
  Returns the property list of the @var{symbol}.  A property list is a
list in which the odd numbered elements are the property names and the
even numbered elements are the properties or associated values.  You
should @emph{not} use this function to get access to the property list
for the purpose of altering it.  (See the example for @code{setplist}).
@end defun

@defun setplist symbol plist
  This function sets @var{symbol}'s property list to @var{plist}.
@var{plist} should be a well-formed property list, although this condition
is not checked for.

@example
(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 example
@end defun

@defun get symbol key
  This function gets @var{key} from @var{symbol}'s property list.  If
@var{symbol} has such a key, the associated value is returned.  If there is
no such key, @code{nil} is returned.  Thus, there is no distinction between
an associated value of @code{nil} and the absence of the key.  @var{key} is
compared with the property names using @code{eq}, so any object is legitimate.
See @code{put} for example.
@end defun

@defun put symbol key value
  This function puts @var{value} onto @var{symbol}'s property list under
the property name @var{key}, replacing any previous value.

(Emacs oriented example needed here!!)

@example
(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)
     @result{} (verb transitive noun (a buzzing little bug))
@end example
@end defun

@node Lisp Symbol Completion,  , Property Lists, Symbols
@section Lisp Symbol Completion
@cindex Lisp symbol completion
@cindex symbol completion, lisp 
@cindex completion, lisp symbol 

  If you type a part of a symbol, and then type @kbd{M-@key{TAB}}
(@code{lisp-complete-symbol}, Emacs will attempt to return as much of
the name of the symbol that it can.  Not only does this save typing,
but it can help you with the name of a symbol that you partially forgot.

  For more on completion, @pxref{Completion}.

@deffn Command lisp-complete-symbol
  This function performs completion on the symbol preceding point.
That symbol is completed against the symbols in the global variable
@code{obarray}, inserting characters from the completion into the
buffer.  If there is more than one completion, a list of all possible
completions is placed in the @samp{*Help*} buffer.  It is an error if there
is no possible completion in @code{obarray}.

  If the symbol starts just after the character @samp{(}, only
symbols with function definitions will be considered.  Otherwise,
symbols with any of a function definition, value, or property will be
considered.

  @code{lisp-complete-symbol} returns @code{t} if the symbol had an exact, 
and unique, match; otherwise, it returns @code{nil}.

  In the example, the user already inserted @samp{(forwa} into the buffer 
@file{foo.el}.  @code{lisp-complete-symbol} is then invoked, and completes 
the function call to @samp{(forward-}.

@example
---------- Buffer: foo.el ----------
(forwa@point{}
---------- Buffer: foo.el ----------

(lisp-complete-symbol)
     @result{} nil

---------- Buffer: foo.el ----------
(forward-@point{}
---------- Buffer: foo.el ----------
@end example
@end deffn
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦4b59108ff⟧ TextFile

Derivation

TextFile
