[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r106913: Update several Lisp manual c
|
From: |
Chong Yidong |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r106913: Update several Lisp manual chapters. |
|
Date: |
Mon, 23 Jan 2012 12:23:50 +0800 |
|
User-agent: |
Bazaar (2.3.1) |
------------------------------------------------------------
revno: 106913
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Mon 2012-01-23 12:23:50 +0800
message:
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.
modified:
admin/FOR-RELEASE
doc/lispref/ChangeLog
doc/lispref/control.texi
doc/lispref/elisp.texi
doc/lispref/eval.texi
doc/lispref/lists.texi
doc/lispref/sequences.texi
doc/lispref/strings.texi
doc/lispref/symbols.texi
=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-01-21 14:58:38 +0000
+++ b/admin/FOR-RELEASE 2012-01-23 04:23:50 +0000
@@ -187,25 +187,25 @@
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 @@
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 @@
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 ?
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2012-01-21 16:04:55 +0000
+++ b/doc/lispref/ChangeLog 2012-01-23 04:23:50 +0000
@@ -1,3 +1,26 @@
+2012-01-23 Chong Yidong <address@hidden>
+
+ * 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 <address@hidden>
* intro.texi (A Sample Function Description): Special notation
=== modified file 'doc/lispref/control.texi'
--- a/doc/lispref/control.texi 2012-01-19 07:21:25 +0000
+++ b/doc/lispref/control.texi 2012-01-23 04:23:50 +0000
@@ -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
address@hidden 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
address@hidden (@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
=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi 2012-01-19 07:21:25 +0000
+++ b/doc/lispref/elisp.texi 2012-01-23 04:23:50 +0000
@@ -326,7 +326,6 @@
* 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 @@
* 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
=== modified file 'doc/lispref/eval.texi'
--- a/doc/lispref/eval.texi 2012-01-19 07:21:25 +0000
+++ b/doc/lispref/eval.texi 2012-01-23 04:23:50 +0000
@@ -64,8 +64,8 @@
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
address@hidden of the function. (In this example, however, @code{car} is
-not a Lisp function; it is a primitive function implemented in C.)
address@hidden 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 @@
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 @@
@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 @@
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}).
address@hidden 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 address@hidden, means to evaluate
address@hidden 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
=== modified file 'doc/lispref/lists.texi'
--- a/doc/lispref/lists.texi 2012-01-19 07:21:25 +0000
+++ b/doc/lispref/lists.texi 2012-01-23 04:23:50 +0000
@@ -23,7 +23,6 @@
* 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 @@
@cindex lists and cons cells
Lists in Lisp are not a primitive data type; they are built up from
address@hidden 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
address@hidden 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.''
address@hidden 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
address@hidden slot of each cons cell refers to the following cons cell. The
address@hidden 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
address@hidden We call such a @code{nil}-terminated structure a
address@hidden 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
address@hidden 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
address@hidden list}, since its printed representation would use
address@hidden 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
address@hidden, 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
address@hidden 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
address@hidden 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
@result{} (b c)
@end example
+
address@hidden
+For the @code{pop} macro, which removes an element from a list,
address@hidden Variables}.
@end defmac
@defun nth n list
@@ -695,6 +693,10 @@
l
@result{} (c a b)
@end example
+
address@hidden
+For the @code{pop} macro, which removes the first element from a list,
address@hidden Elements}.
@end defmac
Two functions modify lists that are the values of variables.
@@ -1800,90 +1802,3 @@
compares the @sc{cdr} of each @var{alist} association instead of the
@sc{car}.
@end defun
-
address@hidden Rings
address@hidden Managing a Fixed-Size Ring of Objects
-
address@hidden ring data structure
- This section describes functions for operating on rings. A
address@hidden is a fixed-size data structure that supports insertion,
-deletion, rotation, and modulo-indexed reference and traversal.
-
address@hidden make-ring size
-This returns a new ring capable of holding @var{size} objects.
address@hidden should be an integer.
address@hidden defun
-
address@hidden ring-p object
-This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
address@hidden defun
-
address@hidden ring-size ring
-This returns the maximum capacity of the @var{ring}.
address@hidden defun
-
address@hidden 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}.
address@hidden defun
-
address@hidden ring-elements ring
-This returns a list of the objects in @var{ring}, in order, newest first.
address@hidden defun
-
address@hidden 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}.
address@hidden defun
-
address@hidden ring-empty-p ring
-This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
address@hidden 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.
-
address@hidden ring-ref ring index
-This returns the object in @var{ring} found at index @var{index}.
address@hidden may be negative or greater than the ring length. If
address@hidden is empty, @code{ring-ref} signals an error.
address@hidden defun
-
address@hidden 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.
address@hidden defun
-
address@hidden 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
address@hidden, that means to remove the oldest item. If @var{ring} is
-empty, @code{ring-remove} signals an error.
address@hidden defun
-
address@hidden 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.
address@hidden defun
-
address@hidden 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:
-
address@hidden
-(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")
address@hidden lisp
=== modified file 'doc/lispref/sequences.texi'
--- a/doc/lispref/sequences.texi 2012-01-19 07:21:25 +0000
+++ b/doc/lispref/sequences.texi 2012-01-23 04:23:50 +0000
@@ -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 @@
* 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 @@
@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 @@
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 @@
@noindent
These results make sense because the binary codes for control-_ and
control-W are 11111 and 10111, respectively.
+
address@hidden Rings
address@hidden Managing a Fixed-Size Ring of Objects
+
address@hidden 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.
+
address@hidden make-ring size
+This returns a new ring capable of holding @var{size} objects.
address@hidden should be an integer.
address@hidden defun
+
address@hidden ring-p object
+This returns @code{t} if @var{object} is a ring, @code{nil} otherwise.
address@hidden defun
+
address@hidden ring-size ring
+This returns the maximum capacity of the @var{ring}.
address@hidden defun
+
address@hidden 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}.
address@hidden defun
+
address@hidden ring-elements ring
+This returns a list of the objects in @var{ring}, in order, newest first.
address@hidden defun
+
address@hidden 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}.
address@hidden defun
+
address@hidden ring-empty-p ring
+This returns @code{t} if @var{ring} is empty, @code{nil} otherwise.
address@hidden 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.
+
address@hidden ring-ref ring index
+This returns the object in @var{ring} found at index @var{index}.
address@hidden may be negative or greater than the ring length. If
address@hidden is empty, @code{ring-ref} signals an error.
address@hidden defun
+
address@hidden 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.
address@hidden defun
+
address@hidden 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
address@hidden, that means to remove the oldest item. If @var{ring} is
+empty, @code{ring-remove} signals an error.
address@hidden defun
+
address@hidden 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.
address@hidden defun
+
address@hidden 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:
+
address@hidden
+(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")
address@hidden lisp
=== modified file 'doc/lispref/strings.texi'
--- a/doc/lispref/strings.texi 2012-01-19 07:21:25 +0000
+++ b/doc/lispref/strings.texi 2012-01-23 04:23:50 +0000
@@ -410,8 +410,13 @@
@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
address@hidden
+
+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 @@
@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
=== modified file 'doc/lispref/symbols.texi'
--- a/doc/lispref/symbols.texi 2012-01-19 07:21:25 +0000
+++ b/doc/lispref/symbols.texi 2012-01-23 04:23:50 +0000
@@ -41,62 +41,58 @@
@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
address@hidden 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
address@hidden 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
address@hidden:} (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.
address@hidden
+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.
address@hidden, 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
address@hidden and @code{t}, and any symbol whose name starts with
address@hidden:} (those are called @dfn{keywords}). @xref{Constant
+Variables}.
+
+ 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
address@hidden (@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
address@hidden @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 @@
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},
address@hidden, 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
address@hidden 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
address@hidden
-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
address@hidden@var{version}} file. (29529 is the offset from the beginning
-of the @address@hidden file to where that documentation string
-begins---see @ref{Documentation Basics}.) The function cell contains
-the function for returning the name of the file.
address@hidden 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
address@hidden 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
address@hidden macro, which also calls @code{defvar} as a subroutine
+(@pxref{Customization}).
+
+ In principle, you can assign a variable value to any symbol with
address@hidden, 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 @@
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
address@hidden 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
address@hidden@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 @@
@cindex CL note---symbol in obarrays
@quotation
address@hidden Lisp note:} In Common Lisp, a single symbol may be interned in
-several obarrays.
address@hidden 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 @@
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.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r106913: Update several Lisp manual chapters.,
Chong Yidong <=