+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- 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.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and 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 the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: Trapping Errors, Next: Edebug Views, Prev: Breakpoints, Up: Edebug
-
-Trapping Errors
----------------
-
- An error may be signaled by subroutines or XEmacs Lisp code. If a
-signal is not handled by a `condition-case', this indicates an
-unrecognized situation has occurred. If Edebug is not active when an
-unhandled error is signaled, `debug' is run normally (if
-`debug-on-error' is non-`nil'). But while Edebug is active,
-`debug-on-error' and `debug-on-quit' are bound to `edebug-on-error' and
-`edebug-on-quit', which are both `t' by default. Actually, if
-`debug-on-error' already has a non-`nil' value, that value is still
-used.
-
- It is best to change the values of `edebug-on-error' or
-`edebug-on-quit' when Edebug is not active since their values won't be
-used until the next time Edebug is invoked at a deeper command level.
-If you only change `debug-on-error' or `debug-on-quit' while Edebug is
-active, these changes will be forgotten when Edebug becomes inactive.
-Furthermore, during Edebug's recursive edit, these variables are bound
-to the values they had outside of Edebug.
-
- Edebug shows you the last stop point that it knew about before the
-error was signaled. This may be the location of a call to a function
-which was not instrumented, within which the error actually occurred.
-For an unbound variable error, the last known stop point might be quite
-distant from the offending variable. If the cause of the error is not
-obvious at first, note that you can also get a full backtrace inside of
-Edebug (see *Note Edebug Misc::).
-
- Edebug can also trap signals even if they are handled. If
-`debug-on-error' is a list of signal names, Edebug will stop when any
-of these errors are signaled. Edebug shows you the last known stop
-point just as for unhandled errors. After you continue execution, the
-error is signaled again (but without being caught by Edebug). Edebug
-can only trap errors that are handled if they are signaled in Lisp code
-(not subroutines) since it does so by temporarily replacing the
-`signal' function.
-
-\1f
-File: lispref.info, Node: Edebug Views, Next: Edebug Eval, Prev: Trapping Errors, Up: Edebug
-
-Edebug Views
-------------
-
- The following Edebug commands let you view aspects of the buffer and
-window status that obtained before entry to Edebug.
-
-`v'
- View the outside window configuration (`edebug-view-outside').
-
-`p'
- Temporarily display the outside current buffer with point at its
- outside position (`edebug-bounce-point'). If prefix arg is
- supplied, sit for that many seconds instead.
-
-`w'
- Move point back to the current stop point (`edebug-where') in the
- source code buffer. Also, if you use this command in another
- window displaying the same buffer, this window will be used
- instead to display the buffer in the future.
-
-`W'
- Toggle the `edebug-save-windows' variable which indicates whether
- the outside window configuration is saved and restored
- (`edebug-toggle-save-windows'). Also, each time it is toggled on,
- make the outside window configuration the same as the current
- window configuration.
-
- With a prefix argument, `edebug-toggle-save-windows' only toggles
- saving and restoring of the selected window. To specify a window
- that is not displaying the source code buffer, you must use
- `C-xXW' from the global keymap.
-
- You can view the outside window configuration with `v' or just
-bounce to the current point in the current buffer with `p', even if it
-is not normally displayed. After moving point, you may wish to pop
-back to the stop point with `w' from a source code buffer.
-
- By using `W' twice, Edebug again saves and restores the outside
-window configuration, but to the current configuration. This is a
-convenient way to, for example, add another buffer to be displayed
-whenever Edebug is active. However, the automatic redisplay of
-`*edebug*' and `*edebug-trace*' may conflict with the buffers you wish
-to see unless you have enough windows open.
-
-\1f
-File: lispref.info, Node: Edebug Eval, Next: Eval List, Prev: Edebug Views, Up: Edebug
-
-Evaluation
-----------
-
- While within Edebug, you can evaluate expressions "as if" Edebug were
-not running. Edebug tries to be invisible to the expression's
-evaluation and printing. Evaluation of expressions that cause side
-effects will work as expected except for things that Edebug explicitly
-saves and restores. See *Note The Outside Context:: for details on this
-process. Also see *Note Reading in Edebug:: and *Note Printing in
-Edebug:: for topics related to evaluation.
-
-`e EXP <RET>'
- Evaluate expression EXP in the context outside of Edebug
- (`edebug-eval-expression'). In other words, Edebug tries to avoid
- altering the effect of EXP.
-
-`M-<ESC> EXP <RET>'
- Evaluate expression EXP in the context of Edebug itself.
-
-`C-x C-e'
- Evaluate the expression before point, in the context outside of
- Edebug (`edebug-eval-last-sexp').
-
- Edebug supports evaluation of expressions containing references to
-lexically bound symbols created by the following constructs in `cl.el'
-(version 2.03 or later): `lexical-let', `macrolet', and
-`symbol-macrolet'.
-
-\1f
-File: lispref.info, Node: Eval List, Next: Reading in Edebug, Prev: Edebug Eval, Up: Edebug
-
-Evaluation List Buffer
-----------------------
-
- You can use the "evaluation list buffer", called `*edebug*', to
-evaluate expressions interactively. You can also set up the
-"evaluation list" of expressions to be evaluated automatically each
-time Edebug updates the display.
-
-`E'
- Switch to the evaluation list buffer `*edebug*'
- (`edebug-visit-eval-list').
-
- In the `*edebug*' buffer you can use the commands of Lisp
-Interaction as well as these special commands:
-
-`LFD'
- Evaluate the expression before point, in the outside context, and
- insert the value in the buffer (`edebug-eval-print-last-sexp').
-
-`C-x C-e'
- Evaluate the expression before point, in the context outside of
- Edebug (`edebug-eval-last-sexp').
-
-`C-c C-u'
- Build a new evaluation list from the first expression of each
- group, reevaluate and redisplay (`edebug-update-eval-list').
- Groups are separated by comment lines.
-
-`C-c C-d'
- Delete the evaluation list group that point is in
- (`edebug-delete-eval-item').
-
-`C-c C-w'
- Switch back to the source code buffer at the current stop point
- (`edebug-where').
-
- You can evaluate expressions in the evaluation list window with
-`LFD' or `C-x C-e', just as you would in `*scratch*'; but they are
-evaluated in the context outside of Edebug.
-
- The expressions you enter interactively (and their results) are lost
-when you continue execution unless you add them to the evaluation list
-with `C-c C-u'. This command builds a new list from the first
-expression of each "evaluation list group". Groups are separated by
-comment lines. Be careful not to add expressions that execute
-instrumented code otherwise an infinite loop will result.
-
- When the evaluation list is redisplayed, each expression is displayed
-followed by the result of evaluating it, and a comment line. If an
-error occurs during an evaluation, the error message is displayed in a
-string as if it were the result. Therefore expressions that, for
-example, use variables not currently valid do not interrupt your
-debugging.
-
- Here is an example of what the evaluation list window looks like
-after several expressions have been added to it:
-
- (current-buffer)
- #<buffer *scratch*>
- ;---------------------------------------------------------------
- (selected-window)
- #<window 16 on *scratch*>
- ;---------------------------------------------------------------
- (point)
- 196
- ;---------------------------------------------------------------
- bad-var
- "Symbol's value as variable is void: bad-var"
- ;---------------------------------------------------------------
- (recursion-depth)
- 0
- ;---------------------------------------------------------------
- this-command
- eval-last-sexp
- ;---------------------------------------------------------------
-
- To delete a group, move point into it and type `C-c C-d', or simply
-delete the text for the group and update the evaluation list with `C-c
-C-u'. When you add a new group, be sure it is separated from its
-neighbors by a comment line.
-
- After selecting `*edebug*', you can return to the source code buffer
-with `C-c C-w'. The `*edebug*' buffer is killed when you continue
-execution, and recreated next time it is needed.
-
-\1f
-File: lispref.info, Node: Reading in Edebug, Next: Printing in Edebug, Prev: Eval List, Up: Edebug
-
-Reading in Edebug
------------------
-
- To instrument a form, Edebug first reads the whole form. Edebug
-replaces the standard Lisp Reader with its own reader that remembers the
-positions of expressions. This reader is used by the Edebug
-replacements for `eval-region', `eval-defun', `eval-buffer', and
-`eval-current-buffer'.
-
- Another package, `cl-read.el', replaces the standard reader with one
-that understands Common Lisp reader macros. If you use that package,
-Edebug will automatically load `edebug-cl-read.el' to provide
-corresponding reader macros that remember positions of expressions. If
-you define new reader macros, you will have to define similar reader
-macros for Edebug.
-
-\1f
-File: lispref.info, Node: Printing in Edebug, Next: Tracing, Prev: Reading in Edebug, Up: Edebug
-
-Printing in Edebug
-------------------
-
- If the result of an expression in your program contains a circular
-reference, you may get an error when Edebug attempts to print it. You
-can set `print-length' to a non-zero value to limit the print length of
-lists (the number of cdrs), and in Emacs 19, set `print-level' to a
-non-zero value to limit the print depth of lists. But you can print
-such circular structures and structures that share elements more
-informatively by using the `cust-print' package.
-
- To load `cust-print' and activate custom printing only for Edebug,
-simply use the command `M-x edebug-install-custom-print'. To restore
-the standard print functions, use `M-x edebug-uninstall-custom-print'.
-You can also activate custom printing for printing in any Lisp code;
-see the package for details.
-
- Here is an example of code that creates a circular structure:
-
- (progn
- (edebug-install-custom-print)
- (setq a '(x y))
- (setcar a a))
-
- Edebug will print the result of the `setcar' as `Result: #1=(#1#
-y)'. The `#1=' notation names the structure that follows it, and the
-`#1#' notation references the previously named structure. This
-notation is used for any shared elements of lists or vectors.
-
- Independent of whether `cust-print' is active, while printing
-results Edebug binds `print-length', `print-level', and `print-circle'
-to `edebug-print-length' (`50'), `edebug-print-level' (`50'), and
-`edebug-print-circle' (`t') respectively, if these values are
-non-`nil'. Also, `print-readably' is bound to `nil' since some objects
-simply cannot be printed readably.
-
-\1f
-File: lispref.info, Node: Tracing, Next: Coverage Testing, Prev: Printing in Edebug, Up: Edebug
-
-Tracing
--------
-
- In addition to automatic stepping through source code, which is also
-called *tracing* (see *Note Edebug Execution Modes::), Edebug can
-produce a traditional trace listing of execution in a separate buffer,
-`*edebug-trace*'.
-
- If the variable `edebug-trace' is non-nil, each function entry and
-exit adds lines to the trace buffer. On function entry, Edebug prints
-`::::{' followed by the function name and argument values. On function
-exit, Edebug prints `::::}' followed by the function name and result of
-the function. The number of `:'s is computed from the recursion depth.
-The balanced braces in the trace buffer can be used to find the
-matching beginning or end of function calls. These displays may be
-customized by replacing the functions `edebug-print-trace-before' and
-`edebug-print-trace-after', which take an arbitrary message string to
-print.
-
- The macro `edebug-tracing' provides tracing similar to function
-enter and exit tracing, but for arbitrary expressions. This macro
-should be explicitly inserted by you around expressions you wish to
-trace the execution of. The first argument is a message string
-(evaluated), and the rest are expressions to evaluate. The result of
-the last expression is returned.
-
- Finally, you can insert arbitrary strings into the trace buffer with
-explicit calls to `edebug-trace'. The arguments of this function are
-the same as for `message', but a newline is always inserted after each
-string printed in this way.
-
- `edebug-tracing' and `edebug-trace' insert lines in the trace buffer
-even if Edebug is not active. Every time the trace buffer is added to,
-the window is scrolled to show the last lines inserted. (There may be
-some display problems if you use tracing along with the evaluation
-list.)
-
-\1f
-File: lispref.info, Node: Coverage Testing, Next: The Outside Context, Prev: Tracing, Up: Edebug
-
-Coverage Testing
-----------------
-
- Edebug provides a rudimentary coverage tester and display of
-execution frequency. Frequency counts are always accumulated, both
-before and after evaluation of each instrumented expression, even if
-the execution mode is `Go-nonstop'. Coverage testing is only done if
-the option `edebug-test-coverage' is non-`nil' because this is
-relatively expensive. Both data sets are displayed by `M-x
-edebug-display-freq-count'.
-
- - Command: edebug-display-freq-count
- Display the frequency count data for each line of the current
- definition. The frequency counts are inserted as comment lines
- after each line, and you can undo all insertions with one `undo'
- command. The counts are inserted starting under the `(' before an
- expression or the `)' after an expression, or on the last char of
- a symbol. The counts are only displayed when they differ from
- previous counts on the same line.
-
- If coverage is being tested, whenever all known results of an
- expression are `eq', the char `=' will be appended after the count
- for that expression. Note that this is always the case for an
- expression only evaluated once.
-
- To clear the frequency count and coverage data for a definition,
- reinstrument it.
-
-
- For example, after evaluating `(fac 5)' with an embedded breakpoint,
-and setting `edebug-test-coverage' to `t', when the breakpoint is
-reached, the frequency data is looks like this:
-
- (defun fac (n)
- (if (= n 0) (edebug))
- ;#6 1 0 =5
- (if (< 0 n)
- ;#5 =
- (* n (fac (1- n)))
- ;# 5 0
- 1))
- ;# 0
-
- The comment lines show that `fac' has been called 6 times. The
-first `if' statement has returned 5 times with the same result each
-time, and the same is true for the condition on the second `if'. The
-recursive call of `fac' has not returned at all.
-
-\1f
-File: lispref.info, Node: The Outside Context, Next: Instrumenting Macro Calls, Prev: Coverage Testing, Up: Edebug
-
-The Outside Context
--------------------
-
- Edebug tries to be transparent to the program you are debugging. In
-addition, most evaluations you do within Edebug (see *Note Edebug
-Eval::) occur in the same outside context which is temporarily restored
-for the evaluation. But Edebug is not completely successful and this
-section explains precisely how it fails. Edebug operation unavoidably
-alters some data in XEmacs, and this can interfere with debugging
-certain programs. Also notice that Edebug's protection against change
-of outside data means that any side effects *intended* by the user in
-the course of debugging will be defeated.
-
-* Menu:
-
-* Checking Whether to Stop:: When Edebug decides what to do.
-* Edebug Display Update:: When Edebug updates the display.
-* Edebug Recursive Edit:: When Edebug stops execution.
-
-\1f
-File: lispref.info, Node: Checking Whether to Stop, Next: Edebug Display Update, Up: The Outside Context
-
-Checking Whether to Stop
-........................
-
- Whenever Edebug is entered just to think about whether to take some
-action, it needs to save and restore certain data.
-
- * `max-lisp-eval-depth' and `max-specpdl-size' are both incremented
- one time to reduce Edebug's impact on the stack. You could,
- however, still run out of stack space when using Edebug.
-
- * The state of keyboard macro execution is saved and restored. While
- Edebug is active, `executing-macro' is bound to
- `edebug-continue-kbd-macro'.
-
-\1f
-File: lispref.info, Node: Edebug Display Update, Next: Edebug Recursive Edit, Prev: Checking Whether to Stop, Up: The Outside Context
-
-Edebug Display Update
-.....................
-
- When Edebug needs to display something (e.g., in trace mode), it
-saves the current window configuration from "outside" Edebug. When you
-exit Edebug (by continuing the program), it restores the previous window
-configuration.
-
- XEmacs redisplays only when it pauses. Usually, when you continue
-execution, the program comes back into Edebug at a breakpoint or after
-stepping without pausing or reading input in between. In such cases,
-XEmacs never gets a chance to redisplay the "outside" configuration.
-What you see is the same window configuration as the last time Edebug
-was active, with no interruption.
-
- Entry to Edebug for displaying something also saves and restores the
-following data, but some of these are deliberately not restored if an
-error or quit signal occurs.
-
- * Which buffer is current, and where point and mark are in the
- current buffer are saved and restored.
-
- * The Edebug Display Update, is saved and restored if
- `edebug-save-windows' is non-`nil'. It is not restored on error
- or quit, but the outside selected window *is* reselected even on
- error or quit in case a `save-excursion' is active. If the value
- of `edebug-save-windows' is a list, only the listed windows are
- saved and restored.
-
- The window start and horizontal scrolling of the source code
- buffer are not restored, however, so that the display remains
- coherent.
-
- * The value of point in each displayed buffer is saved and restored
- if `edebug-save-displayed-buffer-points' is non-`nil'.
-
- * The variables `overlay-arrow-position' and `overlay-arrow-string'
- are saved and restored. So you can safely invoke Edebug from the
- recursive edit elsewhere in the same buffer.
-
- * `cursor-in-echo-area' is locally bound to `nil' so that the cursor
- shows up in the window.
-
-\1f
-File: lispref.info, Node: Edebug Recursive Edit, Prev: Edebug Display Update, Up: The Outside Context
-
-Edebug Recursive Edit
-.....................
-
- When Edebug is entered and actually reads commands from the user, it
-saves (and later restores) these additional data:
-
- * The current match data, for whichever buffer was current.
-
- * `last-command', `this-command', `last-command-char',
- `last-input-char', `last-input-event', `last-command-event',
- `last-event-frame', `last-nonmenu-event', and `track-mouse' .
- Commands used within Edebug do not affect these variables outside
- of Edebug.
-
- The key sequence returned by `this-command-keys' is changed by
- executing commands within Edebug and there is no way to reset the
- key sequence from Lisp.
-
- For Emacs 18, Edebug cannot save and restore the value of
- `unread-command-char'. Entering Edebug while this variable has a
- nontrivial value can interfere with execution of the program you
- are debugging.
-
- * Complex commands executed while in Edebug are added to the variable
- `command-history'. In rare cases this can alter execution.
-
- * Within Edebug, the recursion depth appears one deeper than the
- recursion depth outside Edebug. This is not true of the
- automatically updated evaluation list window.
-
- * `standard-output' and `standard-input' are bound to `nil' by the
- `recursive-edit', but Edebug temporarily restores them during
- evaluations.
-
- * The state of keyboard macro definition is saved and restored.
- While Edebug is active, `defining-kbd-macro' is bound to
- `edebug-continue-kbd-macro'.
-
-\1f
-File: lispref.info, Node: Instrumenting Macro Calls, Next: Edebug Options, Prev: The Outside Context, Up: Edebug
-
-Instrumenting Macro Calls
--------------------------
-
- When Edebug instruments an expression that calls a Lisp macro, it
-needs additional advice to do the job properly. This is because there
-is no way to tell which subexpressions of the macro call may be
-evaluated. (Evaluation may occur explicitly in the macro body, or when
-the resulting expansion is evaluated, or any time later.) You must
-explain the format of macro call arguments by using `def-edebug-spec' to
-define an "Edebug specification" for each macro.
-
- - Macro: def-edebug-spec MACRO SPECIFICATION
- Specify which expressions of a call to macro MACRO are forms to be
- evaluated. For simple macros, the SPECIFICATION often looks very
- similar to the formal argument list of the macro definition, but
- specifications are much more general than macro arguments.
-
- The MACRO argument may actually be any symbol, not just a macro
- name.
-
- Unless you are using Emacs 19 or XEmacs, this macro is only defined
- in Edebug, so you may want to use the following which is
- equivalent: `(put 'MACRO 'edebug-form-spec 'SPECIFICATION)'
-
- Here is a simple example that defines the specification for the
-`for' macro described in the XEmacs Lisp Reference Manual, followed by
-an alternative, equivalent specification.
-
- (def-edebug-spec for
- (symbolp "from" form "to" form "do" &rest form))
-
- (def-edebug-spec for
- (symbolp ['from form] ['to form] ['do body]))
-
- Here is a table of the possibilities for SPECIFICATION and how each
-directs processing of arguments.
-
-*`t'
- All arguments are instrumented for evaluation.
-
-*`0'
- None of the arguments is instrumented.
-
-*a symbol
- The symbol must have an Edebug specification which is used instead.
- This indirection is repeated until another kind of specification is
- found. This allows you to inherit the specification for another
- macro.
-
-*a list
- The elements of the list describe the types of the arguments of a
- calling form. The possible elements of a specification list are
- described in the following sections.
-
-* Menu:
-
-* Specification List:: How to specify complex patterns of evaluation.
-* Backtracking:: What Edebug does when matching fails.
-* Debugging Backquote:: Debugging Backquote
-* Specification Examples:: To help understand specifications.
-
-\1f
-File: lispref.info, Node: Specification List, Next: Backtracking, Up: Instrumenting Macro Calls
-
-Specification List
-..................
-
- A "specification list" is required for an Edebug specification if
-some arguments of a macro call are evaluated while others are not. Some
-elements in a specification list match one or more arguments, but others
-modify the processing of all following elements. The latter, called
-"keyword specifications", are symbols beginning with ``&'' (e.g.
-`&optional').
-
- A specification list may contain sublists which match arguments that
-are themselves lists, or it may contain vectors used for grouping.
-Sublists and groups thus subdivide the specification list into a
-hierarchy of levels. Keyword specifications only apply to the
-remainder of the sublist or group they are contained in and there is an
-implicit grouping around a keyword specification and all following
-elements in the sublist or group.
-
- If a specification list fails at some level, then backtracking may
-be invoked to find some alternative at a higher level, or if no
-alternatives remain, an error will be signaled. See *Note
-Backtracking:: for more details.
-
- Edebug specifications provide at least the power of regular
-expression matching. Some context-free constructs are also supported:
-the matching of sublists with balanced parentheses, recursive
-processing of forms, and recursion via indirect specifications.
-
- Each element of a specification list may be one of the following,
-with the corresponding type of argument:
-
-`sexp'
- A single unevaluated expression.
-
-`form'
- A single evaluated expression, which is instrumented.
-
-`place'
- A place as in the Common Lisp `setf' place argument. It will be
- instrumented just like a form, but the macro is expected to strip
- the instrumentation. Two functions, `edebug-unwrap' and
- `edebug-unwrap*', are provided to strip the instrumentation one
- level or recursively at all levels.
-
-`body'
- Short for `&rest form'. See `&rest' below.
-
-`function-form'
- A function form: either a quoted function symbol, a quoted lambda
- expression, or a form (that should evaluate to a function symbol
- or lambda expression). This is useful when function arguments
- might be quoted with `quote' rather than `function' since the body
- of a lambda expression will be instrumented either way.
-
-`lambda-expr'
- An unquoted anonymous lambda expression.
-
-`&optional'
- All following elements in the specification list are optional; as
- soon as one does not match, Edebug stops matching at this level.
-
- To make just a few elements optional followed by non-optional
- elements, use `[&optional SPECS...]'. To specify that several
- elements should all succeed together, use `&optional [SPECS...]'.
- See the `defun' example below.
-
-`&rest'
- All following elements in the specification list are repeated zero
- or more times. All the elements need not match in the last
- repetition, however.
-
- To repeat only a few elements, use `[&rest SPECS...]'. To specify
- all elements must match on every repetition, use `&rest
- [SPECS...]'.
-
-`&or'
- Each of the following elements in the specification list is an
- alternative, processed left to right until one matches. One of the
- alternatives must match otherwise the `&or' specification fails.
-
- Each list element following `&or' is a single alternative even if
- it is a keyword specification. (This breaks the implicit grouping
- rule.) To group two or more list elements as a single
- alternative, enclose them in `[...]'.
-
-`¬'
- Each of the following elements is matched as alternatives as if by
- using `&or', but if any of them match, the specification fails.
- If none of them match, nothing is matched, but the `¬'
- specification succeeds.
-
-`&define'
- Indicates that the specification is for a defining form. The
- defining form itself is not instrumented (i.e. Edebug does not
- stop before and after the defining form), but forms inside it
- typically will be instrumented. The `&define' keyword should be
- the first element in a list specification.
-
- Additional specifications that may only appear after `&define' are
- described here. See the `defun' example below.
-
- `name'
- The argument, a symbol, is the name of the defining form.
- But a defining form need not be named at all, in which case a
- unique name will be created for it.
-
- The `name' specification may be used more than once in the
- specification and each subsequent use will append the
- corresponding symbol argument to the previous name with ``@''
- between them. This is useful for generating unique but
- meaningful names for definitions such as `defadvice' and
- `defmethod'.
-
- `:name'
- The element following `:name' should be a symbol; it is used
- as an additional name component for the definition. This is
- useful to add a unique, static component to the name of the
- definition. It may be used more than once. No argument is
- matched.
-
- `arg'
- The argument, a symbol, is the name of an argument of the
- defining form. However, lambda list keywords (symbols
- starting with ``&'') are not allowed. See `lambda-list' and
- the example below.
-
- `lambda-list'
- This matches the whole argument list of an XEmacs Lisp lambda
- expression, which is a list of symbols and the keywords
- `&optional' and `&rest'
-
- `def-body'
- The argument is the body of code in a definition. This is
- like `body', described above, but a definition body must be
- instrumented with a different Edebug call that looks up
- information associated with the definition. Use `def-body'
- for the highest level list of forms within the definition.
-
- `def-form'
- The argument is a single, highest-level form in a definition.
- This is like `def-body', except use this to match a single
- form rather than a list of forms. As a special case,
- `def-form' also means that tracing information is not output
- when the form is executed. See the `interactive' example
- below.
-
-`nil'
- This is successful when there are no more arguments to match at the
- current argument list level; otherwise it fails. See sublist
- specifications and the backquote example below.
-
-`gate'
- No argument is matched but backtracking through the gate is
- disabled while matching the remainder of the specifications at
- this level. This is primarily used to generate more specific
- syntax error messages. See *Note Backtracking:: for more details.
- Also see the `let' example below.
-
-`OTHER-SYMBOL'
- Any other symbol in a specification list may be a predicate or an
- indirect specification.
-
- If the symbol has an Edebug specification, this "indirect
- specification" should be either a list specification that is used
- in place of the symbol, or a function that is called to process the
- arguments. The specification may be defined with `def-edebug-spec'
- just as for macros. See the `defun' example below.
-
- Otherwise, the symbol should be a predicate. The predicate is
- called with the argument and the specification fails if the
- predicate fails. The argument is not instrumented.
-
- Predicates that may be used include: `symbolp', `integerp',
- `stringp', `vectorp', `atom' (which matches a number, string,
- symbol, or vector), `keywordp', and `lambda-list-keywordp'. The
- last two, defined in `edebug.el', test whether the argument is a
- symbol starting with ``:'' and ``&'' respectively.
-
-`[ELEMENTS...]'
- Rather than matching a vector argument, a vector treats the
- ELEMENTS as a single "group specification".
-
-`"STRING"'
- The argument should be a symbol named STRING. This specification
- is equivalent to the quoted symbol, `'SYMBOL', where the name of
- SYMBOL is the STRING, but the string form is preferred.
-
-`'SYMBOL or (quote SYMBOL)'
- The argument should be the symbol SYMBOL. But use a string
- specification instead.
-
-`(vector ELEMENTS...)'
- The argument should be a vector whose elements must match the
- ELEMENTS in the specification. See the backquote example below.
-
-`(ELEMENTS...)'
- Any other list is a "sublist specification" and the argument must
- be a list whose elements match the specification ELEMENTS.
-
- A sublist specification may be a dotted list and the corresponding
- list argument may then be a dotted list. Alternatively, the last
- cdr of a dotted list specification may be another sublist
- specification (via a grouping or an indirect specification, e.g.
- `(spec . [(more specs...)])') whose elements match the non-dotted
- list arguments. This is useful in recursive specifications such
- as in the backquote example below. Also see the description of a
- `nil' specification above for terminating such recursion.
-
- Note that a sublist specification of the form `(specs . nil)'
- means the same as `(specs)', and `(specs .
- (sublist-elements...))' means the same as `(specs
- sublist-elements...)'.
-
-\1f
-File: lispref.info, Node: Backtracking, Next: Debugging Backquote, Prev: Specification List, Up: Instrumenting Macro Calls
-
-Backtracking
-............
-
- If a specification fails to match at some point, this does not
-necessarily mean a syntax error will be signaled; instead,
-"backtracking" will take place until all alternatives have been
-exhausted. Eventually every element of the argument list must be
-matched by some element in the specification, and every required element
-in the specification must match some argument.
-
- Backtracking is disabled for the remainder of a sublist or group when
-certain conditions occur, described below. Backtracking is reenabled
-when a new alternative is established by `&optional', `&rest', or
-`&or'. It is also reenabled initially when processing a sublist or
-group specification or an indirect specification.
-
- You might want to disable backtracking to commit to some alternative
-so that Edebug can provide a more specific syntax error message.
-Normally, if no alternative matches, Edebug reports that none matched,
-but if one alternative is committed to, Edebug can report how it failed
-to match.
-
- First, backtracking is disabled while matching any of the form
-specifications (i.e. `form', `body', `def-form', and `def-body').
-These specifications will match any form so any error must be in the
-form itself rather than at a higher level.
-
- Second, backtracking is disabled after successfully matching a quoted
-symbol or string specification, since this usually indicates a
-recognized construct. If you have a set of alternative constructs that
-all begin with the same symbol, you can usually work around this
-constraint by factoring the symbol out of the alternatives, e.g.,
-`["foo" &or [first case] [second case] ...]'.
-
- Third, backtracking may be explicitly disabled by using the `gate'
-specification. This is useful when you know that no higher
-alternatives may apply.
-
-\1f
-File: lispref.info, Node: Debugging Backquote, Next: Specification Examples, Prev: Backtracking, Up: Instrumenting Macro Calls
-
-Debugging Backquote
-...................
-
- Backquote (``') is a macro that results in an expression that may or
-may not be evaluated. It is often used to simplify the definition of a
-macro to return an expression that is evaluated, but Edebug does not
-know when this is the case. However, the forms inside unquotes (`,' and
-`,@') are evaluated and Edebug instruments them.
-
- Nested backquotes are supported by Edebug, but there is a limit on
-the support of quotes inside of backquotes. Quoted forms (with `'')
-are not normally evaluated, but if the quoted form appears immediately
-within `,' and `,@' forms, Edebug treats this as a backquoted form at
-the next higher level (even if there is not a next higher level - this
-is difficult to fix).
-
- If the backquoted forms happen to be code intended to be evaluated,
-you can have Edebug instrument them by using `edebug-`' instead of the
-regular ``'. Unquoted forms can always appear inside `edebug-`'
-anywhere a form is normally allowed. But `(, FORM)' may be used in two
-other places specially recognized by Edebug: wherever a predicate
-specification would match, and at the head of a list form in place of a
-function name or lambda expression. The FORM inside a spliced unquote,
-`(,@ FORM)', will be wrapped, but the unquote form itself will not be
-wrapped since this would interfere with the splicing.
-
- There is one other complication with using `edebug-`'. If the
-`edebug-`' call is in a macro and the macro may be called from code
-that is also instrumented, and if unquoted forms contain any macro
-arguments bound to instrumented forms, then you should modify the
-specification for the macro as follows: the specifications for those
-arguments must use `def-form' instead of `form'. (This is to
-reestablish the Edebugging context for those external forms.)
-
- For example, the `for' macro (*note Problems with Macros: ()Problems
-with Macros.) is shown here but with `edebug-`' substituted for regular
-``'.
-
- (defmacro inc (var)
- (list 'setq var (list '1+ var)))
-
- (defmacro for (var from init to final do &rest body)
- (let ((tempvar (make-symbol "max")))
- (edebug-` (let (((, var) (, init))
- ((, tempvar) (, final)))
- (while (<= (, var) (, tempvar))
- (, body)
- (inc (, var)))))))
-
- Here is the corresponding modified Edebug specification and some code
-that calls the macro:
-
- (def-edebug-spec for
- (symbolp "from" def-form "to" def-form "do" &rest def-form))
-
- (let ((n 5))
- (for i from n to (* n (+ n 1)) do
- (message "%s" i)))
-
- After instrumenting the `for' macro and the macro call, Edebug first
-steps to the beginning of the macro call, then into the macro body,
-then through each of the unquoted expressions in the backquote showing
-the expressions that will be embedded in the backquote form. Then when
-the macro expansion is evaluated, Edebug will step through the `let'
-form and each time it gets to an unquoted form, it will jump back to an
-argument of the macro call to step through that expression. Finally
-stepping will continue after the macro call. Even more convoluted
-execution paths may result when using anonymous functions.
-
- When the result of an expression is an instrumented expression, it is
-difficult to see the expression inside the instrumentation. So you may
-want to set the option `edebug-unwrap-results' to a non-`nil' value
-while debugging such expressions, but it would slow Edebug down to
-always do this.
-
-\1f
-File: lispref.info, Node: Specification Examples, Prev: Debugging Backquote, Up: Instrumenting Macro Calls
-
-Specification Examples
-......................
-
- Here we provide several examples of Edebug specifications to show
-many of its capabilities.
-
- A `let' special form has a sequence of bindings and a body. Each of
-the bindings is either a symbol or a sublist with a symbol and optional
-value. In the specification below, notice the `gate' inside of the
-sublist to prevent backtracking.
-
- (def-edebug-spec let
- ((&rest
- &or symbolp (gate symbolp &optional form))
- body))
-
- Edebug uses the following specifications for `defun' and `defmacro'
-and the associated argument list and `interactive' specifications. It
-is necessary to handle the expression argument of an interactive form
-specially since it is actually evaluated outside of the function body.
-
- (def-edebug-spec defmacro defun) ; Indirect ref to `defun' spec
- (def-edebug-spec defun
- (&define name lambda-list
- [&optional stringp] ; Match the doc string, if present.
- [&optional ("interactive" interactive)]
- def-body))
-
- (def-edebug-spec lambda-list
- (([&rest arg]
- [&optional ["&optional" arg &rest arg]]
- &optional ["&rest" arg]
- )))
-
- (def-edebug-spec interactive
- (&optional &or stringp def-form)) ; Notice: `def-form'
-
- The specification for backquote below illustrates how to match
-dotted lists and use `nil' to terminate recursion. It also illustrates
-how components of a vector may be matched. (The actual specification
-provided by Edebug does not support dotted lists because doing so
-causes very deep recursion that could fail.)
-
- (def-edebug-spec ` (backquote-form)) ;; alias just for clarity
-
- (def-edebug-spec backquote-form
- (&or ([&or "," ",@"] &or ("quote" backquote-form) form)
- (backquote-form . [&or nil backquote-form])
- (vector &rest backquote-form)
- sexp))
-
-\1f
-File: lispref.info, Node: Edebug Options, Prev: Instrumenting Macro Calls, Up: Edebug
-
-Edebug Options
---------------
-
- These options affect the behavior of Edebug:
-
- - User Option: edebug-setup-hook
- Functions to call before Edebug is used. Each time it is set to a
- new value, Edebug will call those functions once and then
- `edebug-setup-hook' is reset to `nil'. You could use this to load
- up Edebug specifications associated with a package you are using
- but only when you also use Edebug. See *Note Instrumenting::.
-
- - User Option: edebug-all-defs
- If non-`nil', normal evaluation of any defining forms (e.g.
- `defun' and `defmacro') will instrument them for Edebug. This
- applies to `eval-defun', `eval-region', and `eval-current-buffer'.
-
- Use the command `M-x edebug-all-defs' to toggle the value of this
- variable. You may want to make this variable local to each buffer
- by calling `(make-local-variable 'edebug-all-defs)' in your
- `emacs-lisp-mode-hook'. See *Note Instrumenting::.
-
- - User Option: edebug-all-forms
- If non-`nil', normal evaluation of any forms by `eval-defun',
- `eval-region', and `eval-current-buffer' will instrument them for
- Edebug.
-
- Use the command `M-x edebug-all-forms' to toggle the value of this
- option. See *Note Instrumenting::.
-
- - User Option: edebug-save-windows
- If non-`nil', save and restore window configuration on Edebug
- calls. It takes some time to do this, so if your program does not
- care what happens to data about windows, you may want to set this
- variable to `nil'.
-
- If the value is a list, only the listed windows are saved and
- restored.
-
- `M-x edebug-toggle-save-windows' may be used to change this
- variable. This command is bound to `W' in source code buffers.
- See *Note Edebug Display Update::.
-
- - User Option: edebug-save-displayed-buffer-points
- If non-`nil', save and restore point in all displayed buffers.
- This is necessary if you are debugging code that changes the point
- of a buffer which is displayed in a non-selected window. If
- Edebug or the user then selects the window, the buffer's point
- will be changed to the window's point.
-
- This is an expensive operation since it visits each window and
- therefore each displayed buffer twice for each Edebug activation,
- so it is best to avoid it if you can. See *Note Edebug Display
- Update::.
-
- - User Option: edebug-initial-mode
- If this variable is non-`nil', it specifies the initial execution
- mode for Edebug when it is first activated. Possible values are
- `step', `next', `go', `Go-nonstop', `trace', `Trace-fast',
- `continue', and `Continue-fast'.
-
- The default value is `step'. See *Note Edebug Execution Modes::.
-
- - User Option: edebug-trace
- Non-`nil' means display a trace of function entry and exit.
- Tracing output is displayed in a buffer named `*edebug-trace*', one
- function entry or exit per line, indented by the recursion level.
-
- The default value is `nil'.
-
- Also see `edebug-tracing'. See *Note Tracing::.
-
- - User Option: edebug-test-coverage
- If non-`nil', Edebug tests coverage of all expressions debugged.
- This is done by comparing the result of each expression with the
- previous result. Coverage is considered OK if two different
- results are found. So to sufficiently test the coverage of your
- code, try to execute it under conditions that evaluate all
- expressions more than once, and produce different results for each
- expression.
-
- Use `M-x edebug-display-freq-count' to display the frequency count
- and coverage information for a definition. See *Note Coverage
- Testing::.
-
- - User Option: edebug-continue-kbd-macro
- If non-`nil', continue defining or executing any keyboard macro
- that is executing outside of Edebug. Use this with caution since
- it is not debugged. See *Note Edebug Execution Modes::.
-
- - User Option: edebug-print-length
- If non-`nil', bind `print-length' to this while printing results
- in Edebug. The default value is `50'. See *Note Printing in
- Edebug::.
-
- - User Option: edebug-print-level
- If non-`nil', bind `print-level' to this while printing results in
- Edebug. The default value is `50'.
-
- - User Option: edebug-print-circle
- If non-`nil', bind `print-circle' to this while printing results
- in Edebug. The default value is `nil'.
-
- - User Option: edebug-on-error
- `debug-on-error' is bound to this while Edebug is active. See
- *Note Trapping Errors::.
-
- - User Option: edebug-on-quit
- `debug-on-quit' is bound to this while Edebug is active. See
- *Note Trapping Errors::.
-
- - User Option: edebug-unwrap-results
- Non-`nil' if Edebug should unwrap results of expressions. This is
- useful when debugging macros where the results of expressions are
- instrumented expressions. But don't do this when results might be
- circular or an infinite loop will result. See *Note Debugging
- Backquote::.
-
- - User Option: edebug-global-break-condition
- If non-`nil', an expression to test for at every stop point. If
- the result is non-nil, then break. Errors are ignored. See *Note
- Global Break Condition::.
-
-\1f
-File: lispref.info, Node: Read and Print, Next: Minibuffers, Prev: Debugging, Up: Top
-
-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 read syntax described in *Note Lisp Data Types::.
-
- 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:: Overview of streams, reading and printing.
-* Input Streams:: Various data types that can be used as input streams.
-* Input Functions:: Functions to read Lisp objects from text.
-* Output Streams:: Various data types that can be used as output streams.
-* Output Functions:: Functions to print Lisp objects as text.
-* Output Variables:: Variables that control what the printing functions do.
-
-\1f
-File: lispref.info, Node: Streams Intro, Next: Input Streams, Up: Read and Print
-
-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. We call the text the
-"read syntax" of the object. For example, the text `(a . 5)' is the
-read syntax for a cons cell whose CAR is `a' and whose CDR is the
-number 5.
-
- "Printing" a Lisp object means producing text that represents that
-object--converting the object to its printed representation. Printing
-the cons cell described above produces the text `(a . 5)'.
-
- Reading and printing are more or less inverse operations: printing
-the object that results from reading a given piece of text often
-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 `a' and `b'.
-
- However, these two operations are not precisely inverses. There are
-three kinds of exceptions:
-
- * Printing can produce text that cannot be read. For example,
- buffers, windows, frames, 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 printing must choose one of them.
-
- * Comments can appear at certain points in the middle of an object's
- read sequence without affecting the result of reading it.
-
projects / chise / xemacs-chise.git.1 / blobdiff