(lispref.info)Symbol Components


Next: Definitions Prev: Symbols Up: Symbols

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

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

Print name
     The "print name cell" holds a string which 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 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 is done with a hashing algorithm that uses an obarray; see *Note
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 (*note
Evaluation::.).  Keyboard macros (Note: Keyboard Macros.), keymaps
(Note: Keymaps.) and autoload objects (Note: Autoloading.) are also
sometimes stored in the function cell of symbols.  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 only when
necessary.

   Similarly, the property list cell normally holds 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 the value of a cell which 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.  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
documentation about `buffer-file-name' in the `DOC' file.  (29529 is
the offset from the beginning of the `DOC' file where the documentation
for the function begins.)  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