|
DataMuseum.dkPresents historical artifacts from the history of: DKUUG/EUUG Conference tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about DKUUG/EUUG Conference tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: T l
Length: 53249 (0xd001)
Types: TextFile
Names: »lispref-7«
└─⟦a05ed705a⟧ Bits:30007078 DKUUG GNU 2/12/89
└─⟦c06c473ab⟧ »./UNRELEASED/lispref.tar.Z«
└─⟦1b57a2ffe⟧
└─⟦this⟧ »lispref-7«
Info file: lispref, -*-Text-*-
produced by texinfo-format-buffer
from file: lispref.texinfo
This file documents GNU Emacs Lisp.
This is Edition 0.1 Beta of the GNU Emacs Lisp Reference Manual, for
Emacs Version 18, with some references to Emacs Version 19.
Please read this document for review purposes.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1989 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.
▶1f◀
File: lispref Node: Function Forms, Prev: Classifying Lists, Up: Nonempty List Forms, Next: Macro Forms
Evaluation of Function Forms
----------------------------
If the first element of a list being evaluated is a Lisp function
object or primitive function object, then that form is called a
"function call". For example, this is a call to the function `+':
(+ 1 x)
When a function call is evaluated, first the elements of the rest of
the list are evaluated in the order they appear. Then the function is
called with this list of arguments, effectively using the function
`apply' to do this (*Note Calling Functions::). If the function is
written in Lisp, the arguments are used to bind the parameter variables
of the function (*Note Lambda Expressions::); then the forms in the
function body are evaluated in order, and the result of the last one is
used as the value of the function call.
▶1f◀
File: lispref Node: Macro Forms, Prev: Function Forms, Up: Nonempty List Forms, Next: Special Forms
Lisp Macro Evaluation
---------------------
If the first element of a list being evaluated is a macro object, then
that form is called a "macro call".
When a macro call is evaluated, the elements of the rest of the list
are *not* initially evaluated; instead, these elements themselves are
used as the arguments of the macro. The macro definition computes a
replacement form, called the "expansion" of the macro. Then the
expansion is 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:
(defmacro cadr (x)
(list 'car (list 'cdr x)))
an expression such as `(cadr (assq 'handler list))' is a macro call, and
its expansion is:
(car (cdr (assq 'handler list)))
Note that the argument `(assq 'handler list)' appears in the expansion,
as usual.
*Note Macros::, for the complete description of Emacs Lisp macros.
▶1f◀
File: lispref Node: Special Forms, Prev: Macro Forms, Up: Nonempty List Forms, Next: Autoloading
Special Forms
-------------
A "special form" is a primitive function specially marked so that its
arguments are not all evaluated. 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. Sometimes, whether a particular
argument is evaluated depends 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.
`and'
*Note Combining Conditions::
`catch'
*Note Catch and Throw::
`cond'
*Note Conditionals::
`condition-case'
*Note Errors::
`defvar'
*Note Global Variables::
`defmacro'
*Note Defining Macros::
`defun'
*Note Defining Functions::
`defvar'
*Note Defining Variables::
`if'
*Note Conditionals::
`function'
*Note Anonymous Functions::
`interactive'
*Note Interactive Call::
`let'
*Note Local Variables::
`let*'
*Note Local Variables::
`or'
*Note Combining Conditions::
`progn'
*Note Sequencing::
`prog1'
*Note Sequencing::
`prog2'
*Note Sequencing::
`quote'
*Note Quoting::
`save-excursion'
*Note Excursions::
`save-restriction'
*Note Clipping Restrictions::
`save-window-excursion'
*Note Window Configurations::
`setq'
*Note Setting Variables::
`setq-default'
*Note Buffer Local Variables::
`unwind-protect'
*Note Nonlocal Exits::
`while'
*Note Iteration:: `with-output-to-temp-buffer' *Note Temporary
Displays:: Common Lisp Note: Here are some comparisons of special
forms in GNU Emacs Lisp and Common Lisp: `setq', `if', and `catch'
are special forms in both Emacs Lisp and Common Lisp. `defun' is a
special form in Emacs Lisp, but a macro in Common Lisp.
`save-excursion' is a special form in Emacs Lisp, but doesn't exist
in Common Lisp. `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).
▶1f◀
File: lispref Node: Autoloading, Prev: Special Forms, Up: Nonempty List Forms
Autoloading
-----------
The "autoload" feature allows you to call a function or macro whose
function definition has not yet been loaded into Emacs. When an
autoload object appears as a symbol's function definition and that
symbol is used as a function, Emacs will automatically install the real
definition and its other associated code, and then call that definition.
(*Note Autoload::.)
▶1f◀
File: lispref Node: Quoting, Prev: Forms, Up: Evaluation
Quoting
=======
The special form `quote' returns its single argument ``unchanged''.
* Special form: quote OBJECT
This special form returns OBJECT, without evaluating it. This
allows symbols and lists, which would normally be evaluated, to be
included literally in a program. (It is not necessary to quote
numbers, strings, and vectors since they are self-evaluating.) Use
`function' instead of `quote' when quoting lambda expressions
(*Note Anonymous Functions::).
Because `quote' is used so often in programs, a convenient read
syntax is defined. An apostrophe character (`'') followed by a
form expands to a list whose first element is `quote', and whose
second element is the form.
(quote (+ 1 2))
=> (+ 1 2)
(quote foo)
=> foo
'foo
=> foo
''foo
=> (quote foo)
'(quote foo)
=> (quote foo)
['foo]
=> [(quote foo)]
▶1f◀
File: lispref Node: Loading, Prev: Evaluation, Up: Top, Next: Byte Compilation
Loading
*******
Loading a file of Lisp code means bringing the program into the Lisp
environment in the form of Lisp objects. Emacs finds and opens the
file, reads the contents of the file, evaluates each form within it, and
then closes the file.
Thus, the load functions evaluate all the expressions in a file just
as the `eval-current-buffer' function evaluates all the expressions in a
buffer. The difference is that the load functions read and evaluate the
text in the file as found on disk, not the text in an Emacs buffer.
The loaded file must contain Lisp expressions, either as source code
or, optionally, as byte-compiled code. Each form in the file is called
a "top-level form". There is no special format for the forms in a
loadable file; any form in a file may equally well be typed directly
into a buffer and evaluated there. (Indeed, most code is tested this
way.) Most often, the forms in a load file are function and variable
definitions.
* Menu:
* Loading Libraries:: Files containing code are called libraries.
* How Programs do Loading::
* Autoload::
* Features::
▶1f◀
File: lispref Node: Loading Libraries, Prev: Loading, Up: Loading, Next: How Programs do Loading
Lisp Libraries and Loading
==========================
A file containing Lisp code is often called a "library". Thus, the
`Rmail library' is a file containing code for reading mail. Similarly,
a `Lisp library directory' is a directory of files containing Lisp code.
You may load a file more than once in an Emacs session. For example,
after you have rewritten and reinstalled a function definition by
editing it in a buffer, you may wish to return to the original version;
you can do this by reloading the file in which it is located.
However, when you load or re-load files, bear in mind that the `load'
and `load-library' functions automatically load a byte-compiled file
rather than a non-compiled file of similar name. If you rewrite a file
that you intend to save and reinstall, remember to byte-compile it if
necessary; otherwise you may find yourself inadvertently reloading the
older, byte-compiled file instead of your newer, non-compiled file!
There are several interface functions for loading. For example, the
`autoload' function creates a Lisp object that loads a file when it is
evaluated (*Note Autoload::). `require' also causes automatic loading
(*Note Features::). Ultimately, all these facilities call the `load'
function to do the work.
Any errors that are encountered while loading a file cause `load' to
abort. If the load was done for the sake of `autoload', certain kinds
of top-level forms, those which define functions, are undone.
To learn how `load' is used to build Emacs, *Note Building Emacs::.
▶1f◀
File: lispref Node: How Programs do Loading, Prev: Loading Libraries, Up: Loading, Next: Autoload
How Programs do Loading
=======================
* Function: load FILENAME &optional MISSING-OK NOMESSAGE NOSUFFIX
This function finds and opens a file of Lisp code, executes all
the forms in it, and closes the file.
To find the file,
`load' first looks for a file named `FILENAME.elc', that is, for
a file whose name has `.elc' appended. If such a file exists, it
is loaded. But if there is no file by that name, then `load' looks
for a file whose name has `.el' appended. If that file exists, it
is loaded. Finally, if there is no file by either name, `load'
looks for a file named FILENAME with nothing appended, and loads it
if it exists. (The `load' function is not clever about looking at
FILENAME. In the perverse case of a file named `foo.el.el',
evaluation of `(load "foo.el")' will indeed find it.)
If the optional argument NOSUFFIX is non-`nil', then the suffixes
`.elc' and `.el' are not tried. In this case, the filename must be
specified precisely.
If FILENAME is a relative path, such as `foo.bar' or
`baz/foo.bar', Emacs searches for the file using the variable
`load-path'. Emacs does this by appending the relative path to
each of the directories listed in `load-path', and loading the
first file it finds whose name matches. The current working
directory is tried only if it is specified in `load-path', where it
is represented as `nil'.
When FILENAME is a relative file name, all three possible
filenames are tried in the first directory in `load-path', then all
three in the second directory in `load-path', etc.
Messages like `Loading foo.el ...' and `Loading foo.el ... done'
are printed in the echo area while loading unless NOMESSAGE is
non-`nil'.
The error `file-error' is signaled (with `Cannot open load file
FILENAME') if no file is found. No error is signaled if MISSING-OK
is non-`nil'---then `load' just returns `nil'.
`load' returns `t' if the file loads successfully.
* User Option: load-path
The value of this global variable is a list of directories to
search when loading files with `load'. Each element is a string
(which must be a directory name) or `nil' (which stands for the
current working directory). The value of `load-path' is
initialized from the environment variable `EMACSLOADPATH', if it
exists; otherwise it is set to the default specified in
`emacs/src/paths.h' when Emacs is built.
The syntax of `EMACSLOADPATH' is the same as that of `PATH';
fields are separated by `:', and `.' is used for the current
working directory. Here is an example of how to set your
`EMACSLOADPATH' variable from a `.login' file:
setenv EMACSLOADPATH .:/user/liberte/emacs:/usr/local/lib/emacs/lisp
Here is an example of code you can place in a `.emacs' file to
add several directories to the front of your default `load-path':
(setq load-path
(append
(list nil
"/user/liberte/emacs/"
"/usr/local/lib/emacs/local")
load-path))
In this example, the current working directory is placed first,
followed by `/user/liberte/emacs/' and
`/usr/local/lib/emacs/local'.
* Variable: load-in-progress
This global variable is non-`nil' if Emacs is in the process of
loading a file, and it is `nil' otherwise. This is how `autoload'
determines whether a load is in progress.
▶1f◀
File: lispref Node: Autoload, Prev: How Programs do Loading, Up: Loading, Next: Features
Autoload
========
The "autoload" feature allows you to call a function or macro whose
function definition has not yet been loaded into Emacs. An attempt to
call the symbol while its definition is an autoload-object will
automatically install the real definition and its other associated code,
and then call the real definition.
To prepare a function or macro for autoloading, you must call
`autoload' on it, specifying the function name and the name of the file
to be loaded. This is usually done when Emacs is first built, by files
such as `emacs/lisp/loaddefs.el'.
The following example shows how `dired' is prepared for autoloading in
`loaddefs.el':
(autoload 'dired "dired"
"\ ; (`loaddefs.el' uses special
\"Edit\" directory DIRNAME. ; formatting conventions.)
...
t)
Calling `autoload' creates an `autoload object' containing the name of
the file and some other information, and makes this the definition of
the specified symbol. When you later try to call that symbol as a
function or macro, the file is loaded; the loading should redefine that
symbol with its proper definition. After the file completes loading,
the function or macro is called as if it had been there originally.
If a Lisp function or macro is not redefined by loading the file, the
error `error' is signaled (with data `"Autoloading failed to define
function FUNCTION-NAME"'.
The autoloaded file may, of course, contain other definitions and may
require or provide one or more features. If the file is not completely
loaded (due to some error in the evaluation of the contents) any
function definitions or `provide' calls that occurred during the load
are undone. This is to ensure that another `autoload' attempt will
result from the next attempt to call the autoloading function.
* Function: autoload SYMBOL FILENAME &optional DOCSTRING INTERACTIVE MACRO
This function defines the function (or macro) named SYMBOL so as
to load automatically from FILENAME. FILENAME is a file name which
will be passed to `load' when the function is called.
DOCSTRING is the documentation string for the function.
Normally, this is the same string that is in the function
definition itself. This makes it possible for you to look at the
documentation without loading the file.
If INTERACTIVE is non-`nil', then the function can be called
interactively. This lets completion in `M-x' work without loading
the symbol's definition. The complete interactive specification
need not be given here. If MACRO is non-`nil', then the function
is really a macro.
If SYMBOL already has a non-`nil' function cell that is not an
`autoload' definition, `autoload' does nothing and returns `nil'.
If the function cell of SYMBOL is void, it is set to an `autoload'
object that looks like this:
(autoload FILENAME DOCSTRING INTERACTIVE MACRO)
For example,
(symbol-function 'run-prolog)
=> (autoload "prolog" 169681 t nil)
In this case, `prolog' is the name of the file to load, 169681 is
the reference to the documentation string in the `emacs/etc/DOC'
file, `t' means the function is interactive, and `nil' that it is
not a macro.
▶1f◀
File: lispref Node: Features, Prev: Autoload, Up: Loading
Features
========
`provide' and `require' are another way to load files automatically
besides `autoload', by named features. While autoloading is tied to
particular functions, features are loaded whenever another program says
they are needed, but never more than once in a session.
The use of named features simplifies the task of determining whether
required definitions have been defined. A feature name stands for a
collection of functions, variables, etc. A program that needs the
collection may ensure that they are defined by "requiring" the feature.
If the file that contains the feature has not yet been loaded, then it
will be loaded (or an error will be signaled if it cannot be loaded).
The file thus loaded must "provide" the required feature or an error
will be signaled.
To require the presence of a feature, call `require' with the name of
the feature. `require' looks in the global variable `features' to see
whether the desired feature has been provided already. If not, it loads
the associated file. The file that contains the feature should call
`provide' at the top-level to add the feature to `features' once it is
loaded.
Features are normally named after the files they are provided in so
that `require' need not be given the file name.
For example, in `emacs/lisp/prolog.el', the definition for
`run-prolog' includes the following code:
(interactive)
(require 'shell)
(switch-to-buffer (make-shell "prolog" "prolog"))
(inferior-prolog-mode))
The expression `(require 'shell)' means that if the `shell' file has not
yet been loaded, it will be loaded. This ensures that `make-shell' is
defined.
Also, the `emacs/lisp/shell.el' file contains the following top-level
expression:
(provide 'shell)
This adds `shell' to the global `features' list when the `shell' file is
loaded, so that `(require 'shell)' will know that nothing needs to be
done. (The order of the elements in the `features' list is not
significant.)
When `require' is used at top-level in a file, it takes effect if you
byte-compile that file (*Note Byte Compilation::). This is in case the
required package required contains macros that the byte-compiler must
know about.
Although top-level calls to `require' are evaluated during the
byte-compilation, `provide' calls are not. Therefore, you can ensure
that a file of definitions is loaded before it is byte-compiled by
including a `provide' followed by a `require' for the same feature, as
in the following example.
(provide 'my-feature) ; ignored by byte compiler, evaluated by load
(require 'my-feature) ; evaluated by byte compiler
* Function: provide FEATURE
This function announces that FEATURE is now loaded (or will be as
soon as this load is done) in the current Emacs session. This
means that the facilities associated with FEATURE are available for
other Lisp programs.
The FEATURE is added to the front of the list `features' if it is
not already in the list. FEATURE must be a symbol. `provide'
returns FEATURE.
features
=> (bar bish)
(provide 'foo)
=> foo
features
=> (foo bar bish)
* Function: require FEATURE &optional FILENAME
This function looks to see if FEATURE is present in the current
Emacs session (i.e., `(featurep FEATURE)' is true). If it is not,
then `require' loads FILENAME with `load'. If FILENAME is not
supplied, then FEATURE is used as the file name to load.
If FEATURE is not provided after the file has been loaded, Emacs
will signal the error `error' (with data `Required feature FEATURE
was not provided').
* Function: featurep FEATURE
This function returns `t' if FEATURE has been provided in the
current Emacs session (i.e., FEATURE is a member of `features'.)
* Variable: features
The value of this global variable is a list of symbols which are
the features loaded in the current Emacs session. Each symbol was
put in this list with a call to `provide'.
▶1f◀
File: lispref Node: Byte Compilation, Prev: Loading, Up: Top, Next: Debugging
Byte Compilation
****************
GNU Emacs Lisp has a compiler which translates functions from
lambda-expressions into a special form called "byte code" which can be
executed more efficiently. The compiler replaces each function
definition with byte code. When a byte code file is called, its
definition is then evaluated by the "byte code interpreter".
Because the byte compiled code is evaluated by the byte-code
interpreter, instead of being executed directly by the machine's
hardware (as true compiled code is), byte-code is completely
transportable from machine to machine without re-compilation. But it is
not as fast as true compiled code.
* Menu:
* Compilation Functions:: Byte compilation functions.
* Disassembly:: Disassembled byte code
▶1f◀
File: lispref Node: Compilation Functions, Prev: Byte Compilation, Up: Byte Compilation, Next: Disassembly
The Compilation Functions
=========================
An individual function or macro definition may be byte-compiled with
the `byte-compile' function. A whole file may be byte-compiled with
`byte-compile-file' and several files may be byte-compiled with
`byte-recompile-directory' or `batch-byte-compile'. Only `defun' and
`defmacro' forms in a file are byte-compiled; other top-level forms are
unaltered byte-compilation.
Be careful when byte compiling code that uses macros since macro calls
are expanded when they are compiled and therefore the macros must
already be defined for proper compilation. For more details, *Note
Macros::.
While byte-compiling a file, any `require' calls at top-level are
executed. This is one way to ensure that required macro definitions are
available during compilation: require the file that defines them. *Note
Features::.
A byte compiled function is not as efficient as a primitive function
written in C, but it will run much faster than the interpreted version.
As a rough comparison, consider the example below:
(defun silly-loop (n)
"Return time before and after N iterations of a loop."
(let ((t1 (current-time-string)))
(while (> (setq n (1- n))
0))
(list t1 (current-time-string))
))
=> silly-loop
(silly-loop 100000)
=> ("Thu Jan 12 20:18:38 1989"
"Thu Jan 12 20:19:29 1989") ; 51 secconds
(byte-compile 'silly-loop)
=> [Compiled code not shown]
(silly-loop 100000)
=> ("Thu Jan 12 20:21:04 1989"
"Thu Jan 12 20:21:17 1989") ; 13 seconds
In this example, the interpreted code required 51 seconds to run,
whereas the byte compiled code required 13 seconds. These results are
representative, but there will be great variability depending upon the
specific functions called.
* Function: byte-compile SYMBOL
This function byte-compiles the function definition of SYMBOL,
replacing the previous definition with the compiled one. The
function definition of SYMBOL must be the actual code for the
function; i.e., the compiler will not follow indirection to another
symbol. `byte-compile' does not compile macros.
The `byte-compile' function is not autoloaded as are
`byte-compile-file' and `byte-recompile-directory'.
(defun factorial (integer)
"Compute factorial of INTEGER."
(if (= 1 integer) 1
(* integer (factorial (1- integer)))))
=> factorial
(byte-compile 'factorial)
=> (lambda (integer)
"Compute factorial of INTEGER."
(byte-code "\301^HU\203
^@\301\202^Q^@\302^H\303^HS!\"\207"
[integer 1 * factorial] 4))
* Command: byte-compile-file FILENAME
This function compiles a file of Lisp code named FILENAME into a
file of byte code. The output file's name is made by appending `c'
to the end of FILENAME.
Each form in the input file read. If it returns a function or
macro, the compiled function or macro definition is written out.
Other forms are copied in unchanged. All comments are discarded.
When called interactively, this command prompts you for the
filename.
% ls -l push*
-rw-r--r-- 1 lewis 0 791 Oct 5 20:31 push.el
(byte-compile-file "~/emacs/push.el")
=> t
% ls -l push*
-rw-r--r-- 1 lewis 0 791 Oct 5 20:31 push.el
-rw-rw-rw- 1 lewis 0 638 Oct 8 20:25 push.elc
* Command: byte-recompile-directory DIRECTORY FLAG
This function recompiles every `.el' file in DIRECTORY that needs
recompilation. A file needs recompilation if a `.elc' file exists
but is older than the `.el' file.
If a `.el' file exists, but there is no corresponding `.elc'
file, then FLAG is examined. If it is `nil', the file is ignored.
If it is non-`nil', the user is asked if the file should be
compiled.
* Function: batch-byte-compile
This function runs `byte-compile-file' on the files remaining on
the command line. This function must be used only in a batch
execution of Emacs, as it kills Emacs on completion. Each file
will be processed, even if an error occurs while compiling a
previous file. (The file with the error will not produce any
compiled code, of course.)
% emacs -batch -f batch-byte-compile *.el
* Function: byte-code CODE-STRING DATA-VECTOR MAX-STACK
This is the function that actually interprets the byte code. A
byte-compiled function is actually defined with a body that calls
`byte-code'. Don't call this function yourself!
▶1f◀
File: lispref Node: Disassembly, Prev: Compilation Functions, Up: Byte Compilation
Dissassembled Byte Code
=======================
People never write byte code; that job is left to the byte compiler.
But a disassembler has been provided to satisfy a cat-like curiosity.
The disassembler converts the byte-compiled code into a humanly readable
form.
The byte code interpreter is implemented as a very simple stack
machine. Values get stored by being pushed onto the stack, and are
popped off and manipulated, the results being pushed back onto the
stack. When a function returns, the top of the stack is popped and
returned as the value of the fucntion.
In addition to the stack, variables bound in the environment can also
hold values during execution. The values of such variables can be
pushed onto the stack, or the variables can be set by popping the stack.
* Function: disassemble OBJECT &optional STREAM
This function prints the disassembled code for OBJECT. If STREAM
is supplied, then output goes there. Otherwise, the disassembled
code is printed to the standard output. OBJECT can be a function
name or a lambda expression.
Here are two examples of using the `disassemble' function. The
comments added to the examples do not appear in the output of
`disassemble'.
(defun factorial (integer)
"Compute factorial of an integer."
(if (= 1 integer) 1
(* integer (factorial (1- integer)))))
=> factorial
(factorial 4)
=> 24
(disassemble 'factorial)
=> byte code for factorial:
doc: Compute factorial of an integer.
args: (integer)
0 constant 1 ; push 1 onto stack
1 varref integer ; get value of `integer' from the environment
; and push the value onto the stack
2 eqlsign ; pop top two values off stack,
; compare them,
; and push result onto stack
3 goto-if-nil 10 ; pop and test top of stack;
; if `nil', go to 10,
; else continue
6 constant 1 ; push 1 onto top of stack
7 goto 17 ; go to 17 (in this case, 1 will be
; returned by the function)
10 constant * ; push symbol `*' onto stack
11 varref integer ; push value of `integer' onto stack
12 constant factorial ; push `factorial' onto stack
13 varref integer ; push value of `integer' onto stack
14 sub1 ; pop `integer', decrement value,
; push new value onto stack
; stack now is:
; decremented value of `integer'
; `factorial'
; value of `integer'
; `*'
15 call 1 ; call function `factorial' using
; the first (i.e., the top) element
; of the stack as the argument;
; push returned value onto stack
; stack now is:
; result of result of recursive
; call to `factorial'
; value of `integer'
; `*'
16 call 2 ; using the first two (i.e., the top two)
; elements of the stack as arguments,
; call the function `*',
; pushing the result onto the stack
17 return ; return the top element of the stack
=> nil
The `silly-loop' function is somewhat more complex:
(defun silly-loop (n)
"Return time before and after N iterations of a loop."
(let ((t1 (current-time-string)))
(while (> (setq n (1- n))
0))
(list t1 (current-time-string))
))
=> silly-loop
(disassemble 'silly-loop)
=> byte code for silly-loop:
doc: Return time before and after N iterations of a loop.
args: (n)
0 constant current-time-string ; push `current-time-string'
; onto top of stack
1 call 0 ; call `current-time-string' with no
; argument, pushing result onto stack
2 varbind t1 ; pop stack and bind `t1' to popped value
3 varref n ; get value of `n' from the environment
; and push the value onto the stack
4 sub1 ; subtract 1 from top of stack
5 dup ; duplicate the top of the stack;
; i.e. copy the top of the stack
; and push the copy onto the stack
6 varset n ; pop the top of the stack,
; and bind `n' to the value
; in effect, the sequence `dup varset' copies
; the top of the stack into the value of `n'
; without popping it
7 constant 0 ; push 0 onto stack
8 gtr ; pop top two values off stack,
; test if N is greater than 0
; and push result onto stack
9 goto-if-nil-else-pop 17 ; goto 17 if `n' > 0 else
; pop top of stack and continue
; (this exits the while loop)
12 constant nil ; push `nil' onto stack
; (this is the body of the loop)
13 discard ; discard result of the body of the loop
; (a while loop is always evaluated
; for its side effects)
14 goto 3 ; jump back to beginning of while loop
17 discard ; discard result of while loop
; by popping top of stack
18 varref t1 ; push value of `t1' onto stack
19 constant current-time-string ; push `current-time-string'
; onto top of stack
20 call 0 ; call `current-time-string' again
21 list2 ; pop top two elements off stack,
; create a list of them,
; and push list onto stack
22 unbind 1 ; unbind t1 in local environment
23 return ; return value of the top of stack
=> nil
▶1f◀
File: lispref Node: Debugging, Prev: Byte Compilation, Up: Top, Next: Streams
Debugging
*********
The Lisp Debugger provides you with the ability to suspend evaluation
of a form and do a number of things that help in debugging Lisp code.
While evaluation is suspended (a state that is commonly known as a
"break"), you may examine the runtime stack, examine the values of local
or global variables and, optionally, change those values. Since a break
is a recursive edit while in the middle of a function call, it is
possible to do anything, including calling the debugger again. (*Note
Recursive Editing::, and also, (*Note Recursive Editing Levels:
(emacs)Recursive Edit..)
The actions of the debugger are well documented in the GNU Emacs
Manual; and they will not be repeated here. The rest of this section
assumes that you are familiar with that section in the manual. (*Note
The Emacs-Lisp Debugger: (emacs)Lisp Debug.)
The operation of the debugger is quite simple: it performs one basic
operation, which is to enter a break. The debugger enters such a break
when one or other of the following conditions occur:
* when a certain function specified by you is entered or exited;
* when a error occurs; or
* when a `quit' signal is not handled by user code.
After entering the break, the debugger displays information about the
status of the stack in a `*Backtrace*' buffer, and waits for you to type
a command.
When you cause Emacs to continue evaluation, at a break for function
entry or exit, the debugger will arrange for the called function to
continue to a normal conclusion and return the same value that it would
return when evaluated without the debugger. It will not produce an
abnormal termination unless you specifically request it.
Another useful debugging tool is a dribble file. When a dribble file
is open, Emacs copies all keyboard input characters to that file. You
can examine it to find out what you did. *Note Terminal Input::; also
see the `open-termscript' function in *Note Terminal Output::.
* Menu:
* Debug Functions::
▶1f◀
File: lispref Node: Debug Functions, Prev: Debugging, Up: Debugging
Debug Functions
===============
* Function: debug &rest DEBUGGER-ARGS
This function enters the debugger. It switches buffers to a
buffer named `*Backtrace*' (or `*Backtrace*<2>' if it is the second
recursive edit, etc.) and prints out information about the stack.
Emacs then enters a recursive edit, leaving that buffer showing in
the selected window, which is in Debugger Mode.
One of the commands defined in Debugger mode is `continue', which
causes Emacs to exit the recursive edit, switch back to the
previous buffer, and continue evaluation normally.
If the first of the DEBUGGER-ARGS passed to `debug' is `nil' (or
if it is a non-`nil' value which is not one of the following
special values), then the rest of the arguments to `debug' are
printed at the top of the `*Backtrace*' buffer. This mechanism is
used to display a message to the user.
However, if the first argument passed to `debug' is one of the
following special values, then it has special significance.
Normally, these values are passed to `debug' only by the internals
of Emacs and the debugger, and not by programmers calling `debug'.
The special values are:
`lambda'
When `lambda' is passed as the first of the DEBUGGER-ARGS,
the debugger displays `Entering:' as a line of text at the top
of the buffer. This is used to indicate that a function that
is being debugged is being entered.
`debug'
When `debug' is passed as the first of the DEBUGGER-ARGS,
the debugger displays `Entering:' as a line of text at the top
of the buffer, just as when `lambda' is passed as the first of
the DEBUGGER-ARGS. This is used to indicate that a function
that is being debugged is being entered.
In addition, use of `debug' causes the debugger to mark the
function that called `debug' so that it will also break on
exit.
`error'
When `error' is passed as the argument, the debugger
indicates that it is being entered because an error or `quit'
was signaled and not handled. If an error was signaled,
presumably the variable `debug-on-error' is non-`nil'. If
`quit' was signaled, then presumably the variable
`debug-on-quit' is non-`nil'.
When entering, the debugger displays `Signaling:' followed
by the error signaled and any arguments to `signal'.
For example,
(let ((debug-on-error t))
(/ 1 0))
---------- Buffer: *Backtrace* ----------
Signaling: (arith-error)
/(1 0)
...
`t'
When `t' is passed as the argument, the debuggerwill
indicate that Emacs is beginning the evaluation of a function
call. The debugger displays `Beginning evaluation of function
call form:' as the top line in the buffer.
`exit'
When `exit' is passed as the argument, it means that a a
function that was being debugged is returning a value. The
debugger displays `Return value:' on the top line of the
buffer, followed by the returned value.
`nil'
Use `nil' as the first of the DEBUGGER-ARGS when you want to
enter the debugger directly. The rest of the DEBUGGER-ARGS
are printed on the top line of the buffer. You can use this
feature to display messages---for example, to remind yourself
the conditions under which `debug' is called.
* Variable: debugger
The value of this variable is the function to call in order to
invoke the debugger. Its value must be a function (or, more
typically, the name of a function) of any number of arguments.
Presumably this function will enter some kind of debugger.
The first argument that Lisp hands to the function indicates how
it was called. The convention for arguments is detailed in the
description of `debug'.
* Command: backtrace
This function prints a trace of Lisp function calls currently
active. This is the function used by `debug' to fill up the
`*Backtrace*' buffer. It is written in C, as it must have access
to the stack in order to determine which function calls are active.
The return value is always `nil'.
In the following example, `backtrace' is called explicitly in a
Lisp expression. When the expression is evaluated, the backtrace
is printed to `standard-output': in this case, to the buffer
`backtrace-output'. Each line of the backtrace represents one
function call. If the arguments of the function call are all
known, they are displayed; if they are being computed, that fact is
displayed. The arguments of special forms are elided.
(with-output-to-temp-buffer "backtrace-output"
(let ((var 1))
(save-excursion
(setq var (eval '(progn
(1+ var)
(list 'testing (backtrace))
))))))
=> nil
----------- 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 ------------
* Command: debug-on-entry FUNCTION-NAME
This function requests FUNCTION-NAME to invoke the debugger each
time it is called. It works by inserting the form `(debug 'debug)'
into the function definition as the first form.
Any function defined as Lisp code may be debugged, regardless of
whether it is interpreted code or compiled code. Even functions
which are commands may be debugged. They will enter the debugger
when called inside of a function, or when called interactively.
Primitive functions (i.e., those written in C) may not be debugged.
When `debug-on-entry' is called interactively, Emacs prompts you
for FUNCTION-NAME in the minibuffer.
`debug-on-entry' returns FUNCTION-NAME. If `debug-on-entry' is
called more than once on the same function, the second call does
nothing.
(defun fact (n)
(if (zerop n) 1
(* n (fact (1- n)))))
=> fact
(debug-on-entry 'fact)
=> fact
(fact 3)
=> 6
---------- 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* ----------
(symbol-function 'fact)
=> (lambda (n)
(debug (quote debug))
(if (zerop n) 1 (* n (fact (1- n)))))
* Command: cancel-debug-on-entry FUNCTION-NAME
This function undoes the effect of `debug-on-entry' on
FUNCTION-NAME.
When `cancel-debug-on-entry' is called interactively, Emacs
prompts you for FUNCTION-NAME in the minibuffer.
If `cancel-debug-on-entry' is called more than once on the same
function, the second call does nothing. `cancel-debug-on-entry'
returns FUNCTION-NAME.
* User Option: debug-on-error
This variable determines whether the debugger is called when a
error is signaled and not handled. If the `debug-on-error'
variable is non-`nil', then the debugger is called on every such
error. (Note that `quit' is not an error.). If the
`debug-on-error' variable is `nil', then the debugger is not
called.
* User Option: debug-on-quit
This variable determines whether the debugger is called when
`quit' is signaled and not handled. If the `debug-on-quit'
variable it is non-`nil' then the debugger is called on every
`quit' signal. If the `debug-on-quit' variable is `nil', then the
debugger is not called. (`quit' is the signal that `C-g' causes.)
* User Option: stack-trace-on-error
This obsolete variable determines whether Lisp shall
automatically display a backtrace buffer after every error that is
not handled. A quit signal counts as an error for this variable.
If it is non-`nil' then a backtrace is shown in a pop-up buffer
named `*Backtrace*' on every error. If it is `nil', then a
backtrace is not shown.
When a backtrace is shown, that buffer is not selected. If
either `debug-on-quit' or `debug-on-error' is also non-`nil', then
a backtrace is shown in one buffer, and the debugger is popped up
in another buffer with its own backtrace.
* Variable: debug-on-next-call
This variable determines whether the debugger is called before
the next `eval', `apply' or `funcall'. It is automatically reset
to `nil' when the debugger is entered.
The `d' command in the debuffer works by setting this variable.
* Function: backtrace-debug LEVEL FLAG
This function sets the debug-on-exit flag of the eval frame LEVEL
levels down to FLAG, causing the debugger to be entered when that
frame exits, assuming FLAG is non-`nil'.
The `debug-on-exit' flag is an entry in the stack frame of a
function call. This flag is examined on every exit from a
function.
Normally this function is only called by the debugger.
▶1f◀
File: lispref Node: Streams, Prev: Debugging, Up: Top, Next: Minibuffers
Reading and Printing Lisp Objects
*********************************
"Printing" and "reading" are the operations of converting Lisp objects
to textual form and vice versa. They use the printed representations
and syntax described in *Note Types of Lisp Object::.
This chapter describes the Lisp functions for reading and printing.
It also describes "streams", which specify where to get the text (if
reading) or where to put it (if printing).
* Menu:
* Streams Intro::
* Input Streams::
* Input Functions::
* Output Streams::
* Output Functions::
▶1f◀
File: lispref Node: Streams Intro, Prev: Streams, Up: Streams, Next: Input Streams
Introduction to Reading and Printing
====================================
"Reading" a Lisp object means parsing a Lisp expression in textual
form and producing a corresponding Lisp object. This is how Lisp
programs get into Lisp from files of Lisp code. For example, reading
the text `(a . 5)' returns a cons cell whose CAR is `a' and whose CDR is
the number 5.
"Printing" a Lisp object means producing the text which represents
that object. Printing that cons cell produces the text `(a . 5)'.
Generally speaking, reading and printing are inverse operations.
Printing the object that results from reading a given piece of text
usually produces the same text, and reading the text that results from
printing an object usually produces a similar-looking object. For
example, printing the symbol `foo' produces the text `foo', and reading
that text returns the symbol `foo'. Printing a list whose elements are
`a' and `b' produces the text `(a b)', and reading that text produces a
list (but not the same list) with elements are `a' and `b'.
However, these two operations are not precisely inverses. There are
two kinds of exceptions:
* Printing can produce text that cannot be read. For example,
buffers, windows, subprocesses and markers print into text that
starts with `#'; if you try to read this text, you get an error.
There is no way to read those data types.
* One object can have multiple textual representations. For example,
`1' and `01' represent the same integer, and `(a b)' and `(a .
(b))' represent the same list. Reading will accept any of the
alternatives, but evidently printing must choose one of them.
▶1f◀
File: lispref Node: Input Streams, Prev: Streams Intro, Up: Streams, Next: Input Functions
Input Streams
=============
Most of the Lisp functions for reading text take an "input stream" as
argument. The input stream specifies where or how to get the characters
of the text to be read. Here are the possible types of input stream:
BUFFER
The input characters are read from BUFFER, starting with the
character directly after point. Point advances as characters are
read.
MARKER
The input characters are read from the buffer that MARKER is in,
starting with the character directly after the marker. Its
position advances as characters are read. The value of point in
the buffer has no effect when the stream is a marker.
STRING
The input characters are taken from STRING, starting at the first
character in the string and advancing through as many character as
required.
FUNCTION
The input characters are generated by FUNCTION, one per call.
In version 18, FUNCTION is always called with no arguments and
should return a character.
`t'
`t' used as a stream means that the input is read from the
minibuffer. In fact, the minibuffer is invoked once and the text
given by the user is made into a string which is then used as the
input stream.
`nil'
`nil' used as a stream means that the value of `standard-input'
should be used instead; that value must be a non-`nil' input
stream.
Here is an example of reading from a stream which is a buffer. We
show where point is before and after.
---------- Buffer: foo ----------
This-!- is the contents of foo.
---------- Buffer: foo ----------
(read (get-buffer "foo"))
=> is
(read (get-buffer "foo"))
=> the
---------- Buffer: foo ----------
This is the -!-contents of foo.
---------- Buffer: foo ----------
Note that the first read skips a space at the beginning. Reading always
skips any amount of whitespace preceding the significant text.
Note also how the second read skips the space which terminates the
symbol `the'. It has to read this space in order to know that no more
letters follow.
Here is an example of reading from a stream which is a marker. The
marker is initialized to point at the beginning of the buffer shown.
The value of the read is the symbol `This'.
---------- Buffer: foo ----------
This is the contents of foo.
---------- Buffer: foo ----------
(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
=> #<marker at 1 in foo>
(read m)
=> This
m
=> #<marker at 6 in foo> ;; After the first space.
Here we read from the text of a string:
(read "(When in) the course")
=> (When in)
The following example reads from the minibuffer, prompting with `Lisp
expression: '. (That is always the prompt used when you read from the
stream `t'.) The user's input is shown following the prompt.
(read t)
=> 23
---------- Buffer: Minibuffer ----------
Lisp expression: 23 RET
Finally, here is an example of a stream which is a function, named
`useless-stream'. The variable `useless-list' is initialized to a list
of characters. Each call to the function `useless-stream' produces the
next letter in the list.
(setq useless-list (append "XY()" nil))
=> (88 89 40 41)
(defun useless-stream ()
(prog1 (car useless-list)
(setq useless-list (cdr useless-list))))
=> useless-stream
Now we read using this stream.
(read 'useless-stream)
=> XY
useless-list
=> (41)
Note that only the close-parenthesis remains in the list. This is
because the open-parenthesis was read before the Lisp reader knew it had
found the end of the symbol. A second attempt to read from the stream
at this point would get an error due to the unmatched close-parenthesis.
* Function: get-file-char
This function is used internally as an input stream to read from
the input file opened by the function `load'. Don't use this
function yourself.
▶1f◀