Commit 31cbea1d authored by Chong Yidong's avatar Chong Yidong
Browse files

Update several Lisp manual chapters.

* 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.
parent 2724d9c7
......@@ -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 ?
......
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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......@@ -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
......@@ -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
......
......@@ -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.
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 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.
@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 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 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