annotate lispref/eval.texi @ 77428:c1d43f2a6032

(EMACS): This change was reverted, so delete this entry.
author Glenn Morris <rgm@gnu.org>
date Sun, 22 Apr 2007 20:18:30 +0000
parents 7bd09f792276
children a1e16e813aed 4ef881a120fe
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
75250
6d19c76d81c5 Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents: 71956
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2001, 2002, 2003,
6d19c76d81c5 Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents: 71956
diff changeset
4 @c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/eval
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @node Evaluation, Control Structures, Symbols, Top
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @cindex evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 @cindex interpreter
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 @cindex interpreter
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 @cindex value of expression
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 The @dfn{evaluation} of expressions in Emacs Lisp is performed by the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 @dfn{Lisp interpreter}---a program that receives a Lisp object as input
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 and computes its @dfn{value as an expression}. How it does this depends
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 on the data type of the object, according to rules described in this
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 chapter. The interpreter runs automatically to evaluate portions of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 your program, but can also be called explicitly via the Lisp primitive
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 function @code{eval}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 22419
diff changeset
22 @ifnottex
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 * Intro Eval:: Evaluation in the scheme of things.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 * Forms:: How various sorts of objects are evaluated.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 * Quoting:: Avoiding evaluation (to put constants in the program).
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
27 * Eval:: How to invoke the Lisp interpreter explicitly.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 @node Intro Eval
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 @section Introduction to Evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
33 The Lisp interpreter, or evaluator, is the program that computes
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 27193
diff changeset
34 the value of an expression that is given to it. When a function
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 written in Lisp is called, the evaluator computes the value of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 function by evaluating the expressions in the function body. Thus,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 running any Lisp program really means running the Lisp interpreter.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 How the evaluator handles an object depends primarily on the data
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 type of the object.
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 22419
diff changeset
41 @end ifnottex
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 @cindex forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
44 @cindex expression
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
45 A Lisp object that is intended for evaluation is called an
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46 @dfn{expression} or a @dfn{form}. The fact that expressions are data
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 objects and not merely text is one of the fundamental differences
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 between Lisp-like languages and typical programming languages. Any
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 object can be evaluated, but in practice only numbers, symbols, lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 and strings are evaluated very often.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 It is very common to read a Lisp expression and then evaluate the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 expression, but reading and evaluation are separate activities, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 either can be performed alone. Reading per se does not evaluate
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 anything; it converts the printed representation of a Lisp object to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 object itself. It is up to the caller of @code{read} whether this
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 object is a form to be evaluated, or serves some entirely different
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 purpose. @xref{Input Functions}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 Do not confuse evaluation with command key interpretation. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 editor command loop translates keyboard input into a command (an
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 interactively callable function) using the active keymaps, and then
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 uses @code{call-interactively} to invoke the command. The execution of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 the command itself involves evaluation if the command is written in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 Lisp, but that is not a part of command key interpretation itself.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 @xref{Command Loop}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 @cindex recursive evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 Evaluation is a recursive process. That is, evaluation of a form may
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 call @code{eval} to evaluate parts of the form. For example, evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 of a function call first evaluates each argument of the function call,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 and then evaluates each form in the function body. Consider evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 of the form @code{(car x)}: the subform @code{x} must first be evaluated
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 recursively, so that its value can be passed as an argument to the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 function @code{car}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
77 Evaluation of a function call ultimately calls the function specified
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
78 in it. @xref{Functions}. The execution of the function may itself work
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
79 by evaluating the function definition; or the function may be a Lisp
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
80 primitive implemented in C, or it may be a byte-compiled function
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
81 (@pxref{Byte Compilation}).
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
82
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 @cindex environment
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 The evaluation of forms takes place in a context called the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 @dfn{environment}, which consists of the current values and bindings of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 all Lisp variables.@footnote{This definition of ``environment'' is
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
87 specifically not intended to include all the data that can affect the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
88 result of a program.} Whenever a form refers to a variable without
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
89 creating a new binding for it, the value of the variable's binding in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
90 the current environment is used. @xref{Variables}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 @cindex side effect
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 Evaluation of a form may create new environments for recursive
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 evaluation by binding variables (@pxref{Local Variables}). These
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 environments are temporary and vanish by the time evaluation of the form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 is complete. The form may also make changes that persist; these changes
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 are called @dfn{side effects}. An example of a form that produces side
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 effects is @code{(setq foo 1)}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 The details of what evaluation means for each kind of form are
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 described below (@pxref{Forms}).
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 @node Forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 @section Kinds of Forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 A Lisp object that is intended to be evaluated is called a @dfn{form}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 How Emacs evaluates a form depends on its data type. Emacs has three
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 different kinds of form that are evaluated differently: symbols, lists,
71956
1caee6e0cbe1 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 68761
diff changeset
109 and ``all other types.'' This section describes all three kinds, one by
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
110 one, starting with the ``all other types'' which are self-evaluating
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
111 forms.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 @menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 * Self-Evaluating Forms:: Forms that evaluate to themselves.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 * Symbol Forms:: Symbols evaluate as variables.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 * Classifying Lists:: How to distinguish various sorts of list forms.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 * Function Indirection:: When a symbol appears as the car of a list,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 we find the real function via the symbol.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 * Function Forms:: Forms that call functions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 * Macro Forms:: Forms that call macros.
71956
1caee6e0cbe1 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 68761
diff changeset
121 * Special Forms:: "Special forms" are idiosyncratic primitives,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 most of them extremely important.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 * Autoloading:: Functions set up to load files
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 containing their real definitions.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 @end menu
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 @node Self-Evaluating Forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 @subsection Self-Evaluating Forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 @cindex vector evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 @cindex literal evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @cindex self-evaluating form
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 A @dfn{self-evaluating form} is any form that is not a list or symbol.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 Self-evaluating forms evaluate to themselves: the result of evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 is the same object that was evaluated. Thus, the number 25 evaluates to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 25, and the string @code{"foo"} evaluates to the string @code{"foo"}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 Likewise, evaluation of a vector does not cause evaluation of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 elements of the vector---it returns the same vector with its contents
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 unchanged.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 @group
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
143 '123 ; @r{A number, shown without evaluation.}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 @result{} 123
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
145 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
146 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 123 ; @r{Evaluated as usual---result is the same.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 @result{} 123
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 (eval '123) ; @r{Evaluated ``by hand''---result is the same.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 @result{} 123
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 (eval (eval '123)) ; @r{Evaluating twice changes nothing.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 @result{} 123
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 It is common to write numbers, characters, strings, and even vectors
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 in Lisp code, taking advantage of the fact that they self-evaluate.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 However, it is quite unusual to do this for types that lack a read
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
163 syntax, because there's no way to write them textually. It is possible
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
164 to construct Lisp expressions containing these types by means of a Lisp
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
165 program. Here is an example:
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 ;; @r{Build an expression containing a buffer object.}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
170 (setq print-exp (list 'print (current-buffer)))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 @result{} (print #<buffer eval.texi>)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 ;; @r{Evaluate it.}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
175 (eval print-exp)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 @print{} #<buffer eval.texi>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 @result{} #<buffer eval.texi>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 @node Symbol Forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 @subsection Symbol Forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 @cindex symbol evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185 When a symbol is evaluated, it is treated as a variable. The result
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 is the variable's value, if it has one. If it has none (if its value
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
187 cell is void), an error is signaled. For more information on the use of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 variables, see @ref{Variables}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190 In the following example, we set the value of a symbol with
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 @code{setq}. Then we evaluate the symbol, and get back the value that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 @code{setq} stored.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 (setq a 123)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 @result{} 123
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 (eval 'a)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 @result{} 123
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 @result{} 123
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 The symbols @code{nil} and @code{t} are treated specially, so that the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 value of @code{nil} is always @code{nil}, and the value of @code{t} is
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
211 always @code{t}; you cannot set or bind them to any other values. Thus,
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
212 these two symbols act like self-evaluating forms, even though
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
213 @code{eval} treats them like any other symbol. A symbol whose name
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
214 starts with @samp{:} also self-evaluates in the same way; likewise,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
215 its value ordinarily cannot be changed. @xref{Constant Variables}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 @node Classifying Lists
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 @subsection Classification of List Forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 @cindex list form evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 A form that is a nonempty list is either a function call, a macro
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 call, or a special form, according to its first element. These three
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 kinds of forms are evaluated in different ways, described below. The
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 remaining list elements constitute the @dfn{arguments} for the function,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 macro, or special form.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 The first step in evaluating a nonempty list is to examine its first
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 element. This element alone determines what kind of form the list is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 and how the rest of the list is to be processed. The first element is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 @emph{not} evaluated, as it would be in some Lisp dialects such as
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 Scheme.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 @node Function Indirection
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 @subsection Symbol Function Indirection
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 @cindex symbol function indirection
76994
7bd09f792276 Improve index entry. Remove redundant ones.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
236 @cindex indirection for functions
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 @cindex void function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 If the first element of the list is a symbol then evaluation examines
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 the symbol's function cell, and uses its contents instead of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 original symbol. If the contents are another symbol, this process,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 called @dfn{symbol function indirection}, is repeated until it obtains a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 non-symbol. @xref{Function Names}, for more information about using a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 symbol as a name for a function stored in the function cell of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 symbol.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 One possible consequence of this process is an infinite loop, in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 event that a symbol's function cell refers to the same symbol. Or a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 symbol may have a void function cell, in which case the subroutine
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 @code{symbol-function} signals a @code{void-function} error. But if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 neither of these things happens, we eventually obtain a non-symbol,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 which ought to be a function or other suitable object.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 @kindex invalid-function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 More precisely, we should now have a Lisp function (a lambda
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256 expression), a byte-code function, a primitive function, a Lisp macro, a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 special form, or an autoload object. Each of these types is a case
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 described in one of the following sections. If the object is not one of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 these types, the error @code{invalid-function} is signaled.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 The following example illustrates the symbol indirection process. We
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 use @code{fset} to set the function cell of a symbol and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 @code{symbol-function} to get the function cell contents
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 (@pxref{Function Cells}). Specifically, we store the symbol @code{car}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 into the function cell of @code{first}, and the symbol @code{first} into
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 the function cell of @code{erste}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 ;; @r{Build this function cell linkage:}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 ;; ------------- ----- ------- -------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 ;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 ;; ------------- ----- ------- -------
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 (symbol-function 'car)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 @result{} #<subr car>
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 (fset 'first 'car)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 @result{} car
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 (fset 'erste 'first)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 @result{} first
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 (erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 @result{} 1
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 By contrast, the following example calls a function without any symbol
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 function indirection, because the first element is an anonymous Lisp
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 function, not a symbol.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302 ((lambda (arg) (erste arg))
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 27193
diff changeset
303 '(1 2 3))
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 @result{} 1
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 @noindent
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
309 Executing the function itself evaluates its body; this does involve
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
310 symbol function indirection when calling @code{erste}.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 The built-in function @code{indirect-function} provides an easy way to
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 perform symbol function indirection explicitly.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @c Emacs 19 feature
68761
35eb90d9d028 (Function Indirection): Add NOERROR to indirect-function.
Kim F. Storm <storm@cua.dk>
parents: 68648
diff changeset
316 @defun indirect-function function &optional noerror
53479
22b1822fac7f (Function Indirection): Add anchor.
Luc Teirlinck <teirllm@auburn.edu>
parents: 53293
diff changeset
317 @anchor{Definition of indirect-function}
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 This function returns the meaning of @var{function} as a function. If
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 @var{function} is a symbol, then it finds @var{function}'s function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 definition and starts over with that value. If @var{function} is not a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 symbol, then it returns @var{function} itself.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322
68761
35eb90d9d028 (Function Indirection): Add NOERROR to indirect-function.
Kim F. Storm <storm@cua.dk>
parents: 68648
diff changeset
323 This function signals a @code{void-function} error if the final symbol
35eb90d9d028 (Function Indirection): Add NOERROR to indirect-function.
Kim F. Storm <storm@cua.dk>
parents: 68648
diff changeset
324 is unbound and optional argument @var{noerror} is @code{nil} or
35eb90d9d028 (Function Indirection): Add NOERROR to indirect-function.
Kim F. Storm <storm@cua.dk>
parents: 68648
diff changeset
325 omitted. Otherwise, if @var{noerror} is non-@code{nil}, it returns
35eb90d9d028 (Function Indirection): Add NOERROR to indirect-function.
Kim F. Storm <storm@cua.dk>
parents: 68648
diff changeset
326 @code{nil} if the final symbol is unbound.
35eb90d9d028 (Function Indirection): Add NOERROR to indirect-function.
Kim F. Storm <storm@cua.dk>
parents: 68648
diff changeset
327
35eb90d9d028 (Function Indirection): Add NOERROR to indirect-function.
Kim F. Storm <storm@cua.dk>
parents: 68648
diff changeset
328 It signals a @code{cyclic-function-indirection} error if there is a
35eb90d9d028 (Function Indirection): Add NOERROR to indirect-function.
Kim F. Storm <storm@cua.dk>
parents: 68648
diff changeset
329 loop in the chain of symbols.
53293
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
330
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 Here is how you could define @code{indirect-function} in Lisp:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 @smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 (defun indirect-function (function)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 (if (symbolp function)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 (indirect-function (symbol-function function))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 function))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 @end smallexample
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 @end defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 @node Function Forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 @subsection Evaluation of Function Forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 @cindex function form evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 @cindex function call
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
345
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 If the first element of a list being evaluated is a Lisp function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 object, byte-code object or primitive function object, then that list is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 a @dfn{function call}. For example, here is a call to the function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 @code{+}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 (+ 1 x)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
355 The first step in evaluating a function call is to evaluate the
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
356 remaining elements of the list from left to right. The results are the
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
357 actual argument values, one value for each list element. The next step
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
358 is to call the function with this list of arguments, effectively using
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
359 the function @code{apply} (@pxref{Calling Functions}). If the function
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
360 is written in Lisp, the arguments are used to bind the argument
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
361 variables of the function (@pxref{Lambda Expressions}); then the forms
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
362 in the function body are evaluated in order, and the value of the last
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
363 body form becomes the value of the function call.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 @node Macro Forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 @subsection Lisp Macro Evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 @cindex macro call evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 If the first element of a list being evaluated is a macro object, then
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370 the list is a @dfn{macro call}. When a macro call is evaluated, the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 elements of the rest of the list are @emph{not} initially evaluated.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372 Instead, these elements themselves are used as the arguments of the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 macro. The macro definition computes a replacement form, called the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 @dfn{expansion} of the macro, to be evaluated in place of the original
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 form. The expansion may be any sort of form: a self-evaluating
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
376 constant, a symbol, or a list. If the expansion is itself a macro call,
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 this process of expansion repeats until some other sort of form results.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
379 Ordinary evaluation of a macro call finishes by evaluating the
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
380 expansion. However, the macro expansion is not necessarily evaluated
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
381 right away, or at all, because other programs also expand macro calls,
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
382 and they may or may not evaluate the expansions.
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
383
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384 Normally, the argument expressions are not evaluated as part of
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 computing the macro expansion, but instead appear as part of the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
386 expansion, so they are computed when the expansion is evaluated.
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388 For example, given a macro defined as follows:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 (defmacro cadr (x)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 (list 'car (list 'cdr x)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 an expression such as @code{(cadr (assq 'handler list))} is a macro
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 call, and its expansion is:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 (car (cdr (assq 'handler list)))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 @noindent
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406 Note that the argument @code{(assq 'handler list)} appears in the
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 expansion.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 @xref{Macros}, for a complete description of Emacs Lisp macros.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 @node Special Forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412 @subsection Special Forms
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 @cindex special form evaluation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 A @dfn{special form} is a primitive function specially marked so that
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 its arguments are not all evaluated. Most special forms define control
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 structures or perform variable bindings---things which functions cannot
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 do.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 Each special form has its own rules for which arguments are evaluated
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 and which are used without evaluation. Whether a particular argument is
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 evaluated may depend on the results of evaluating other arguments.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 Here is a list, in alphabetical order, of all of the special forms in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 Emacs Lisp with a reference to where each is described.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427 @table @code
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 @item and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 @pxref{Combining Conditions}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 @item catch
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 @pxref{Catch and Throw}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 @item cond
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 @pxref{Conditionals}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 @item condition-case
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 @pxref{Handling Errors}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 @item defconst
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 @pxref{Defining Variables}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 @item defmacro
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 @pxref{Defining Macros}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 @item defun
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @pxref{Defining Functions}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 @item defvar
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 @pxref{Defining Variables}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 @item function
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 @pxref{Anonymous Functions}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 @item if
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 @pxref{Conditionals}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 @item interactive
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 @pxref{Interactive Call}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @item let
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 @itemx let*
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 @pxref{Local Variables}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @item or
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 @pxref{Combining Conditions}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 @item prog1
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 @itemx prog2
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 @itemx progn
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 @pxref{Sequencing}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473 @item quote
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474 @pxref{Quoting}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
476 @item save-current-buffer
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
477 @pxref{Current Buffer}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
478
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 @item save-excursion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 @pxref{Excursions}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 @item save-restriction
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 @pxref{Narrowing}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 @item save-window-excursion
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 @pxref{Window Configurations}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488 @item setq
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 @pxref{Setting Variables}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 @item setq-default
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 @pxref{Creating Buffer-Local}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 @item track-mouse
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 @pxref{Mouse Tracking}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
497 @item unwind-protect
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
498 @pxref{Nonlocal Exits}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
499
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 @item while
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501 @pxref{Iteration}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
502
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
503 @item with-output-to-temp-buffer
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504 @pxref{Temporary Displays}
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505 @end table
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 @cindex CL note---special forms compared
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
508 @quotation
7119
19bd3bfc57de entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 6558
diff changeset
509 @b{Common Lisp note:} Here are some comparisons of special forms in
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510 GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511 @code{catch} are special forms in both Emacs Lisp and Common Lisp.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 @code{defun} is a special form in Emacs Lisp, but a macro in Common
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513 Lisp. @code{save-excursion} is a special form in Emacs Lisp, but
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514 doesn't exist in Common Lisp. @code{throw} is a special form in
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 Common Lisp (because it must be able to throw multiple values), but it
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516 is a function in Emacs Lisp (which doesn't have multiple
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 values).@refill
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518 @end quotation
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 @node Autoloading
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 @subsection Autoloading
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 The @dfn{autoload} feature allows you to call a function or macro
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524 whose function definition has not yet been loaded into Emacs. It
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 specifies which file contains the definition. When an autoload object
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 appears as a symbol's function definition, calling that symbol as a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 function automatically loads the specified file; then it calls the real
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528 definition loaded from that file. @xref{Autoload}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530 @node Quoting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531 @section Quoting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
533 The special form @code{quote} returns its single argument, as written,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
534 without evaluating it. This provides a way to include constant symbols
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
535 and lists, which are not self-evaluating objects, in a program. (It is
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
536 not necessary to quote self-evaluating objects such as numbers, strings,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
537 and vectors.)
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 @defspec quote object
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
540 This special form returns @var{object}, without evaluating it.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
541 @end defspec
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 @cindex @samp{'} for quoting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 @cindex quoting using apostrophe
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545 @cindex apostrophe for quoting
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 Because @code{quote} is used so often in programs, Lisp provides a
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 convenient read syntax for it. An apostrophe character (@samp{'})
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 followed by a Lisp object (in read syntax) expands to a list whose first
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
549 element is @code{quote}, and whose second element is the object. Thus,
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550 the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 Here are some examples of expressions that use @code{quote}:
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 @example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 (quote (+ 1 2))
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 @result{} (+ 1 2)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 (quote foo)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 @result{} foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 'foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 @result{} foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 ''foo
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 @result{} (quote foo)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 '(quote foo)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 @result{} (quote foo)
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 @group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 ['foo]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @result{} [(quote foo)]
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 @end group
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 @end example
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 Other quoting constructs include @code{function} (@pxref{Anonymous
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 Functions}), which causes an anonymous lambda expression written in Lisp
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
583 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
6558
fa8ff07eaafc Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 only part of a list, while computing and substituting other parts.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
585
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
586 @node Eval
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
587 @section Eval
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
588
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
589 Most often, forms are evaluated automatically, by virtue of their
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
590 occurrence in a program being run. On rare occasions, you may need to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
591 write code that evaluates a form that is computed at run time, such as
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
592 after reading a form from text being edited or getting one from a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
593 property list. On these occasions, use the @code{eval} function.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
594
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
595 The functions and variables described in this section evaluate forms,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
596 specify limits to the evaluation process, or record recently returned
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
597 values. Loading a file also does evaluation (@pxref{Loading}).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
598
52626
fe75563f4d13 Avoid @strong{Note:}.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
599 It is generally cleaner and more flexible to store a function in a
fe75563f4d13 Avoid @strong{Note:}.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
600 data structure, and call it with @code{funcall} or @code{apply}, than
fe75563f4d13 Avoid @strong{Note:}.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
601 to store an expression in the data structure and evaluate it. Using
fe75563f4d13 Avoid @strong{Note:}.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
602 functions provides the ability to pass information to them as
fe75563f4d13 Avoid @strong{Note:}.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
603 arguments.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
604
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
605 @defun eval form
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
606 This is the basic function evaluating an expression. It evaluates
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
607 @var{form} in the current environment and returns the result. How the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
608 evaluation proceeds depends on the type of the object (@pxref{Forms}).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
609
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
610 Since @code{eval} is a function, the argument expression that appears
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
611 in a call to @code{eval} is evaluated twice: once as preparation before
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
612 @code{eval} is called, and again by the @code{eval} function itself.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
613 Here is an example:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
614
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
615 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
616 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
617 (setq foo 'bar)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
618 @result{} bar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
619 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
620 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
621 (setq bar 'baz)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
622 @result{} baz
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
623 ;; @r{Here @code{eval} receives argument @code{foo}}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
624 (eval 'foo)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
625 @result{} bar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
626 ;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
627 (eval foo)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
628 @result{} baz
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
629 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
630 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
631
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
632 The number of currently active calls to @code{eval} is limited to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
633 @code{max-lisp-eval-depth} (see below).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
634 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
635
56215
c9aa4127a482 Reposition @anchor's.
Luc Teirlinck <teirllm@auburn.edu>
parents: 55734
diff changeset
636 @deffn Command eval-region start end &optional stream read-function
53293
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
637 @anchor{Definition of eval-region}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
638 This function evaluates the forms in the current buffer in the region
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
639 defined by the positions @var{start} and @var{end}. It reads forms from
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
640 the region and calls @code{eval} on them until the end of the region is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
641 reached, or until an error is signaled and not handled.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
642
53293
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
643 By default, @code{eval-region} does not produce any output. However,
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
644 if @var{stream} is non-@code{nil}, any output produced by output
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
645 functions (@pxref{Output Functions}), as well as the values that
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
646 result from evaluating the expressions in the region are printed using
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
647 @var{stream}. @xref{Output Streams}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
648
53293
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
649 If @var{read-function} is non-@code{nil}, it should be a function,
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
650 which is used instead of @code{read} to read expressions one by one.
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
651 This function is called with one argument, the stream for reading
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
652 input. You can also use the variable @code{load-read-function}
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
653 (@pxref{Definition of load-read-function,, How Programs Do Loading})
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
654 to specify this function, but it is more robust to use the
22419
3967db186db6 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
655 @var{read-function} argument.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
656
53293
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
657 @code{eval-region} does not move point. It always returns @code{nil}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
658 @end deffn
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
659
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
660 @cindex evaluation of buffer contents
53293
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
661 @deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
662 This is similar to @code{eval-region}, but the arguments provide
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
663 different optional features. @code{eval-buffer} operates on the
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
664 entire accessible portion of buffer @var{buffer-or-name}.
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
665 @var{buffer-or-name} can be a buffer, a buffer name (a string), or
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
666 @code{nil} (or omitted), which means to use the current buffer.
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
667 @var{stream} is used as in @code{eval-region}, unless @var{stream} is
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
668 @code{nil} and @var{print} non-@code{nil}. In that case, values that
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
669 result from evaluating the expressions are still discarded, but the
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
670 output of the output functions is printed in the echo area.
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
671 @var{filename} is the file name to use for @code{load-history}
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
672 (@pxref{Unloading}), and defaults to @code{buffer-file-name}
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
673 (@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil},
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
674 @code{read} converts strings to unibyte whenever possible.
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
675
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
676 @findex eval-current-buffer
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
677 @code{eval-current-buffer} is an alias for this command.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
678 @end deffn
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
679
56215
c9aa4127a482 Reposition @anchor's.
Luc Teirlinck <teirllm@auburn.edu>
parents: 55734
diff changeset
680 @defvar max-lisp-eval-depth
53293
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
681 @anchor{Definition of max-lisp-eval-depth}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
682 This variable defines the maximum depth allowed in calls to @code{eval},
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
683 @code{apply}, and @code{funcall} before an error is signaled (with error
55734
93c897de7898 (Eval): Increasing max-lisp-eval-depth can cause real stack overflow.
Richard M. Stallman <rms@gnu.org>
parents: 53479
diff changeset
684 message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).
93c897de7898 (Eval): Increasing max-lisp-eval-depth can cause real stack overflow.
Richard M. Stallman <rms@gnu.org>
parents: 53479
diff changeset
685
93c897de7898 (Eval): Increasing max-lisp-eval-depth can cause real stack overflow.
Richard M. Stallman <rms@gnu.org>
parents: 53479
diff changeset
686 This limit, with the associated error when it is exceeded, is one way
93c897de7898 (Eval): Increasing max-lisp-eval-depth can cause real stack overflow.
Richard M. Stallman <rms@gnu.org>
parents: 53479
diff changeset
687 Emacs Lisp avoids infinite recursion on an ill-defined function. If
93c897de7898 (Eval): Increasing max-lisp-eval-depth can cause real stack overflow.
Richard M. Stallman <rms@gnu.org>
parents: 53479
diff changeset
688 you increase the value of @code{max-lisp-eval-depth} too much, such
93c897de7898 (Eval): Increasing max-lisp-eval-depth can cause real stack overflow.
Richard M. Stallman <rms@gnu.org>
parents: 53479
diff changeset
689 code can cause stack overflow instead.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
690 @cindex Lisp nesting error
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
691
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
692 The depth limit counts internal uses of @code{eval}, @code{apply}, and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
693 @code{funcall}, such as for calling the functions mentioned in Lisp
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
694 expressions, and recursive evaluation of function call arguments and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
695 function body forms, as well as explicit calls in Lisp code.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
696
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
697 The default value of this variable is 300. If you set it to a value
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
698 less than 100, Lisp will reset it to 100 if the given value is reached.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
699 Entry to the Lisp debugger increases the value, if there is little room
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
700 left, to make sure the debugger itself has room to execute.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
701
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
702 @code{max-specpdl-size} provides another limit on nesting.
53293
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
703 @xref{Definition of max-specpdl-size,, Local Variables}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
704 @end defvar
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
705
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
706 @defvar values
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
707 The value of this variable is a list of the values returned by all the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
708 expressions that were read, evaluated, and printed from buffers
53293
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
709 (including the minibuffer) by the standard Emacs commands which do
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
710 this. (Note that this does @emph{not} include evaluation in
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
711 @samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
712 @code{lisp-interaction-mode}.) The elements are ordered most recent
66f89280d7be (Function Indirection): Describe the errors that `indirect-function'
Luc Teirlinck <teirllm@auburn.edu>
parents: 52626
diff changeset
713 first.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
714
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
715 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
716 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
717 (setq x 1)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
718 @result{} 1
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
719 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
720 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
721 (list 'A (1+ 2) auto-save-default)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
722 @result{} (A 3 t)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
723 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
724 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
725 values
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
726 @result{} ((A 3 t) 1 @dots{})
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
727 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
728 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
729
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
730 This variable is useful for referring back to values of forms recently
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
731 evaluated. It is generally a bad idea to print the value of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
732 @code{values} itself, since this may be very long. Instead, examine
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
733 particular elements, like this:
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
734
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
735 @example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
736 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
737 ;; @r{Refer to the most recent evaluation result.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
738 (nth 0 values)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
739 @result{} (A 3 t)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
740 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
741 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
742 ;; @r{That put a new element on,}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
743 ;; @r{so all elements move back one.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
744 (nth 1 values)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
745 @result{} (A 3 t)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
746 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
747 @group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
748 ;; @r{This gets the element that was next-to-most-recent}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
749 ;; @r{before this example.}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
750 (nth 3 values)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
751 @result{} 1
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
752 @end group
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
753 @end example
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 12098
diff changeset
754 @end defvar
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
755
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
756 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
757 arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
758 @end ignore