From 31cbea1d3d3c548025f70551514bd1a370301ccf Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Mon, 23 Jan 2012 12:23:50 +0800 Subject: [PATCH] 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. --- admin/FOR-RELEASE | 19 ++-- doc/lispref/ChangeLog | 23 +++++ doc/lispref/control.texi | 10 +-- doc/lispref/elisp.texi | 2 +- doc/lispref/eval.texi | 24 ++--- doc/lispref/lists.texi | 163 ++++++++-------------------------- doc/lispref/sequences.texi | 120 ++++++++++++++++++++++--- doc/lispref/strings.texi | 13 +-- doc/lispref/symbols.texi | 176 +++++++++++++++++-------------------- 9 files changed, 281 insertions(+), 269 deletions(-) diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE index 9335e5b1fbe..f704a3c9397 100644 --- a/admin/FOR-RELEASE +++ b/admin/FOR-RELEASE @@ -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 ? diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 3c18de96d72..b66f82c5738 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,26 @@ +2012-01-23 Chong Yidong + + * 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 * intro.texi (A Sample Function Description): Special notation diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index e74f3e198bf..0511f21007d 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -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 diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 0b8d972c1d5..1555b98e7fb 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -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 diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index adb4841a82d..fc18e503543 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -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 diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index eb9ddf58603..c8433c79b54 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -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 diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 0ea32f99e12..94f1bf666d2 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -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 diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 49199d3e32f..bbb75f1474d 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -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 diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index 866a63c4cd9..0ee22b905b6 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -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 +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 +@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{} # -(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. -- 2.39.2