+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.
+
+\1f