GNU Info

Info Node: (elisp)Symbol Components

(elisp)Symbol Components


Next: Definitions Prev: Symbols Up: Symbols
Enter node , (file) or (file)node

Symbol Components
=================

   Each symbol has four components (or "cells"), each of which
references another object:

Print name
     The "print name cell" holds a string that names the symbol for
     reading and printing.  See `symbol-name' in Note: Creating
     Symbols.

Value
     The "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 `symbol-value' in
     Note: Accessing Variables.

Function
     The "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 names and function names do not conflict.  See
     `symbol-function' in Note: Function Cells.

Property list
     The "property list cell" holds the property list of the symbol.
     See `symbol-plist' in Note: Property Lists.

   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 GNU Emacs Lisp,
this lookup uses a hashing algorithm and an obarray; see Note: Creating
Symbols.)

   The value cell holds the symbol's value as a variable (Note:
Variables).  That is what you get if you evaluate the symbol as a
Lisp expression (Note: Evaluation).  Any Lisp object is a legitimate
value.  Certain symbols have values that cannot be changed; these
include `nil' and `t', and any symbol whose name starts with `:' (those
are called "keywords").  Note: Constant Variables.

   We often refer to "the function `foo'" when we really mean the
function stored in the function cell of the symbol `foo'.  We make the
distinction explicit only when necessary.  In normal usage, the
function cell usually contains a function (Note: Functions) or a
macro (Note: Macros), as that is what the Lisp interpreter expects to
see there (Note: Evaluation).  Keyboard macros (Note: Keyboard
Macros), keymaps (Note: Keymaps) and autoload objects (Note:
Autoloading) are also sometimes stored in the function cells of
symbols.

   The property list cell normally should hold a correctly formatted
property list (Note: Property Lists), as a number of functions expect
to see a property list there.

   The function cell or the value cell may be "void", which means that
the cell does not reference any object.  (This is not the same thing as
holding the symbol `void', nor the same as holding the symbol `nil'.)
Examining a function or value cell that is void results in an error,
such as `Symbol's value as variable is void'.

   The four functions `symbol-name', `symbol-value', `symbol-plist',
and `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 `buffer-file-name':

     (symbol-name 'buffer-file-name)
          => "buffer-file-name"
     (symbol-value 'buffer-file-name)
          => "/gnu/elisp/symbols.texi"
     (symbol-plist 'buffer-file-name)
          => (variable-documentation 29529)
     (symbol-function 'buffer-file-name)
          => #<subr buffer-file-name>

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 Emacs Lisp Manual.
The property list cell contains the list `(variable-documentation
29529)' which tells the documentation functions where to find the
documentation string for the variable `buffer-file-name' in the
`DOC-VERSION' file.  (29529 is the offset from the beginning of the
`DOC-VERSION' file to where that documentation string begins--see Note:
Documentation Basics.)  The function cell contains the function for
returning the name of the file.  `buffer-file-name' names a primitive
function, which has no read syntax and prints in hash notation (Note:
Primitive Function Type).  A symbol naming a function written in Lisp
would have a lambda expression (or a byte-code object) in this cell.


automatically generated by info2www version 1.2.2.9