procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update several Lisp manual chapters.

Browse source 
* doc/lispref/eval.texi (Intro Eval, Symbol Forms): Minor tweaks for
correctness with lexical scoping.
(Eval): Copyedits.

* doc/lispref/sequences.texi (Sequence Functions): Don't repeat the
introduction already given in the parent.
(Vectors): Copyedits.
(Rings): Move from lists.texi.  Note that this is specific to the
ring package.

* doc/lispref/lists.texi (Cons Cells): Copyedits.
(List Elements): Mention push.
(List Variables): Mention pop.
(Rings): Move to sequences.texi.

* doc/lispref/strings.texi (Text Comparison): Minor qualification.

* doc/lispref/symbols.texi (Definitions, Symbol Components): Mention variable
scoping issues.
(Plists and Alists): Copyedits.
This commit is contained in:
Chong Yidong 2012-01-23 12:23:50 +08:00
parent 2724d9c71e
commit 31cbea1d3d
9 changed files with 278 additions and 266 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
admin/FOR-RELEASE
View file

@ -187,25 +187,25 @@ backups.texi
buffers.texi
commands.texi
compile.texi
control.texi
control.texi cyd
customize.texi
debugging.texi
display.texi
edebug.texi
elisp.texi
errors.texi
eval.texi
eval.texi cyd
files.texi
frames.texi
functions.texi
hash.texi
hash.texi cyd
help.texi
hooks.texi
index.texi
internals.texi
intro.texi cyd
keymaps.texi
lists.texi
lists.texi cyd
loading.texi
locals.texi
macros.texi
@ -214,17 +214,17 @@ markers.texi
minibuf.texi
modes.texi
nonascii.texi
numbers.texi
numbers.texi cyd
objects.texi cyd
os.texi
package.texi
positions.texi
processes.texi
searching.texi
sequences.texi
sequences.texi cyd
streams.texi
strings.texi
symbols.texi
strings.texi cyd
symbols.texi cyd
syntax.texi
text.texi
tips.texi
@ -232,8 +232,7 @@ variables.texi
windows.texi
* PLANNED ADDITIONS
** pov-mode (probably not for Emacs-23: waiting for a Free POV-Ray).
* pov-mode (probably not for Emacs-23: waiting for a Free POV-Ray).
** gas-mode ?

23
doc/lispref/ChangeLog
View file

@ -1,3 +1,26 @@
2012-01-23 Chong Yidong <cyd@gnu.org>
* strings.texi (Text Comparison): Minor qualification.
* lists.texi (Cons Cells): Copyedits.
(List Elements): Mention push.
(List Variables): Mention pop.
(Rings): Move to sequences.texi.
* sequences.texi (Sequence Functions): Don't repeat the
introduction already given in the parent.
(Vectors): Copyedits.
(Rings): Move from lists.texi. Note that this is specific to the
ring package.
* symbols.texi (Definitions, Symbol Components): Mention variable
scoping issues.
(Plists and Alists): Copyedits.
* eval.texi (Intro Eval, Symbol Forms): Minor tweaks for
correctness with lexical scoping.
(Eval): Copyedits.
2012-01-21 Chong Yidong <cyd@gnu.org>
* intro.texi (A Sample Function Description): Special notation

10
doc/lispref/control.texi
View file

@ -8,11 +8,11 @@
@cindex special forms for control structures
@cindex control structures
A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}).
We control the order of execution of these forms by enclosing them in
@dfn{control structures}. Control structures are special forms which
control when, whether, or how many times to execute the forms they
contain.
A Lisp program consists of a set of @dfn{expressions}, or
@dfn{forms} (@pxref{Forms}). We control the order of execution of
these forms by enclosing them in @dfn{control structures}. Control
structures are special forms which control when, whether, or how many
times to execute the forms they contain.
@cindex textual order
The simplest order of execution is sequential execution: first form

2
doc/lispref/elisp.texi
View file

@ -326,7 +326,6 @@ Lists
* Modifying Lists:: Storing new pieces into an existing list.
* Sets And Lists:: A list can represent a finite mathematical set.
* Association Lists:: A list can represent a finite relation or mapping.
* Rings:: Managing a fixed-size ring of objects.
Modifying Existing List Structure
@ -344,6 +343,7 @@ Sequences, Arrays, and Vectors
* Vector Functions:: Functions specifically for vectors.
* Char-Tables:: How to work with char-tables.
* Bool-Vectors:: How to work with bool-vectors.
* Rings:: Managing a fixed-size ring of objects.
Hash Tables

24
doc/lispref/eval.texi
View file

@ -64,8 +64,8 @@ evaluate a @dfn{function call} form such as @code{(car x)}, Emacs
first evaluates the argument (the subform @code{x}). After evaluating
the argument, Emacs @dfn{executes} the function (@code{car}), and if
the function is written in Lisp, execution works by evaluating the
@dfn{body} of the function. (In this example, however, @code{car} is
not a Lisp function; it is a primitive function implemented in C.)
@dfn{body} of the function (in this example, however, @code{car} is
not a Lisp function; it is a primitive function implemented in C).
@xref{Functions}, for more information about functions and function
calls.
@ -77,9 +77,8 @@ variables (@pxref{Variables}).@footnote{This definition of
that can affect the result of a program.} Whenever a form refers to a
variable without creating a new binding for it, the variable evaluates
to the value given by the current environment. Evaluating a form may
create a new environment for recursive evaluation, by binding
variables (@pxref{Local Variables}). Such environments are temporary,
and vanish when the evaluation of the form is complete.
also temporarily alter the environment by binding variables
(@pxref{Local Variables}).
@cindex side effect
Evaluating a form may also make changes that persist; these changes
@ -177,9 +176,9 @@ program. Here is an example:
@cindex symbol evaluation
When a symbol is evaluated, it is treated as a variable. The result
is the variable's value, if it has one. If it has none (if its value
cell is void), an error is signaled. For more information on the use of
variables, see @ref{Variables}.
is the variable's value, if it has one. If the symbol has no value as
a variable, the Lisp interpreter signals an error. For more
information on the use of variables, see @ref{Variables}.
In the following example, we set the value of a symbol with
@code{setq}. Then we evaluate the symbol, and get back the value that
@ -602,12 +601,13 @@ functions provides the ability to pass information to them as
arguments.
@defun eval form &optional lexical
This is the basic function evaluating an expression. It evaluates
This is the basic function for evaluating an expression. It evaluates
@var{form} in the current environment and returns the result. How the
evaluation proceeds depends on the type of the object (@pxref{Forms}).
@var{lexical} if non-nil means to evaluate @var{form} using lexical scoping
rules (@pxref{Lexical Binding}) instead of the default dynamic scoping used
historically in Emacs Lisp.
The argument @var{lexical}, if non-@code{nil}, means to evaluate
@var{form} using lexical scoping rules for variables, instead of the
default dynamic scoping rules. @xref{Lexical Binding}.
Since @code{eval} is a function, the argument expression that appears
in a call to @code{eval} is evaluated twice: once as preparation before

163
doc/lispref/lists.texi
View file

@ -23,7 +23,6 @@ the whole list.
* Modifying Lists:: Storing new pieces into an existing list.
* Sets And Lists:: A list can represent a finite mathematical set.
* Association Lists:: A list can represent a finite relation or mapping.
* Rings:: Managing a fixed-size ring of objects.
@end menu
@node Cons Cells
@ -31,61 +30,56 @@ the whole list.
@cindex lists and cons cells
Lists in Lisp are not a primitive data type; they are built up from
@dfn{cons cells}. A cons cell is a data object that represents an
ordered pair. That is, it has two slots, and each slot @dfn{holds}, or
@dfn{refers to}, some Lisp object. One slot is known as the @sc{car},
and the other is known as the @sc{cdr}. (These names are traditional;
see @ref{Cons Cell Type}.) @sc{cdr} is pronounced ``could-er.''
@dfn{cons cells} (@pxref{Cons Cell Type}). A cons cell is a data
object that represents an ordered pair. That is, it has two slots,
and each slot @dfn{holds}, or @dfn{refers to}, some Lisp object. One
slot is known as the @sc{car}, and the other is known as the @sc{cdr}.
(These names are traditional; see @ref{Cons Cell Type}.) @sc{cdr} is
pronounced ``could-er.''
We say that ``the @sc{car} of this cons cell is'' whatever object
its @sc{car} slot currently holds, and likewise for the @sc{cdr}.
A list is a series of cons cells ``chained together,'' so that each
cell refers to the next one. There is one cons cell for each element of
the list. By convention, the @sc{car}s of the cons cells hold the
elements of the list, and the @sc{cdr}s are used to chain the list: the
@sc{cdr} slot of each cons cell refers to the following cons cell. The
@sc{cdr} of the last cons cell is @code{nil}. This asymmetry between
the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the
level of cons cells, the @sc{car} and @sc{cdr} slots have the same
characteristics.
cell refers to the next one. There is one cons cell for each element
of the list. By convention, the @sc{car}s of the cons cells hold the
elements of the list, and the @sc{cdr}s are used to chain the list
(this asymmetry between @sc{car} and @sc{cdr} is entirely a matter of
convention; at the level of cons cells, the @sc{car} and @sc{cdr}
slots have similar properties). Hence, the @sc{cdr} slot of each cons
cell in a list refers to the following cons cell.
@cindex true list
Since @code{nil} is the conventional value to put in the @sc{cdr} of
the last cons cell in the list, we call that case a @dfn{true list}.
In Lisp, we consider the symbol @code{nil} a list as well as a
symbol; it is the list with no elements. For convenience, the symbol
Also by convention, the @sc{cdr} of the last cons cell in a list is
@code{nil}. We call such a @code{nil}-terminated structure a
@dfn{true list}. In Emacs Lisp, the symbol @code{nil} is both a
symbol and a list with no elements. For convenience, the symbol
@code{nil} is considered to have @code{nil} as its @sc{cdr} (and also
as its @sc{car}). Therefore, the @sc{cdr} of a true list is always a
true list.
as its @sc{car}).
Hence, the @sc{cdr} of a true list is always a true list. The
@sc{cdr} of a nonempty true list is a true list containing all the
elements except the first.
@cindex dotted list
@cindex circular list
If the @sc{cdr} of a list's last cons cell is some other value,
neither @code{nil} nor another cons cell, we call the structure a
@dfn{dotted list}, since its printed representation would use
@samp{.}. There is one other possibility: some cons cell's @sc{cdr}
could point to one of the previous cons cells in the list. We call
that structure a @dfn{circular list}.
If the @sc{cdr} of a list's last cons cell is some value other than
@code{nil}, we call the structure a @dfn{dotted list}, since its
printed representation would use dotted pair notation (@pxref{Dotted
Pair Notation}). There is one other possibility: some cons cell's
@sc{cdr} could point to one of the previous cons cells in the list.
We call that structure a @dfn{circular list}.
For some purposes, it does not matter whether a list is true,
circular or dotted. If the program doesn't look far enough down the
circular or dotted. If a program doesn't look far enough down the
list to see the @sc{cdr} of the final cons cell, it won't care.
However, some functions that operate on lists demand true lists and
signal errors if given a dotted list. Most functions that try to find
the end of a list enter infinite loops if given a circular list.
@cindex list structure
Because most cons cells are used as part of lists, the phrase
@dfn{list structure} has come to mean any structure made out of cons
cells.
The @sc{cdr} of any nonempty true list @var{l} is a list containing all the
elements of @var{l} except the first.
@xref{Cons Cell Type}, for the read and print syntax of cons cells and
lists, and for ``box and arrow'' illustrations of lists.
Because most cons cells are used as part of lists, we refer to any
structure made out of cons cells as a @dfn{list structure}.
@node List-related Predicates
@section Predicates on Lists
@ -257,6 +251,10 @@ x
x
@result{} (b c)
@end example
@noindent
For the @code{pop} macro, which removes an element from a list,
@xref{List Variables}.
@end defmac
@defun nth n list
@ -695,6 +693,10 @@ This macro provides an alternative way to write
l
@result{} (c a b)
@end example
@noindent
For the @code{pop} macro, which removes the first element from a list,
@xref{List Elements}.
@end defmac
Two functions modify lists that are the values of variables.
@ -1800,90 +1802,3 @@ often modifies the original list structure of @var{alist}.
compares the @sc{cdr} of each @var{alist} association instead of the
@sc{car}.
@end defun
@node Rings
@section Managing a Fixed-Size Ring of Objects
@cindex ring data structure
This section describes functions for operating on rings. A
@dfn{ring} is a fixed-size data structure that supports insertion,
deletion, rotation, and modulo-indexed reference and traversal.
@defun make-ring size
This returns a new ring capable of holding @var{size} objects.
@var{size} should be an integer.
@end defun
@defun ring-p object
This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
@end defun
@defun ring-size ring
This returns the maximum capacity of the @var{ring}.
@end defun
@defun ring-length ring
This returns the number of objects that @var{ring} currently contains.
The value will never exceed that returned by @code{ring-size}.
@end defun
@defun ring-elements ring
This returns a list of the objects in @var{ring}, in order, newest first.
@end defun
@defun ring-copy ring
This returns a new ring which is a copy of @var{ring}.
The new ring contains the same (@code{eq}) objects as @var{ring}.
@end defun
@defun ring-empty-p ring
This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
@end defun
The newest element in the ring always has index 0. Higher indices
correspond to older elements. Indices are computed modulo the ring
length. Index @minus{}1 corresponds to the oldest element, @minus{}2
to the next-oldest, and so forth.
@defun ring-ref ring index
This returns the object in @var{ring} found at index @var{index}.
@var{index} may be negative or greater than the ring length. If
@var{ring} is empty, @code{ring-ref} signals an error.
@end defun
@defun ring-insert ring object
This inserts @var{object} into @var{ring}, making it the newest
element, and returns @var{object}.
If the ring is full, insertion removes the oldest element to
make room for the new element.
@end defun
@defun ring-remove ring &optional index
Remove an object from @var{ring}, and return that object. The
argument @var{index} specifies which item to remove; if it is
@code{nil}, that means to remove the oldest item. If @var{ring} is
empty, @code{ring-remove} signals an error.
@end defun
@defun ring-insert-at-beginning ring object
This inserts @var{object} into @var{ring}, treating it as the oldest
element. The return value is not significant.
If the ring is full, this function removes the newest element to make
room for the inserted element.
@end defun
@cindex fifo data structure
If you are careful not to exceed the ring size, you can
use the ring as a first-in-first-out queue. For example:
@lisp
(let ((fifo (make-ring 5)))
(mapc (lambda (obj) (ring-insert fifo obj))
'(0 one "two"))
(list (ring-remove fifo) t
(ring-remove fifo) t
(ring-remove fifo)))
@result{} (0 t one t "two")
@end lisp

120
doc/lispref/sequences.texi
View file

@ -8,10 +8,10 @@
@chapter Sequences, Arrays, and Vectors
@cindex sequence
Recall that the @dfn{sequence} type is the union of two other Lisp
types: lists and arrays. In other words, any list is a sequence, and
any array is a sequence. The common property that all sequences have is
that each is an ordered collection of elements.
The @dfn{sequence} type is the union of two other Lisp types: lists
and arrays. In other words, any list is a sequence, and any array is
a sequence. The common property that all sequences have is that each
is an ordered collection of elements.
An @dfn{array} is a fixed-length object with a slot for each of its
elements. All the elements are accessible in constant time. The four
@ -54,19 +54,17 @@ But it is possible to add elements to the list, or remove elements.
* Vector Functions:: Functions specifically for vectors.
* Char-Tables:: How to work with char-tables.
* Bool-Vectors:: How to work with bool-vectors.
* Rings:: Managing a fixed-size ring of objects.
@end menu
@node Sequence Functions
@section Sequences
In Emacs Lisp, a @dfn{sequence} is either a list or an array. The
common property of all sequences is that they are ordered collections of
elements. This section describes functions that accept any kind of
sequence.
This section describes functions that accept any kind of sequence.
@defun sequencep object
Returns @code{t} if @var{object} is a list, vector, string,
bool-vector, or char-table, @code{nil} otherwise.
This function returns @code{t} if @var{object} is a list, vector,
string, bool-vector, or char-table, @code{nil} otherwise.
@end defun
@defun length sequence
@ -149,8 +147,9 @@ This function generalizes @code{aref} (@pxref{Array Functions}) and
@defun copy-sequence sequence
@cindex copying sequences
Returns a copy of @var{sequence}. The copy is the same type of object
as the original sequence, and it has the same elements in the same order.
This function returns a copy of @var{sequence}. The copy is the same
type of object as the original sequence, and it has the same elements
in the same order.
Storing a new element into the copy does not affect the original
@var{sequence}, and vice versa. However, the elements of the new
@ -394,8 +393,8 @@ symbol-lookup tables (@pxref{Creating Symbols}), as part of the
representation of a byte-compiled function (@pxref{Byte Compilation}),
and more.
In Emacs Lisp, the indices of the elements of a vector start from zero
and count up from there.
Like other arrays, vectors use zero-origin indexing: the first
element has index 0.
Vectors are printed with square brackets surrounding the elements.
Thus, a vector whose elements are the symbols @code{a}, @code{b} and
@ -728,3 +727,96 @@ bv
@noindent
These results make sense because the binary codes for control-_ and
control-W are 11111 and 10111, respectively.
@node Rings
@section Managing a Fixed-Size Ring of Objects
@cindex ring data structure
A @dfn{ring} is a fixed-size data structure that supports insertion,
deletion, rotation, and modulo-indexed reference and traversal. An
efficient ring data structure is implemented by the @code{ring}
package. It provides the functions listed in this section.
Note that several ``rings'' in Emacs, like the kill ring and the
mark ring, are actually implemented as simple lists, @emph{not} using
the @code{ring} package; thus the following functions won't work on
them.
@defun make-ring size
This returns a new ring capable of holding @var{size} objects.
@var{size} should be an integer.
@end defun
@defun ring-p object
This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
@end defun
@defun ring-size ring
This returns the maximum capacity of the @var{ring}.
@end defun
@defun ring-length ring
This returns the number of objects that @var{ring} currently contains.
The value will never exceed that returned by @code{ring-size}.
@end defun
@defun ring-elements ring
This returns a list of the objects in @var{ring}, in order, newest first.
@end defun
@defun ring-copy ring
This returns a new ring which is a copy of @var{ring}.
The new ring contains the same (@code{eq}) objects as @var{ring}.
@end defun
@defun ring-empty-p ring
This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
@end defun
The newest element in the ring always has index 0. Higher indices
correspond to older elements. Indices are computed modulo the ring
length. Index @minus{}1 corresponds to the oldest element, @minus{}2
to the next-oldest, and so forth.
@defun ring-ref ring index
This returns the object in @var{ring} found at index @var{index}.
@var{index} may be negative or greater than the ring length. If
@var{ring} is empty, @code{ring-ref} signals an error.
@end defun
@defun ring-insert ring object
This inserts @var{object} into @var{ring}, making it the newest
element, and returns @var{object}.
If the ring is full, insertion removes the oldest element to
make room for the new element.
@end defun
@defun ring-remove ring &optional index
Remove an object from @var{ring}, and return that object. The
argument @var{index} specifies which item to remove; if it is
@code{nil}, that means to remove the oldest item. If @var{ring} is
empty, @code{ring-remove} signals an error.
@end defun
@defun ring-insert-at-beginning ring object
This inserts @var{object} into @var{ring}, treating it as the oldest
element. The return value is not significant.
If the ring is full, this function removes the newest element to make
room for the inserted element.
@end defun
@cindex fifo data structure
If you are careful not to exceed the ring size, you can
use the ring as a first-in-first-out queue. For example:
@lisp
(let ((fifo (make-ring 5)))
(mapc (lambda (obj) (ring-insert fifo obj))
'(0 one "two"))
(list (ring-remove fifo) t
(ring-remove fifo) t
(ring-remove fifo)))
@result{} (0 t one t "two")
@end lisp

13
doc/lispref/strings.texi
View file

@ -410,8 +410,13 @@ in case if @code{case-fold-search} is non-@code{nil}.
@defun string= string1 string2
This function returns @code{t} if the characters of the two strings
match exactly. Symbols are also allowed as arguments, in which case
their print names are used.
Case is always significant, regardless of @code{case-fold-search}.
the symbol names are used. Case is always significant, regardless of
@code{case-fold-search}.
This function is equivalent to @code{equal} for comparing two strings
(@pxref{Equality Predicates}). In particular, the text properties of
the two strings are ignored. But if either argument is not a string
or symbol, an error is signaled.
@example
(string= "abc" "abc")
@ -422,10 +427,6 @@ Case is always significant, regardless of @code{case-fold-search}.
@result{} nil
@end example
The function @code{string=} ignores the text properties of the two
strings. When @code{equal} (@pxref{Equality Predicates}) compares two
strings, it uses @code{string=}.
For technical reasons, a unibyte and a multibyte string are
@code{equal} if and only if they contain the same sequence of
character codes and all these codes are either in the range 0 through

170
doc/lispref/symbols.texi
View file

@ -41,62 +41,58 @@ 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}.
The symbol's name.
@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}.
The symbol's current value as a variable.
@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 names and function names do
not conflict. See @code{symbol-function} in @ref{Function Cells}.
The symbol's function definition. It can also hold a symbol, a
keymap, or a keyboard macro.
@item Property list
@cindex property list cell
The @dfn{property list cell} holds the property list of the symbol. See
@code{symbol-plist} in @ref{Property Lists}.
The symbol's property list.
@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.
@noindent
The print name cell always holds a string, and cannot be changed.
Each of the other three cells can be set to any 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 @ref{Creating
Symbols}.)
The print name cell holds the string that is the name of a 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. To get a
symbol's name, use the function @code{symbol-name} (@pxref{Creating
Symbols}).
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}.
The value cell holds a symbol's value as a variable, which is what
you get if the symbol itself is evaluated as a Lisp expression.
@xref{Variables}, for details about how values are set and retrieved,
including complications such as @dfn{local bindings} and @dfn{scoping
rules}. Most symbols can have any Lisp object as a value, but certain
special 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 function cell holds a symbol's function definition. Often, we
refer to ``the function @code{foo}'' when we really mean the function
stored in the function cell of @code{foo}; we make the distinction
explicit only when necessary. Typically, the function cell is used to
hold a function (@pxref{Functions}) or a macro (@pxref{Macros}).
However, it can also be used to hold a symbol (@pxref{Function
Indirection}), keyboard macro (@pxref{Keyboard Macros}), keymap
(@pxref{Keymaps}), or autoload object (@pxref{Autoloading}). To get
the contents of a symbol's function cell, use the function
@code{symbol-function} (@pxref{Function Cells}).
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.
property list. To get a symbol's function cell, use the function
@code{symbol-plist}. @xref{Property Lists}.
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
@ -104,57 +100,43 @@ thing as holding the symbol @code{void}, nor the same as holding the
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
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}:
Because each symbol has separate value and function cells, variables
names and function names do not conflict. For example, the symbol
@code{buffer-file-name} has a value (the name of the file being
visited in the current buffer) as well as a function definition (a
primitive function that returns the name of the file):
@example
(symbol-name 'buffer-file-name)
@result{} "buffer-file-name"
(symbol-value 'buffer-file-name)
buffer-file-name
@result{} "/gnu/elisp/symbols.texi"
(symbol-function 'buffer-file-name)
@result{} #<subr buffer-file-name>
(symbol-plist 'buffer-file-name)
@result{} (variable-documentation 29529)
@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 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-@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
(or a byte-code object) in this cell.
@node Definitions, Creating Symbols, Symbol Components, Symbols
@section Defining Symbols
@cindex definitions of symbols
A @dfn{definition} in Lisp is a special form that announces your
intention to use a certain symbol in a particular way. In Emacs 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.
A @dfn{definition} is a special kind of Lisp expression that
announces your intention to use a symbol in a particular way. It
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}. For defining user option variables that can
be customized, use @code{defcustom} (@pxref{Customization}).
symbol as a @dfn{global variable}---a variable that can be accessed at
any point in a Lisp program. @xref{Variables}, for details about
variables. To define a customizable variable, use the
@code{defcustom} macro, which also calls @code{defvar} as a subroutine
(@pxref{Customization}).
In principle, you can assign a variable value to any symbol with
@code{setq}, whether not it has first been defined as a variable.
However, you ought to write a variable definition for each global
variable that you want to use; otherwise, your Lisp program may not
act correctly if it is evaluated with lexical scoping enabled
(@pxref{Variable Scoping}).
@code{defun} defines a symbol as a function, creating a lambda
expression and storing it in the function cell of the symbol. This
@ -171,15 +153,14 @@ 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 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{DOC-@var{version}} file. @xref{Accessing Documentation}.
As previously noted, Emacs Lisp allows the same symbol to be defined
both as a variable (e.g.@: with @code{defvar}) and as a function or
macro (e.g.@: with @code{defun}). Such definitions do not conflict.
These definition also act as guides for programming tools. For
example, the @kbd{C-h f} and @kbd{C-h v} commands create help buffers
containing links to the relevant variable, function, or macro
definitions. @xref{Name Help,,, emacs, The GNU Emacs Manual}.
@node Creating Symbols, Property Lists, Definitions, Symbols
@section Creating and Interning Symbols
@ -254,8 +235,8 @@ not work---only @code{intern} can enter a symbol in an obarray properly.
@cindex CL note---symbol in obarrays
@quotation
@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
several obarrays.
@b{Common Lisp note:} Unlike Common Lisp, Emacs Lisp does not provide
for interning a single symbol in several obarrays.
@end quotation
Most of the functions below take a name and sometimes an obarray as
@ -448,12 +429,13 @@ must be distinct.
Property lists are better than association lists for attaching
information to various Lisp function names or variables. If your
program keeps all of its associations in one association list, it will
program keeps all such information 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
association for a particular Lisp function name or variable, which
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.