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

Initial revision

Browse source
This commit is contained in:
Richard M. Stallman 1994-03-28 20:21:44 +00:00
parent f142f62a0a
commit 73804d4b1b
10 changed files with 11959 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

120
lispref/Makefile.in Normal file
View file

@ -0,0 +1,120 @@
# Makefile for the GNU Emacs Lisp Reference Manual.
#
# 11 August 1990
# Redefine `TEX' if `tex' does not invoke plain TeX. For example:
# TEX=platex
TEX=tex
# Where the TeX macros are kept:
texmacrodir = /usr/local/lib/tex/macros
# Where the Emacs hierarchy lives ($EMACS in the INSTALL document for Emacs.)
# For example:
# emacslibdir = /usr/local/gnu/lib/emacs
# Directory where Emacs is installed, by default:
emacslibdir = /usr/local/emacs
# Unless you have a nonstandard Emacs installation, these shouldn't have to
# be changed.
prefix = /usr/local
infodir = ${prefix}/info
# The name of the manual:
VERSION=2.02.2
manual = elisp-manual-19-$(VERSION)
# Uncomment this line for permuted index.
# permuted_index = 1
# List of all the texinfo files in the manual:
srcs = elisp.texi back.texi \
abbrevs.texi anti.texi backups.texi locals.texi buffers.texi \
calendar.texi commands.texi compile.texi control.texi debugging.texi \
display.texi edebug.texi errors.texi eval.texi files.texi \
frames.texi functions.texi help.texi hooks.texi \
internals.texi intro.texi keymaps.texi lists.texi \
loading.texi macros.texi maps.texi markers.texi \
minibuf.texi modes.texi numbers.texi objects.texi \
os.texi positions.texi processes.texi searching.texi \
sequences.texi streams.texi strings.texi symbols.texi \
syntax.texi text.texi tips.texi variables.texi \
windows.texi \
index.unperm index.perm
.PHONY: elisp.dvi clean
elisp.dvi: $(srcs) index.texi texindex
# Avoid losing old contents of aux file entirely.
-mv elisp.aux elisp.oaux
# First shot to define xrefs:
$(TEX) elisp.texi
if [ a${permuted_index} != a ]; \
then \
./permute-index; \
mv permuted.fns elisp.fns; \
else \
./texindex elisp.??; \
fi
$(TEX) elisp.texi
index.texi:
if [ a${permuted_index} != a ]; \
then \
ln -s index.perm index.texi; \
else \
ln -s index.unperm index.texi; \
fi
# The info file is named `elisp'.
elisp: $(srcs) index.texi makeinfo
./makeinfo elisp.texi
install: elisp elisp.dvi
mv elisp elisp-* $(infodir)
@echo also add the line for elisp to $(infodir)/dir.
installall: install
install -c texinfo.tex $(texmacrodir)
clean:
rm -f *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \
*.vr *.vrs *.pg *.pgs *.ky *.kys
rm -f make.out core
rm -f makeinfo.o makeinfo getopt.o getopt1.o
rm -f texindex.o texindex index.texi
dist:
-mkdir temp
-mkdir temp/$(manual)
-ln README Makefile permute-index $(srcs) \
texinfo.tex getopt.c getopt1.c getopt.h \
elisp.dvi elisp.aux elisp.??s elisp elisp-[0-9] elisp-[0-9][0-9] temp/$(manual)
-rm -f temp/$(manual)/texindex.c temp/$(manual)/makeinfo.c
cp texindex.c makeinfo.c temp/$(manual)
(cd temp/$(manual); rm -f *~)
(cd temp; tar chf - $(manual)) | gzip > $(manual).tar.gz
-rm -rf temp
# Make two programs used in generating output from texinfo.
CFLAGS = -g
texindex: texindex.o
$(CC) -o $@ $(LDFLAGS) $(CFLAGS) $?
texindex.o: texindex.c
MAKEINFO_MAJOR = 1
MAKEINFO_MINOR = 0
MAKEINFO_FLAGS = -DMAKEINFO_MAJOR=$(MAKEINFO_MAJOR) -DMAKEINFO_MINOR=$(MAKEINFO_MINOR)
makeinfo: makeinfo.o getopt.o getopt1.o
$(CC) $(LDFLAGS) -o makeinfo makeinfo.o getopt.o getopt1.o
makeinfo.o: makeinfo.c
$(CC) -c $(CFLAGS) $(MAKEINFO_FLAGS) makeinfo.c

701
lispref/debugging.texi Normal file
View file

@ -0,0 +1,701 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/debugging
@node Debugging, Streams, Byte Compilation, Top
@chapter Debugging Lisp Programs
There are three ways to investigate a problem in an Emacs Lisp program,
depending on what you are doing with the program when the problem appears.
@itemize @bullet
@item
If the problem occurs when you run the program, you can use a Lisp
debugger (either the default debugger or Edebug) to investigate what is
happening during execution.
@item
If the problem is syntactic, so that Lisp cannot even read the program,
you can use the Emacs facilities for editing Lisp to localize it.
@item
If the problem occurs when trying to compile the program with the byte
compiler, you need to know how to examine the compiler's input buffer.
@end itemize
@menu
* Debugger:: How the Emacs Lisp debugger is implemented.
* Syntax Errors:: How to find syntax errors.
* Compilation Errors:: How to find errors that show up in byte compilation.
* Edebug:: A source-level Emacs Lisp debugger.
@end menu
Another useful debugging tool is the dribble file. When a dribble
file is open, Emacs copies all keyboard input characters to that file.
Afterward, you can examine the file to find out what input was used.
@xref{Terminal Input}.
For debugging problems in terminal descriptions, the
@code{open-termscript} function can be useful. @xref{Terminal Output}.
@node Debugger
@section The Lisp Debugger
@cindex debugger
@cindex Lisp debugger
@cindex break
The @dfn{Lisp debugger} provides the ability to suspend evaluation of
a form. While evaluation is suspended (a state that is commonly known
as a @dfn{break}), you may examine the run time stack, examine the
values of local or global variables, or change those values. Since a
break is a recursive edit, all the usual editing facilities of Emacs are
available; you can even run programs that will enter the debugger
recursively. @xref{Recursive Editing}.
@menu
* Error Debugging:: Entering the debugger when an error happens.
* Infinite Loops:: Stopping and debugging a program that doesn't exit.
* Function Debugging:: Entering it when a certain function is called.
* Explicit Debug:: Entering it at a certain point in the program.
* Using Debugger:: What the debugger does; what you see while in it.
* Debugger Commands:: Commands used while in the debugger.
* Invoking the Debugger:: How to call the function @code{debug}.
* Internals of Debugger:: Subroutines of the debugger, and global variables.
@end menu
@node Error Debugging
@subsection Entering the Debugger on an Error
@cindex error debugging
@cindex debugging errors
The most important time to enter the debugger is when a Lisp error
happens. This allows you to investigate the immediate causes of the
error.
However, entry to the debugger is not a normal consequence of an
error. Many commands frequently get Lisp errors when invoked in
inappropriate contexts (such as @kbd{C-f} at the end of the buffer) and
during ordinary editing it would be very unpleasant to enter the
debugger each time this happens. If you want errors to enter the
debugger, set the variable @code{debug-on-error} to non-@code{nil}.
@defopt debug-on-error
This variable determines whether the debugger is called when a error is
signaled and not handled. If @code{debug-on-error} is @code{t}, all
errors call the debugger. If it is @code{nil}, none call the debugger.
The value can also be a list of error conditions that should call the
debugger. For example, if you set it to the list
@code{(void-variable)}, then only errors about a variable that has no
value invoke the debugger.
@end defopt
To debug an error that happens during loading of the @file{.emacs}
file, use the option @samp{-debug-init}, which binds
@code{debug-on-error} to @code{t} while @file{.emacs} is loaded.
If your @file{.emacs} file sets @code{debug-on-error}, the effect
lasts only until the end of loading @file{.emacs}. (This is an
undesirable by-product of the @samp{-debug-init} feature.) If you want
@file{.emacs} to set @code{debug-on-error} permanently, use
@code{after-init-hook}, like this:
@example
(add-hook 'after-init-hook
'(lambda () (setq debug-on-error t)))
@end example
@node Infinite Loops
@subsection Debugging Infinite Loops
@cindex infinite loops
@cindex loops, infinite
@cindex quitting from infinite loop
@cindex stopping an infinite loop
When a program loops infinitely and fails to return, your first
problem is to stop the loop. On most operating systems, you can do this
with @kbd{C-g}, which causes quit.
Ordinary quitting gives no information about why the program was
looping. To get more information, you can set the variable
@code{debug-on-quit} to non-@code{nil}. Quitting with @kbd{C-g} is not
considered an error, and @code{debug-on-error} has no effect on the
handling of @kbd{C-g}. Contrariwise, @code{debug-on-quit} has no effect
on errors.@refill
Once you have the debugger running in the middle of the infinite loop,
you can proceed from the debugger using the stepping commands. If you
step through the entire loop, you will probably get enough information
to solve the problem.
@defopt debug-on-quit
This variable determines whether the debugger is called when @code{quit}
is signaled and not handled. If @code{debug-on-quit} is non-@code{nil},
then the debugger is called whenever you quit (that is, type @kbd{C-g}).
If @code{debug-on-quit} is @code{nil}, then the debugger is not called
when you quit. @xref{Quitting}.
@end defopt
@node Function Debugging
@subsection Entering the Debugger on a Function Call
@cindex function call debugging
@cindex debugging specific functions
To investigate a problem that happens in the middle of a program, one
useful technique is to enter the debugger whenever a certain function is
called. You can do this to the function in which the problem occurs,
and then step through the function, or you can do this to a function
called shortly before the problem, step quickly over the call to that
function, and then step through its caller.
@deffn Command debug-on-entry function-name
This function requests @var{function-name} to invoke the debugger each time
it is called. It works by inserting the form @code{(debug 'debug)} into
the function definition as the first form.
Any function defined as Lisp code may be set to break on entry,
regardless of whether it is interpreted code or compiled code. If the
function is a command, it will enter the debugger when called from Lisp
and when called interactively (after the reading of the arguments). You
can't debug primitive functions (i.e., those written in C) this way.
When @code{debug-on-entry} is called interactively, it prompts
for @var{function-name} in the minibuffer.
If the function is already set up to invoke the debugger on entry,
@code{debug-on-entry} does nothing.
Caveat: if you redefine a function after using @code{debug-on-entry}
on it, the code to enter the debugger is lost.
@code{debug-on-entry} returns @var{function-name}.
@example
@group
(defun fact (n)
(if (zerop n) 1
(* n (fact (1- n)))))
@result{} fact
@end group
@group
(debug-on-entry 'fact)
@result{} fact
@end group
@group
(fact 3)
@result{} 6
@end group
@group
------ Buffer: *Backtrace* ------
Entering:
* fact(3)
eval-region(4870 4878 t)
byte-code("...")
eval-last-sexp(nil)
(let ...)
eval-insert-last-sexp(nil)
* call-interactively(eval-insert-last-sexp)
------ Buffer: *Backtrace* ------
@end group
@group
(symbol-function 'fact)
@result{} (lambda (n)
(debug (quote debug))
(if (zerop n) 1 (* n (fact (1- n)))))
@end group
@end example
@end deffn
@deffn Command cancel-debug-on-entry function-name
This function undoes the effect of @code{debug-on-entry} on
@var{function-name}. When called interactively, it prompts for
@var{function-name} in the minibuffer.
If @code{cancel-debug-on-entry} is called more than once on the same
function, the second call does nothing. @code{cancel-debug-on-entry}
returns @var{function-name}.
@end deffn
@node Explicit Debug
@subsection Explicit Entry to the Debugger
You can cause the debugger to be called at a certain point in your
program by writing the expression @code{(debug)} at that point. To do
this, visit the source file, insert the text @samp{(debug)} at the
proper place, and type @kbd{C-M-x}. Be sure to undo this insertion
before you save the file!
The place where you insert @samp{(debug)} must be a place where an
additional form can be evaluated and its value ignored. (If the value
isn't ignored, it will alter the execution of the program!) The most
common suitable places are inside a @code{progn} or an implicit
@code{progn} (@pxref{Sequencing}).
@node Using Debugger
@subsection Using the Debugger
When the debugger is entered, it displays the previously selected
buffer in one window and a buffer named @samp{*Backtrace*} in another
window. The backtrace buffer contains one line for each level of Lisp
function execution currently going on. At the beginning of this buffer
is a message describing the reason that the debugger was invoked (such
as the error message and associated data, if it was invoked due to an
error).
The backtrace buffer is read-only and uses a special major mode,
Debugger mode, in which letters are defined as debugger commands. The
usual Emacs editing commands are available; thus, you can switch windows
to examine the buffer that was being edited at the time of the error,
switch buffers, visit files, or do any other sort of editing. However,
the debugger is a recursive editing level (@pxref{Recursive Editing})
and it is wise to go back to the backtrace buffer and exit the debugger
(with the @kbd{q} command) when you are finished with it. Exiting
the debugger gets out of the recursive edit and kills the backtrace
buffer.
@cindex current stack frame
The contents of the backtrace buffer show you the functions that are
executing and their argument values. It also allows you to specify a
stack frame by moving point to the line describing that frame. (A stack
frame is the place where the Lisp interpreter records information about
a particular invocation of a function.) The frame whose line point is
on is considered the @dfn{current frame}. Some of the debugger commands
operate on the current frame.
The debugger itself must be run byte-compiled, since it makes
assumptions about how many stack frames are used for the debugger
itself. These assumptions are false if the debugger is running
interpreted.
@need 3000
@node Debugger Commands
@subsection Debugger Commands
@cindex debugger command list
Inside the debugger (in Debugger mode), these special commands are
available in addition to the usual cursor motion commands. (Keep in
mind that all the usual facilities of Emacs, such as switching windows
or buffers, are still available.)
The most important use of debugger commands is for stepping through
code, so that you can see how control flows. The debugger can step
through the control structures of an interpreted function, but cannot do
so in a byte-compiled function. If you would like to step through a
byte-compiled function, replace it with an interpreted definition of the
same function. (To do this, visit the source file for the function and
type @kbd{C-M-x} on its definition.)
Here is a list of Debugger mode commands:
@table @kbd
@item c
Exit the debugger and continue execution. When continuing is possible,
it resumes execution of the program as if the debugger had never been
entered (aside from the effect of any variables or data structures you
may have changed while inside the debugger).
Continuing is possible after entry to the debugger due to function entry
or exit, explicit invocation, or quitting. You cannot continue if the
debugger was entered because of an error.
@item d
Continue execution, but enter the debugger the next time any Lisp
function is called. This allows you to step through the
subexpressions of an expression, seeing what values the subexpressions
compute, and what else they do.
The stack frame made for the function call which enters the debugger in
this way will be flagged automatically so that the debugger will be
called again when the frame is exited. You can use the @kbd{u} command
to cancel this flag.
@item b
Flag the current frame so that the debugger will be entered when the
frame is exited. Frames flagged in this way are marked with stars
in the backtrace buffer.
@item u
Don't enter the debugger when the current frame is exited. This
cancels a @kbd{b} command on that frame.
@item e
Read a Lisp expression in the minibuffer, evaluate it, and print the
value in the echo area. The debugger alters certain important variables
as part of its operation; @kbd{e} temporarily restores their
outside-the-debugger values so you can examine them. This makes the
debugger more transparent. By contrast, @kbd{M-@key{ESC}} does nothing
special in the debugger; it shows you the variable values within the
debugger.
@item q
Terminate the program being debugged; return to top-level Emacs
command execution.
If the debugger was entered due to a @kbd{C-g} but you really want
to quit, and not debug, use the @kbd{q} command.
@item r
Return a value from the debugger. The value is computed by reading an
expression with the minibuffer and evaluating it.
The @kbd{r} command makes a difference when the debugger was invoked due
to exit from a Lisp call frame (as requested with @kbd{b}); then the
value specified in the @kbd{r} command is used as the value of that
frame.
You can't use @kbd{r} when the debugger was entered due to an error.
@end table
@node Invoking the Debugger
@subsection Invoking the Debugger
Here we describe fully the function used to invoke the debugger.
@defun debug &rest debugger-args
This function enters the debugger. It switches buffers to a buffer
named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second
recursive entry to the debugger, etc.), and fills it with information
about the stack of Lisp function calls. It then enters a recursive
edit, showing the backtrace buffer in Debugger mode.
The Debugger mode @kbd{c} and @kbd{r} commands exit the recursive edit;
then @code{debug} switches back to the previous buffer and returns to
whatever called @code{debug}. This is the only way the function
@code{debug} can return to its caller.
If the first of the @var{debugger-args} passed to @code{debug} is
@code{nil} (or if it is not one of the special values in the table
below), then @code{debeg} displays the rest of its arguments at the the
top of the @samp{*Backtrace*} buffer. This mechanism is used to display
a message to the user.
However, if the first argument passed to @code{debug} is one of the
following special values, then it has special significance. Normally,
these values are passed to @code{debug} only by the internals of Emacs
and the debugger, and not by programmers calling @code{debug}.
The special values are:
@table @code
@item lambda
@cindex @code{lambda} in debug
A first argument of @code{lambda} means @code{debug} was called because
of entry to a function when @code{debug-on-next-call} was
non-@code{nil}. The debugger displays @samp{Entering:} as a line of
text at the top of the buffer.
@item debug
@code{debug} as first argument indicates a call to @code{debug} because
of entry to a function that was set to debug on entry. The debugger
displays @samp{Entering:}, just as in the @code{lambda} case. It also
marks the stack frame for that function so that it will invoke the
debugger when exited.
@item t
When the first argument is @code{t}, this indicates a call to
@code{debug} due to evaluation of a list form when
@code{debug-on-next-call} is non-@code{nil}. The debugger displays the
following as the top line in the buffer:
@smallexample
Beginning evaluation of function call form:
@end smallexample
@item exit
When the first argument is @code{exit}, it indicates the exit of a
stack frame previously marked to invoke the debugger on exit. The
second argument given to @code{debug} in this case is the value being
returned from the frame. The debugger displays @samp{Return value:} on
the top line of the buffer, followed by the value being returned.
@item error
@cindex @code{error} in debug
When the first argument is @code{error}, the debugger indicates that
it is being entered because an error or @code{quit} was signaled and not
handled, by displaying @samp{Signaling:} followed by the error signaled
and any arguments to @code{signal}. For example,
@example
@group
(let ((debug-on-error t))
(/ 1 0))
@end group
@group
------ Buffer: *Backtrace* ------
Signaling: (arith-error)
/(1 0)
...
------ Buffer: *Backtrace* ------
@end group
@end example
If an error was signaled, presumably the variable
@code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled,
then presumably the variable @code{debug-on-quit} is non-@code{nil}.
@item nil
Use @code{nil} as the first of the @var{debugger-args} when you want
to enter the debugger explicitly. The rest of the @var{debugger-args}
are printed on the top line of the buffer. You can use this feature to
display messages---for example, to remind yourself of the conditions
under which @code{debug} is called.
@end table
@end defun
@need 5000
@node Internals of Debugger
@subsection Internals of the Debugger
This section describes functions and variables used internally by the
debugger.
@defvar debugger
The value of this variable is the function to call to invoke the
debugger. Its value must be a function of any number of arguments (or,
more typically, the name of a function). Presumably this function will
enter some kind of debugger. The default value of the variable is
@code{debug}.
The first argument that Lisp hands to the function indicates why it
was called. The convention for arguments is detailed in the description
of @code{debug}.
@end defvar
@deffn Command backtrace
@cindex run time stack
@cindex call stack
This function prints a trace of Lisp function calls currently active.
This is the function used by @code{debug} to fill up the
@samp{*Backtrace*} buffer. It is written in C, since it must have access
to the stack to determine which function calls are active. The return
value is always @code{nil}.
In the following example, a Lisp expression calls @code{backtrace}
explicitly. This prints the backtrace to the stream
@code{standard-output}: in this case, to the buffer
@samp{backtrace-output}. Each line of the backtrace represents one
function call. The line shows the values of the function's arguments if
they are all known. If they are still being computed, the line says so.
The arguments of special forms are elided.
@smallexample
@group
(with-output-to-temp-buffer "backtrace-output"
(let ((var 1))
(save-excursion
(setq var (eval '(progn
(1+ var)
(list 'testing (backtrace))))))))
@result{} nil
@end group
@group
----------- Buffer: backtrace-output ------------
backtrace()
(list ...computing arguments...)
(progn ...)
eval((progn (1+ var) (list (quote testing) (backtrace))))
(setq ...)
(save-excursion ...)
(let ...)
(with-output-to-temp-buffer ...)
eval-region(1973 2142 #<buffer *scratch*>)
byte-code("... for eval-print-last-sexp ...")
eval-print-last-sexp(nil)
* call-interactively(eval-print-last-sexp)
----------- Buffer: backtrace-output ------------
@end group
@end smallexample
The character @samp{*} indicates a frame whose debug-on-exit flag is
set.
@end deffn
@ignore @c Not worth mentioning
@defopt stack-trace-on-error
@cindex stack trace
This variable controls whether Lisp automatically displays a
backtrace buffer after every error that is not handled. A quit signal
counts as an error for this variable. If it is non-@code{nil} then a
backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every
error. If it is @code{nil}, then a backtrace is not shown.
When a backtrace is shown, that buffer is not selected. If either
@code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then
a backtrace is shown in one buffer, and the debugger is popped up in
another buffer with its own backtrace.
We consider this feature to be obsolete and superseded by the debugger
itself.
@end defopt
@end ignore
@defvar debug-on-next-call
@cindex @code{eval}, and debugging
@cindex @code{apply}, and debugging
@cindex @code{funcall}, and debugging
If this variable is non-@code{nil}, it says to call the debugger before
the next @code{eval}, @code{apply} or @code{funcall}. Entering the
debugger sets @code{debug-on-next-call} to @code{nil}.
The @kbd{d} command in the debugger works by setting this variable.
@end defvar
@defun backtrace-debug level flag
This function sets the debug-on-exit flag of the stack frame @var{level}
levels, giving it the value @var{flag}. If @var{flag} is
non-@code{nil}, this will cause the debugger to be entered when that
frame later exits. Even a nonlocal exit through that frame will enter
the debugger.
Normally, this function is only called by the debugger.
@end defun
@defvar command-debug-status
This variable records the debugging status of current interactive
command. Each time a command is called interactively, this variable is
bound to @code{nil}. The debugger can set this variable to leave
information for future debugger invocations during the same command.
The advantage of using this variable rather that defining another global
variable is that the data will never carry over to a subsequent command
invocation.
@end defvar
@defun backtrace-frame frame-number
The function @code{backtrace-frame} is intended for use in Lisp
debuggers. It returns information about what computation is happening
in the stack frame @var{frame-number} levels down.
If that frame has not evaluated the arguments yet (or is a special
form), the value is @code{(nil @var{function} @var{arg-forms}@dots{})}.
If that frame has evaluated its arguments and called its function
already, the value is @code{(t @var{function}
@var{arg-values}@dots{})}.
In the return value, @var{function} is whatever was supplied as @sc{car}
of evaluated list, or a @code{lambda} expression in the case of a macro
call. If the function has a @code{&rest} argument, that is represented
as the tail of the list @var{arg-values}.
If the argument is out of range, @code{backtrace-frame} returns
@code{nil}.
@end defun
@node Syntax Errors
@section Debugging Invalid Lisp Syntax
The Lisp reader reports invalid syntax, but cannot say where the real
problem is. For example, the error ``End of file during parsing'' in
evaluating an expression indicates an excess of open parentheses (or
square brackets). The reader detects this imbalance at the end of the
file, but it cannot figure out where the close parenthesis should have
been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close
parenthesis or missing open parenthesis, but does not say where the
missing parenthesis belongs. How, then, to find what to change?
If the problem is not simply an imbalance of parentheses, a useful
technique is to try @kbd{C-M-e} at the beginning of each defun, and see
if it goes to the place where that defun appears to end. If it does
not, there is a problem in that defun.
However, unmatched parentheses are the most common syntax errors in
Lisp, and we can give further advice for those cases.
@menu
* Excess Open:: How to find a spurious open paren or missing close.
* Excess Close:: How to find a spurious close paren or missing open.
@end menu
@node Excess Open
@subsection Excess Open Parentheses
The first step is to find the defun that is unbalanced. If there is
an excess open parenthesis, the way to do this is to insert a
close parenthesis at the end of the file and type @kbd{C-M-b}
(@code{backward-sexp}). This will move you to the beginning of the
defun that is unbalanced. (Then type @kbd{C-@key{SPC} C-_ C-u
C-@key{SPC}} to set the mark there, undo the insertion of the
close parenthesis, and finally return to the mark.)
The next step is to determine precisely what is wrong. There is no
way to be sure of this except to study the program, but often the
existing indentation is a clue to where the parentheses should have
been. The easiest way to use this clue is to reindent with @kbd{C-M-q}
and see what moves.
Before you do this, make sure the defun has enough close parentheses.
Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest
of the file until the end. So move to the end of the defun and insert a
close parenthesis there. Don't use @kbd{C-M-e} to move there, since
that too will fail to work until the defun is balanced.
Now you can go to the beginning of the defun and type @kbd{C-M-q}.
Usually all the lines from a certain point to the end of the function
will shift to the right. There is probably a missing close parenthesis,
or a superfluous open parenthesis, near that point. (However, don't
assume this is true; study the code to make sure.) Once you have found
the discrepancy, undo the @kbd{C-M-q}, since the old indentation is
probably appropriate to the intended parentheses.
After you think you have fixed the problem, use @kbd{C-M-q} again. If
the old indentation actually fit the intended nesting of parentheses,
and you have put back those parentheses, @kbd{C-M-q} should not change
anything.
@node Excess Close
@subsection Excess Close Parentheses
To deal with an excess close parenthesis, first insert an
open parenthesis at the beginning of the file and type @kbd{C-M-f} to
find the end of the unbalanced defun. (Then type @kbd{C-@key{SPC} C-_
C-u C-@key{SPC}} to set the mark there, undo the insertion of the
open parenthesis, and finally return to the mark.)
Then find the actual matching close parenthesis by typing @kbd{C-M-f}
at the beginning of the defun. This will leave you somewhere short of
the place where the defun ought to end. It is possible that you will
find a spurious close parenthesis in that vicinity.
If you don't see a problem at that point, the next thing to do is to
type @kbd{C-M-q} at the beginning of the defun. A range of lines will
probably shift left; if so, the missing open parenthesis or spurious
close parenthesis is probably near the first of those lines. (However,
don't assume this is true; study the code to make sure.) Once you have
found the discrepancy, undo the @kbd{C-M-q}, since the old indentation
is probably appropriate to the intended parentheses.
@node Compilation Errors
@section Debugging Problems in Compilation
When an error happens during byte compilation, it is normally due to
invalid syntax in the program you are compiling. The compiler prints a
suitable error message in the @samp{*Compile-Log*} buffer, and then
stops. The message may state a function name in which the error was
found, or it may not. Either way, here is how to find out where in the
file the error occurred.
What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}.
(Note that the buffer name starts with a space, so it does not show
up in @kbd{M-x list-buffers}.) This buffer contains the program being
compiled, and point shows how far the byte compiler was able to read.
If the error was due to invalid Lisp syntax, point shows exactly where
the invalid syntax was @emph{detected}. The cause of the error is not
necessarily near by! Use the techniques in the previous section to find
the error.
If the error was detected while compiling a form that had been read
successfully, then point is located at the end of the form. In this
case, it can't localize the error precisely, but can still show you
which function to check.
@include edebug.texi

1676
lispref/edebug.texi Normal file
View file

File diff suppressed because it is too large Load diff

695
lispref/eval.texi Normal file
View file

@ -0,0 +1,695 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/eval
@node Evaluation, Control Structures, Symbols, Top
@chapter Evaluation
@cindex evaluation
@cindex interpreter
@cindex interpreter
@cindex value of expression
The @dfn{evaluation} of expressions in Emacs Lisp is performed by the
@dfn{Lisp interpreter}---a program that receives a Lisp object as input
and computes its @dfn{value as an expression}. How it does this depends
on the data type of the object, according to rules described in this
chapter. The interpreter runs automatically to evaluate portions of
your program, but can also be called explicitly via the Lisp primitive
function @code{eval}.
@ifinfo
@menu
* Intro Eval:: Evaluation in the scheme of things.
* Eval:: How to invoke the Lisp interpreter explicitly.
* Forms:: How various sorts of objects are evaluated.
* Quoting:: Avoiding evaluation (to put constants in the program).
@end menu
@node Intro Eval
@section Introduction to Evaluation
The Lisp interpreter, or evaluator, is the program which computes
the value of an expression which is given to it. When a function
written in Lisp is called, the evaluator computes the value of the
function by evaluating the expressions in the function body. Thus,
running any Lisp program really means running the Lisp interpreter.
How the evaluator handles an object depends primarily on the data
type of the object.
@end ifinfo
@cindex forms
@cindex expression
A Lisp object which is intended for evaluation is called an
@dfn{expression} or a @dfn{form}. The fact that expressions are data
objects and not merely text is one of the fundamental differences
between Lisp-like languages and typical programming languages. Any
object can be evaluated, but in practice only numbers, symbols, lists
and strings are evaluated very often.
It is very common to read a Lisp expression and then evaluate the
expression, but reading and evaluation are separate activities, and
either can be performed alone. Reading per se does not evaluate
anything; it converts the printed representation of a Lisp object to the
object itself. It is up to the caller of @code{read} whether this
object is a form to be evaluated, or serves some entirely different
purpose. @xref{Input Functions}.
Do not confuse evaluation with command key interpretation. The
editor command loop translates keyboard input into a command (an
interactively callable function) using the active keymaps, and then
uses @code{call-interactively} to invoke the command. The execution of
the command itself involves evaluation if the command is written in
Lisp, but that is not a part of command key interpretation itself.
@xref{Command Loop}.
@cindex recursive evaluation
Evaluation is a recursive process. That is, evaluation of a form may
call @code{eval} to evaluate parts of the form. For example, evaluation
of a function call first evaluates each argument of the function call,
and then evaluates each form in the function body. Consider evaluation
of the form @code{(car x)}: the subform @code{x} must first be evaluated
recursively, so that its value can be passed as an argument to the
function @code{car}.
@cindex environment
The evaluation of forms takes place in a context called the
@dfn{environment}, which consists of the current values and bindings of
all Lisp variables.@footnote{This definition of ``environment'' is
specifically not intended to include all the data which can affect the
result of a program.} Whenever the form refers to a variable without
creating a new binding for it, the value of the binding in the current
environment is used. @xref{Variables}.
@cindex side effect
Evaluation of a form may create new environments for recursive
evaluation by binding variables (@pxref{Local Variables}). These
environments are temporary and vanish by the time evaluation of the form
is complete. The form may also make changes that persist; these changes
are called @dfn{side effects}. An example of a form that produces side
effects is @code{(setq foo 1)}.
Finally, evaluation of one particular function call, @code{byte-code},
invokes the @dfn{byte-code interpreter} on its arguments. Although the
byte-code interpreter is not the same as the Lisp interpreter, it uses
the same environment as the Lisp interpreter, and may on occasion invoke
the Lisp interpreter. (@xref{Byte Compilation}.)
The details of what evaluation means for each kind of form are
described below (@pxref{Forms}).
@node Eval
@section Eval
Most often, forms are evaluated automatically, by virtue of their
occurrence in a program being run. On rare occasions, you may need to
write code that evaluates a form that is computed at run time, such as
after reading a form from text being edited or getting one from a
property list. On these occasions, use the @code{eval} function.
The functions and variables described in this section evaluate
forms, specify limits to the evaluation process, or record recently
returned values. Loading a file also does evaluation
(@pxref{Loading}).
@defun eval form
This is the basic function for performing evaluation. It evaluates
@var{form} in the current environment and returns the result. How the
evaluation proceeds depends on the type of the object (@pxref{Forms}).
Since @code{eval} is a function, the argument expression that appears
in a call to @code{eval} is evaluated twice: once as preparation before
@code{eval} is called, and again by the @code{eval} function itself.
Here is an example:
@example
@group
(setq foo 'bar)
@result{} bar
@end group
@group
(setq bar 'baz)
@result{} baz
;; @r{@code{eval} receives argument @code{bar}, which is the value of @code{foo}}
(eval foo)
@result{} baz
@end group
@end example
The number of currently active calls to @code{eval} is limited to
@code{max-lisp-eval-depth} (see below).
@end defun
@cindex evaluation of buffer contents
@deffn Command eval-current-buffer &optional stream
This function evaluates the forms in the current buffer. It reads
forms from the buffer and calls @code{eval} on them until the end of the
buffer is reached, or until an error is signaled and not handled.
If @var{stream} is supplied, the variable @code{standard-output} is
bound to @var{stream} during the evaluation (@pxref{Output
Functions}).
@code{eval-current-buffer} always returns @code{nil}.
@end deffn
@deffn Command eval-region start end &optional stream
This function evaluates the forms in the current buffer in the region
defined by the positions @var{start} and @var{end}. It reads forms from
the region and calls @code{eval} on them until the end of the region is
reached, or until an error is signaled and not handled.
If @var{stream} is supplied, @code{standard-output} is bound to it
for the duration of the command.
@code{eval-region} always returns @code{nil}.
@end deffn
@defvar max-lisp-eval-depth
This variable defines the maximum depth allowed in calls to @code{eval},
@code{apply}, and @code{funcall} before an error is signaled (with error
message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This counts
calling the functions mentioned in Lisp expression, and recursive
evaluation of function call arguments and function body forms.
This limit, with the associated error when it is exceeded, is one way
that Lisp avoids infinite recursion on an ill-defined function.
@cindex Lisp nesting error
The default value of this variable is 200. If you set it to a value
less than 100, Lisp will reset it to 100 if the given value is reached.
@code{max-specpdl-size} provides another limit on nesting.
@xref{Local Variables}.
@end defvar
@defvar values
The value of this variable is a list of the values returned by all the
expressions which were read from buffers (including the minibuffer),
evaluated, and printed. The elements are ordered most recent first.
@example
@group
(setq x 1)
@result{} 1
@end group
@group
(list 'A (1+ 2) auto-save-default)
@result{} (A 3 t)
@end group
@group
values
@result{} ((A 3 t) 1 @dots{})
@end group
@end example
This variable is useful for referring back to values of forms recently
evaluated. It is generally a bad idea to print the value of
@code{values} itself, since this may be very long. Instead, examine
particular elements, like this:
@example
@group
;; @r{Refer to the most recent evaluation result.}
(nth 0 values)
@result{} (A 3 t)
@end group
@group
;; @r{That put a new element on,}
;; @r{so all elements move back one.}
(nth 1 values)
@result{} (A 3 t)
@end group
@group
;; @r{This gets the element that was next-to-last}
;; @r{before this example.}
(nth 3 values)
@result{} 1
@end group
@end example
@end defvar
@node Forms
@section Kinds of Forms
A Lisp object that is intended to be evaluated is called a @dfn{form}.
How Emacs evaluates a form depends on its data type. Emacs has three
different kinds of form that are evaluated differently: symbols, lists,
and ``all other types''. This section describes all three kinds,
starting with ``all other types'' which are self-evaluating forms.
@menu
* Self-Evaluating Forms:: Forms that evaluate to themselves.
* Symbol Forms:: Symbols evaluate as variables.
* Classifying Lists:: How to distinguish various sorts of list forms.
* Function Indirection:: When a symbol appears as the car of a list,
we find the real function via the symbol.
* Function Forms:: Forms that call functions.
* Macro Forms:: Forms that call macros.
* Special Forms:: ``Special forms'' are idiosyncratic primitives,
most of them extremely important.
* Autoloading:: Functions set up to load files
containing their real definitions.
@end menu
@node Self-Evaluating Forms
@subsection Self-Evaluating Forms
@cindex vector evaluation
@cindex literal evaluation
@cindex self-evaluating form
A @dfn{self-evaluating form} is any form that is not a list or symbol.
Self-evaluating forms evaluate to themselves: the result of evaluation
is the same object that was evaluated. Thus, the number 25 evaluates to
25, and the string @code{"foo"} evaluates to the string @code{"foo"}.
Likewise, evaluation of a vector does not cause evaluation of the
elements of the vector---it returns the same vector with its contents
unchanged.
@example
@group
'123 ; @r{An object, shown without evaluation.}
@result{} 123
@end group
@group
123 ; @r{Evaluated as usual---result is the same.}
@result{} 123
@end group
@group
(eval '123) ; @r{Evaluated ``by hand''---result is the same.}
@result{} 123
@end group
@group
(eval (eval '123)) ; @r{Evaluating twice changes nothing.}
@result{} 123
@end group
@end example
It is common to write numbers, characters, strings, and even vectors
in Lisp code, taking advantage of the fact that they self-evaluate.
However, it is quite unusual to do this for types that lack a read
syntax, because there's no way to write them textually; however, it is
possible to construct Lisp expressions containing these types by means
of a Lisp program. Here is an example:
@example
@group
;; @r{Build an expression containing a buffer object.}
(setq buffer (list 'print (current-buffer)))
@result{} (print #<buffer eval.texi>)
@end group
@group
;; @r{Evaluate it.}
(eval buffer)
@print{} #<buffer eval.texi>
@result{} #<buffer eval.texi>
@end group
@end example
@node Symbol Forms
@subsection Symbol Forms
@cindex symbol evaluation
When a symbol is evaluated, it is treated as a variable. The result
is the variable's value, if it has one. If it has none (if its value
cell is void), an error is signaled. For more information on the use of
variables, see @ref{Variables}.
In the following example, we set the value of a symbol with
@code{setq}. Then we evaluate the symbol, and get back the value that
@code{setq} stored.
@example
@group
(setq a 123)
@result{} 123
@end group
@group
(eval 'a)
@result{} 123
@end group
@group
a
@result{} 123
@end group
@end example
The symbols @code{nil} and @code{t} are treated specially, so that the
value of @code{nil} is always @code{nil}, and the value of @code{t} is
always @code{t}. Thus, these two symbols act like self-evaluating
forms, even though @code{eval} treats them like any other symbol.
@node Classifying Lists
@subsection Classification of List Forms
@cindex list form evaluation
A form that is a nonempty list is either a function call, a macro
call, or a special form, according to its first element. These three
kinds of forms are evaluated in different ways, described below. The
remaining list elements constitute the @dfn{arguments} for the function,
macro, or special form.
The first step in evaluating a nonempty list is to examine its first
element. This element alone determines what kind of form the list is
and how the rest of the list is to be processed. The first element is
@emph{not} evaluated, as it would be in some Lisp dialects such as
Scheme.
@node Function Indirection
@subsection Symbol Function Indirection
@cindex symbol function indirection
@cindex indirection
@cindex void function
If the first element of the list is a symbol then evaluation examines
the symbol's function cell, and uses its contents instead of the
original symbol. If the contents are another symbol, this process,
called @dfn{symbol function indirection}, is repeated until it obtains a
non-symbol. @xref{Function Names}, for more information about using a
symbol as a name for a function stored in the function cell of the
symbol.
One possible consequence of this process is an infinite loop, in the
event that a symbol's function cell refers to the same symbol. Or a
symbol may have a void function cell, in which case the subroutine
@code{symbol-function} signals a @code{void-function} error. But if
neither of these things happens, we eventually obtain a non-symbol,
which ought to be a function or other suitable object.
@kindex invalid-function
@cindex invalid function
More precisely, we should now have a Lisp function (a lambda
expression), a byte-code function, a primitive function, a Lisp macro, a
special form, or an autoload object. Each of these types is a case
described in one of the following sections. If the object is not one of
these types, the error @code{invalid-function} is signaled.
The following example illustrates the symbol indirection process. We
use @code{fset} to set the function cell of a symbol and
@code{symbol-function} to get the function cell contents
(@pxref{Function Cells}). Specifically, we store the symbol @code{car}
into the function cell of @code{first}, and the symbol @code{first} into
the function cell of @code{erste}.
@smallexample
@group
;; @r{Build this function cell linkage:}
;; ------------- ----- ------- -------
;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
;; ------------- ----- ------- -------
@end group
@end smallexample
@smallexample
@group
(symbol-function 'car)
@result{} #<subr car>
@end group
@group
(fset 'first 'car)
@result{} car
@end group
@group
(fset 'erste 'first)
@result{} first
@end group
@group
(erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.}
@result{} 1
@end group
@end smallexample
By contrast, the following example calls a function without any symbol
function indirection, because the first element is an anonymous Lisp
function, not a symbol.
@smallexample
@group
((lambda (arg) (erste arg))
'(1 2 3))
@result{} 1
@end group
@end smallexample
@noindent
After that function is called, its body is evaluated; this does
involve symbol function indirection when calling @code{erste}.
The built-in function @code{indirect-function} provides an easy way to
perform symbol function indirection explicitly.
@c Emacs 19 feature
@defun indirect-function function
This function returns the meaning of @var{function} as a function. If
@var{function} is a symbol, then it finds @var{function}'s function
definition and starts over with that value. If @var{function} is not a
symbol, then it returns @var{function} itself.
Here is how you could define @code{indirect-function} in Lisp:
@smallexample
(defun indirect-function (function)
(if (symbolp function)
(indirect-function (symbol-function function))
function))
@end smallexample
@end defun
@node Function Forms
@subsection Evaluation of Function Forms
@cindex function form evaluation
@cindex function call
If the first element of a list being evaluated is a Lisp function
object, byte-code object or primitive function object, then that list is
a @dfn{function call}. For example, here is a call to the function
@code{+}:
@example
(+ 1 x)
@end example
The first step ni evaluating a function call is to evaluate the
remaining elements of the list in the order they appear. The results
are the actual argument values, one value for each list element. The
next step is to call the function with this list of arguments,
effectively using the function @code{apply} (@pxref{Calling Functions}).
If the function is written in Lisp, the arguments are used to bind the
argument variables of the function (@pxref{Lambda Expressions}); then
the forms in the function body are evaluated in order, and the value of
the last body form becomes the value of the function call.
@node Macro Forms
@subsection Lisp Macro Evaluation
@cindex macro call evaluation
If the first element of a list being evaluated is a macro object, then
the list is a @dfn{macro call}. When a macro call is evaluated, the
elements of the rest of the list are @emph{not} initially evaluated.
Instead, these elements themselves are used as the arguments of the
macro. The macro definition computes a replacement form, called the
@dfn{expansion} of the macro, to be evaluated in place of the original
form. The expansion may be any sort of form: a self-evaluating
constant, a symbol or a list. If the expansion is itself a macro call,
this process of expansion repeats until some other sort of form results.
Normally, the argument expressions are not evaluated as part of
computing the macro expansion, but instead appear as part of the
expansion, so they are evaluated when the expansion is evaluated.
For example, given a macro defined as follows:
@example
@group
(defmacro cadr (x)
(list 'car (list 'cdr x)))
@end group
@end example
@noindent
an expression such as @code{(cadr (assq 'handler list))} is a macro
call, and its expansion is:
@example
(car (cdr (assq 'handler list)))
@end example
@noindent
Note that the argument @code{(assq 'handler list)} appears in the
expansion.
@xref{Macros}, for a complete description of Emacs Lisp macros.
@node Special Forms
@subsection Special Forms
@cindex special form evaluation
A @dfn{special form} is a primitive function specially marked so that
its arguments are not all evaluated. Most special forms define control
structures or perform variable bindings---things which functions cannot
do.
Each special form has its own rules for which arguments are evaluated
and which are used without evaluation. Whether a particular argument is
evaluated may depend on the results of evaluating other arguments.
Here is a list, in alphabetical order, of all of the special forms in
Emacs Lisp with a reference to where each is described.
@table @code
@item and
@pxref{Combining Conditions}
@item catch
@pxref{Catch and Throw}
@item cond
@pxref{Conditionals}
@item condition-case
@pxref{Handling Errors}
@item defconst
@pxref{Defining Variables}
@item defmacro
@pxref{Defining Macros}
@item defun
@pxref{Defining Functions}
@item defvar
@pxref{Defining Variables}
@item function
@pxref{Anonymous Functions}
@item if
@pxref{Conditionals}
@item interactive
@pxref{Interactive Call}
@item let
@itemx let*
@pxref{Local Variables}
@item or
@pxref{Combining Conditions}
@item prog1
@itemx prog2
@itemx progn
@pxref{Sequencing}
@item quote
@pxref{Quoting}
@item save-excursion
@pxref{Excursions}
@item save-restriction
@pxref{Narrowing}
@item save-window-excursion
@pxref{Window Configurations}
@item setq
@pxref{Setting Variables}
@item setq-default
@pxref{Creating Buffer-Local}
@item track-mouse
@pxref{Mouse Tracking}
@item unwind-protect
@pxref{Nonlocal Exits}
@item while
@pxref{Iteration}
@item with-output-to-temp-buffer
@pxref{Temporary Displays}
@end table
@cindex CL note---special forms compared
@quotation
@b{Common Lisp note:} here are some comparisons of special forms in
GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and
@code{catch} are special forms in both Emacs Lisp and Common Lisp.
@code{defun} is a special form in Emacs Lisp, but a macro in Common
Lisp. @code{save-excursion} is a special form in Emacs Lisp, but
doesn't exist in Common Lisp. @code{throw} is a special form in
Common Lisp (because it must be able to throw multiple values), but it
is a function in Emacs Lisp (which doesn't have multiple
values).@refill
@end quotation
@node Autoloading
@subsection Autoloading
The @dfn{autoload} feature allows you to call a function or macro
whose function definition has not yet been loaded into Emacs. It
specifies which file contains the definition. When an autoload object
appears as a symbol's function definition, calling that symbol as a
function automatically loads the specified file; then it calls the real
definition loaded from that file. @xref{Autoload}.
@node Quoting
@section Quoting
@cindex quoting
The special form @code{quote} returns its single argument
``unchanged''.
@defspec quote object
This special form returns @var{object}, without evaluating it. This
provides a way to include constant symbols and lists, which are not
self-evaluating objects, in a program. (It is not necessary to quote
self-evaluating objects such as numbers, strings, and vectors.)
@cindex @samp{'} for quoting
@cindex quoting using apostrophe
@cindex apostrophe for quoting
Because @code{quote} is used so often in programs, Lisp provides a
convenient read syntax for it. An apostrophe character (@samp{'})
followed by a Lisp object (in read syntax) expands to a list whose first
element is @code{quote}, and whose second element is the object. Thus,
the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
Here are some examples of expressions that use @code{quote}:
@example
@group
(quote (+ 1 2))
@result{} (+ 1 2)
@end group
@group
(quote foo)
@result{} foo
@end group
@group
'foo
@result{} foo
@end group
@group
''foo
@result{} (quote foo)
@end group
@group
'(quote foo)
@result{} (quote foo)
@end group
@group
['foo]
@result{} [(quote foo)]
@end group
@end example
@end defspec
Other quoting constructs include @code{function} (@pxref{Anonymous
Functions}), which causes an anonymous lambda expression written in Lisp
to be compiled, and @code{`} (@pxref{Backquote}), which is used to quote
only part of a list, while computing and substituting other parts.

1638
lispref/keymaps.texi Normal file
View file

File diff suppressed because it is too large Load diff

1384
lispref/lists.texi Normal file
View file

File diff suppressed because it is too large Load diff

593
lispref/macros.texi Normal file
View file

@ -0,0 +1,593 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/macros
@node Macros, Loading, Functions, Top
@chapter Macros
@cindex macros
@dfn{Macros} enable you to define new control constructs and other
language features. A macro is defined much like a function, but instead
of telling how to compute a value, it tells how to compute another Lisp
expression which will in turn compute the value. We call this
expression the @dfn{expansion} of the macro.
Macros can do this because they operate on the unevaluated expressions
for the arguments, not on the argument values as functions do. They can
therefore construct an expansion containing these argument expressions
or parts of them.
If you are using a macro to do something an ordinary function could
do, just for the sake of speed, consider using an inline function
instead. @xref{Inline Functions}.
@menu
* Simple Macro:: A basic example.
* Expansion:: How, when and why macros are expanded.
* Compiling Macros:: How macros are expanded by the compiler.
* Defining Macros:: How to write a macro definition.
* Backquote:: Easier construction of list structure.
* Problems with Macros:: Don't evaluate the macro arguments too many times.
Don't hide the user's variables.
@end menu
@node Simple Macro
@section A Simple Example of a Macro
Suppose we would like to define a Lisp construct to increment a
variable value, much like the @code{++} operator in C. We would like to
write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}.
Here's a macro definition that does the job:
@findex inc
@example
@group
(defmacro inc (var)
(list 'setq var (list '1+ var)))
@end group
@end example
When this is called with @code{(inc x)}, the argument @code{var} has
the value @code{x}---@emph{not} the @emph{value} of @code{x}. The body
of the macro uses this to construct the expansion, which is @code{(setq
x (1+ x))}. Once the macro definition returns this expansion, Lisp
proceeds to evaluate it, thus incrementing @code{x}.
@node Expansion
@section Expansion of a Macro Call
@cindex expansion of macros
@cindex macro call
A macro call looks just like a function call in that it is a list which
starts with the name of the macro. The rest of the elements of the list
are the arguments of the macro.
Evaluation of the macro call begins like evaluation of a function call
except for one crucial difference: the macro arguments are the actual
expressions appearing in the macro call. They are not evaluated before
they are given to the macro definition. By contrast, the arguments of a
function are results of evaluating the elements of the function call
list.
Having obtained the arguments, Lisp invokes the macro definition just
as a function is invoked. The argument variables of the macro are bound
to the argument values from the macro call, or to a list of them in the
case of a @code{&rest} argument. And the macro body executes and
returns its value just as a function body does.
The second crucial difference between macros and functions is that the
value returned by the macro body is not the value of the macro call.
Instead, it is an alternate expression for computing that value, also
known as the @dfn{expansion} of the macro. The Lisp interpreter
proceeds to evaluate the expansion as soon as it comes back from the
macro.
Since the expansion is evaluated in the normal manner, it may contain
calls to other macros. It may even be a call to the same macro, though
this is unusual.
You can see the expansion of a given macro call by calling
@code{macroexpand}.
@defun macroexpand form &optional environment
@cindex macro expansion
This function expands @var{form}, if it is a macro call. If the result
is another macro call, it is expanded in turn, until something which is
not a macro call results. That is the value returned by
@code{macroexpand}. If @var{form} is not a macro call to begin with, it
is returned as given.
Note that @code{macroexpand} does not look at the subexpressions of
@var{form} (although some macro definitions may do so). Even if they
are macro calls themselves, @code{macroexpand} does not expand them.
The function @code{macroexpand} does not expand calls to inline functions.
Normally there is no need for that, since a call to an inline function is
no harder to understand than a call to an ordinary function.
If @var{environment} is provided, it specifies an alist of macro
definitions that shadow the currently defined macros. Byte compilation
uses this feature.
@smallexample
@group
(defmacro inc (var)
(list 'setq var (list '1+ var)))
@result{} inc
@end group
@group
(macroexpand '(inc r))
@result{} (setq r (1+ r))
@end group
@group
(defmacro inc2 (var1 var2)
(list 'progn (list 'inc var1) (list 'inc var2)))
@result{} inc2
@end group
@group
(macroexpand '(inc2 r s))
@result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.}
@end group
@end smallexample
@end defun
@node Compiling Macros
@section Macros and Byte Compilation
@cindex byte-compiling macros
You might ask why we take the trouble to compute an expansion for a
macro and then evaluate the expansion. Why not have the macro body
produce the desired results directly? The reason has to do with
compilation.
When a macro call appears in a Lisp program being compiled, the Lisp
compiler calls the macro definition just as the interpreter would, and
receives an expansion. But instead of evaluating this expansion, it
compiles the expansion as if it had appeared directly in the program.
As a result, the compiled code produces the value and side effects
intended for the macro, but executes at full compiled speed. This would
not work if the macro body computed the value and side effects
itself---they would be computed at compile time, which is not useful.
In order for compilation of macro calls to work, the macros must be
defined in Lisp when the calls to them are compiled. The compiler has a
special feature to help you do this: if a file being compiled contains a
@code{defmacro} form, the macro is defined temporarily for the rest of
the compilation of that file. To use this feature, you must define the
macro in the same file where it is used and before its first use.
Byte-compiling a file executes any @code{require} calls at top-level
in the file. This is in case the file needs the required packages for
proper compilation. One way to ensure that necessary macro definitions
are available during compilation is to require the file that defines
them. @xref{Features}.
@node Defining Macros
@section Defining Macros
A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should
be a function; expansion of the macro works by applying the function
(with @code{apply}) to the list of unevaluated argument-expressions
from the macro call.
It is possible to use an anonymous Lisp macro just like an anonymous
function, but this is never done, because it does not make sense to pass
an anonymous macro to mapping functions such as @code{mapcar}. In
practice, all Lisp macros have names, and they are usually defined with
the special form @code{defmacro}.
@defspec defmacro name argument-list body-forms@dots{}
@code{defmacro} defines the symbol @var{name} as a macro that looks
like this:
@example
(macro lambda @var{argument-list} . @var{body-forms})
@end example
This macro object is stored in the function cell of @var{name}. The
value returned by evaluating the @code{defmacro} form is @var{name}, but
usually we ignore this value.
The shape and meaning of @var{argument-list} is the same as in a
function, and the keywords @code{&rest} and @code{&optional} may be used
(@pxref{Argument List}). Macros may have a documentation string, but
any @code{interactive} declaration is ignored since macros cannot be
called interactively.
@end defspec
@node Backquote
@section Backquote
@cindex backquote (list substitution)
@cindex ` (list substitution)
Macros often need to construct large list structures from a mixture of
constants and nonconstant parts. To make this easier, use the macro
@code{`} (often called @dfn{backquote}).
Backquote allows you to quote a list, but selectively evaluate
elements of that list. In the simplest case, it is identical to the
special form @code{quote} (@pxref{Quoting}). For example, these
two forms yield identical results:
@example
@group
(` (a list of (+ 2 3) elements))
@result{} (a list of (+ 2 3) elements)
@end group
@group
(quote (a list of (+ 2 3) elements))
@result{} (a list of (+ 2 3) elements)
@end group
@end example
@findex , @{(with Backquote)}
The special marker, @code{,}, inside of the argument to backquote,
indicates a value that isn't constant. Backquote evaluates the
argument of @code{,} and puts the value in the list structure:
@example
@group
(list 'a 'list 'of (+ 2 3) 'elements)
@result{} (a list of 5 elements)
@end group
@group
(` (a list of (, (+ 2 3)) elements))
@result{} (a list of 5 elements)
@end group
@end example
@findex ,@@ @{(with Backquote)}
@cindex splicing (with backquote)
You can also @dfn{splice} an evaluated value into the resulting list,
using the special marker @code{,@@}. The elements of the spliced list
become elements at the same level as the other elements of the resulting
list. The equivalent code without using @code{`} is often unreadable.
Here are some examples:
@example
@group
(setq some-list '(2 3))
@result{} (2 3)
@end group
@group
(cons 1 (append some-list '(4) some-list))
@result{} (1 2 3 4 2 3)
@end group
@group
(` (1 (,@@ some-list) 4 (,@@ some-list)))
@result{} (1 2 3 4 2 3)
@end group
@group
(setq list '(hack foo bar))
@result{} (hack foo bar)
@end group
@group
(cons 'use
(cons 'the
(cons 'words (append (cdr list) '(as elements)))))
@result{} (use the words foo bar as elements)
@end group
@group
(` (use the words (,@@ (cdr list)) as elements))
@result{} (use the words foo bar as elements)
@end group
@end example
Emacs 18 had a bug which made the previous example fail. The bug
affected @code{,@@} followed only by constant elements. If you are
concerned with Emacs 18 compatibility, you can work around the bug like
this:
@example
(` (use the words (,@@ (cdr list)) as elements @code{(,@@ nil)}))
@end example
@noindent
@code{(,@@ nil)} avoids the problem by being a nonconstant element that
does not affect the result.
@defmac ` list
This macro quotes @var{list} except for any sublists of the form
@code{(, @var{subexp})} or @code{(,@@ @var{listexp})}. Backquote
replaces these sublists with the value of @var{subexp} (as a single
element) or @var{listexp} (by splicing). Backquote copies the structure
of @var{list} down to the places where variable parts are substituted.
@ignore @c these work now!
There are certain contexts in which @samp{,} would not be recognized and
should not be used:
@smallexample
@group
;; @r{Use of a @samp{,} expression as the @sc{cdr} of a list.}
(` (a . (, 1))) ; @r{Not @code{(a . 1)}}
@result{} (a \, 1)
@end group
@group
;; @r{Use of @samp{,} in a vector.}
(` [a (, 1) c]) ; @r{Not @code{[a 1 c]}}
@error{} Wrong type argument
@end group
@end smallexample
@end ignore
@end defmac
@cindex CL note---@samp{,}, @samp{,@@} as functions
@quotation
@b{Common Lisp note:} in Common Lisp, @samp{,} and @samp{,@@} are implemented
as reader macros, so they do not require parentheses. Emacs Lisp implements
them as functions because reader macros are not supported (to save space).
@end quotation
@node Problems with Macros
@section Common Problems Using Macros
The basic facts of macro expansion have counterintuitive consequences.
This section describes some important consequences that can lead to
trouble, and rules to follow to avoid trouble.
@menu
* Argument Evaluation:: The expansion should evaluate each macro arg once.
* Surprising Local Vars:: Local variable bindings in the expansion
require special care.
* Eval During Expansion:: Don't evaluate them; put them in the expansion.
* Repeated Expansion:: Avoid depending on how many times expansion is done.
@end menu
@node Argument Evaluation
@subsection Evaluating Macro Arguments Repeatedly
When defining a macro you must pay attention to the number of times
the arguments will be evaluated when the expansion is executed. The
following macro (used to facilitate iteration) illustrates the problem.
This macro allows us to write a simple ``for'' loop such as one might
find in Pascal.
@findex for
@smallexample
@group
(defmacro for (var from init to final do &rest body)
"Execute a simple \"for\" loop.
For example, (for i from 1 to 10 do (print i))."
(list 'let (list (list var init))
(cons 'while (cons (list '<= var final)
(append body (list (list 'inc var)))))))
@end group
@result{} for
@group
(for i from 1 to 3 do
(setq square (* i i))
(princ (format "\n%d %d" i square)))
@expansion{}
@end group
@group
(let ((i 1))
(while (<= i 3)
(setq square (* i i))
(princ (format "%d %d" i square))
(inc i)))
@end group
@group
@print{}1 1
@print{}2 4
@print{}3 9
@result{} nil
@end group
@end smallexample
@noindent
(The arguments @code{from}, @code{to}, and @code{do} in this macro are
``syntactic sugar''; they are entirely ignored. The idea is that you
will write noise words (such as @code{from}, @code{to}, and @code{do})
in those positions in the macro call.)
This macro suffers from the defect that @var{final} is evaluated on
every iteration. If @var{final} is a constant, this is not a problem.
If it is a more complex form, say @code{(long-complex-calculation x)},
this can slow down the execution significantly. If @var{final} has side
effects, executing it more than once is probably incorrect.
@cindex macro argument evaluation
A well-designed macro definition takes steps to avoid this problem by
producing an expansion that evaluates the argument expressions exactly
once unless repeated evaluation is part of the intended purpose of the
macro. Here is a correct expansion for the @code{for} macro:
@smallexample
@group
(let ((i 1)
(max 3))
(while (<= i max)
(setq square (* i i))
(princ (format "%d %d" i square))
(inc i)))
@end group
@end smallexample
Here is a macro definition that creates this expansion:
@smallexample
@group
(defmacro for (var from init to final do &rest body)
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
(` (let (((, var) (, init))
(max (, final)))
(while (<= (, var) max)
(,@@ body)
(inc (, var))))))
@end group
@end smallexample
Unfortunately, this introduces another problem.
@ifinfo
Proceed to the following node.
@end ifinfo
@node Surprising Local Vars
@subsection Local Variables in Macro Expansions
@ifinfo
In the previous section, the definition of @code{for} was fixed as
follows to make the expansion evaluate the macro arguments the proper
number of times:
@smallexample
@group
(defmacro for (var from init to final do &rest body)
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
@end group
@group
(` (let (((, var) (, init))
(max (, final)))
(while (<= (, var) max)
(,@@ body)
(inc (, var))))))
@end group
@end smallexample
@end ifinfo
The new definition of @code{for} has a new problem: it introduces a
local variable named @code{max} which the user does not expect. This
causes trouble in examples such as the following:
@example
@group
(let ((max 0))
(for x from 0 to 10 do
(let ((this (frob x)))
(if (< max this)
(setq max this)))))
@end group
@end example
@noindent
The references to @code{max} inside the body of the @code{for}, which
are supposed to refer to the user's binding of @code{max}, really access
the binding made by @code{for}.
The way to correct this is to use an uninterned symbol instead of
@code{max} (@pxref{Creating Symbols}). The uninterned symbol can be
bound and referred to just like any other symbol, but since it is created
by @code{for}, we know that it cannot appear in the user's program.
Since it is not interned, there is no way the user can put it into the
program later. It will never appear anywhere except where put by
@code{for}. Here is a definition of @code{for} which works this way:
@smallexample
@group
(defmacro for (var from init to final do &rest body)
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
(let ((tempvar (make-symbol "max")))
(` (let (((, var) (, init))
((, tempvar) (, final)))
(while (<= (, var) (, tempvar))
(,@@ body)
(inc (, var)))))))
@end group
@end smallexample
@noindent
This creates an uninterned symbol named @code{max} and puts it in the
expansion instead of the usual interned symbol @code{max} that appears
in expressions ordinarily.
@node Eval During Expansion
@subsection Evaluating Macro Arguments in Expansion
Another problem can happen if you evaluate any of the macro argument
expressions during the computation of the expansion, such as by calling
@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the
user's variables, you may have trouble if the user happens to use a
variable with the same name as one of the macro arguments. Inside the
macro body, the macro argument binding is the most local binding of this
variable, so any references inside the form being evaluated do refer
to it. Here is an example:
@example
@group
(defmacro foo (a)
(list 'setq (eval a) t))
@result{} foo
@end group
@group
(setq x 'b)
(foo x) @expansion{} (setq b t)
@result{} t ; @r{and @code{b} has been set.}
;; @r{but}
(setq a 'c)
(foo a) @expansion{} (setq a t)
@result{} t ; @r{but this set @code{a}, not @code{c}.}
@end group
@end example
It makes a difference whether the user's variable is named @code{a} or
@code{x}, because @code{a} conflicts with the macro argument variable
@code{a}.
Another reason not to call @code{eval} in a macro definition is that
it probably won't do what you intend in a compiled program. The
byte-compiler runs macro definitions while compiling the program, when
the program's own computations (which you might have wished to access
with @code{eval}) don't occur and its local variable bindings don't
exist.
The safe way to work with the run-time value of an expression is to
put the expression into the macro expansion, so that its value is
computed as part of executing the expansion.
@node Repeated Expansion
@subsection How Many Times is the Macro Expanded?
Occasionally problems result from the fact that a macro call is
expanded each time it is evaluated in an interpreted function, but is
expanded only once (during compilation) for a compiled function. If the
macro definition has side effects, they will work differently depending
on how many times the macro is expanded.
In particular, constructing objects is a kind of side effect. If the
macro is called once, then the objects are constructed only once. In
other words, the same structure of objects is used each time the macro
call is executed. In interpreted operation, the macro is reexpanded
each time, producing a fresh collection of objects each time. Usually
this does not matter---the objects have the same contents whether they
are shared or not. But if the surrounding program does side effects
on the objects, it makes a difference whether they are shared. Here is
an example:
@lisp
@group
(defmacro empty-object ()
(list 'quote (cons nil nil)))
@end group
@group
(defun initialize (condition)
(let ((object (empty-object)))
(if condition
(setcar object condition))
object))
@end group
@end lisp
@noindent
If @code{initialize} is interpreted, a new list @code{(nil)} is
constructed each time @code{initialize} is called. Thus, no side effect
survives between calls. If @code{initialize} is compiled, then the
macro @code{empty-object} is expanded during compilation, producing a
single ``constant'' @code{(nil)} that is reused and altered each time
@code{initialize} is called.
One way to avoid pathological cases like this is to think of
@code{empty-object} as a funny kind of constant, not as a memory
allocation construct. You wouldn't use @code{setcar} on a constant such
as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)}
either.

1355
lispref/os.texi Normal file
View file

File diff suppressed because it is too large Load diff

1139
lispref/processes.texi Normal file
View file

File diff suppressed because it is too large Load diff

2658
lispref/text.texi Normal file
View file

File diff suppressed because it is too large Load diff