comparison lispref/edebug.texi @ 52840:590f500fb14b

(Edebug Execution Modes): Clarify t. Document edebug-sit-for-seconds. (Coverage Testing): Document C-x X = and =. (Instrumenting Macro Calls): Fix typo. (Specification List): Don't index the specification keywords.

52839:f4f7a204bc03

Next: stop at the next stop point encountered after an expression
(@code{edebug-next-mode}).  Also see @code{edebug-forward-sexp} in
@ref{Edebug Misc}.

@item t
Trace: pause one second at each Edebug stop point (@code{edebug-trace-mode}).

@item T
Rapid trace: update the display at each stop point, but don't actually
pause (@code{edebug-Trace-fast-mode}).

the value of the variable @code{edebug-initial-mode}.  By default, this
specifies step mode.  Note that you may reenter the same Edebug level
several times if, for example, an instrumented function is called
several times from one command.


@node Jumping
@subsection Jumping

  The commands described in this section execute until they reach a

@code{edebug-test-coverage} is non-@code{nil}.  Frequency counting is
performed for all execution of an instrumented function, even if the
execution mode is Go-nonstop, and regardless of whether coverage testing
is enabled.

  Use @kbd{M-x edebug-display-freq-count} to display both the
coverage information and the frequency counts for a definition.

@deffn Command edebug-display-freq-count
This command displays the frequency count data for each line of the
current definition.

For example, (for i from 1 to 10 do (print i))."
  (declare (edebug symbolp "from" form "to" form "do" &rest form))
  ...)
@end example

  The Edebug specifation says which parts of a call to the macro are
forms to be evaluated.  For simple macros, the @var{specification}
often looks very similar to the formal argument list of the macro
definition, but specifications are much more general than macro
arguments.  @xref{Defining Macros}, for more explanation of
the @code{declare} special form.

@item lambda-expr
A lambda expression with no quoting.

@item &optional
@kindex &optional @r{(Edebug)}
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 @code{[&optional @var{specs}@dots{}]}.  To specify that several
elements must all match or none, use @code{&optional
[@var{specs}@dots{}]}.  See the @code{defun} example below.

@item &rest
@kindex &rest @r{(Edebug)}
All following elements in the specification list are repeated zero or
more times.  In the last repetition, however, it is not a problem if the
expression runs out before matching all of the elements of the
specification list.

To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
To specify several elements that must all match on every repetition, use
@code{&rest [@var{specs}@dots{}]}.

@item &or
@kindex &or @r{(Edebug)}
Each of the following elements in the specification list is an
alternative.  One of the alternatives must match, or the @code{&or}
specification fails.

Each list element following @code{&or} is a single alternative.  To
group two or more list elements as a single alternative, enclose them in
@code{[@dots{}]}.

@item &not
@kindex &not @r{(Edebug)}
Each of the following elements is matched as alternatives as if by using
@code{&or}, but if any of them match, the specification fails.  If none
of them match, nothing is matched, but the @code{&not} specification
succeeds.

@item &define
@kindex &define @r{(Edebug)}
Indicates that the specification is for a defining form.  The defining
form itself is not instrumented (that is, Edebug does not stop before and
after the defining form), but forms inside it typically will be
instrumented.  The @code{&define} keyword should be the first element in
a list specification.

52840:590f500fb14b

Next: stop at the next stop point encountered after an expression
(@code{edebug-next-mode}).  Also see @code{edebug-forward-sexp} in
@ref{Edebug Misc}.

@item t
Trace: pause (normally one second) at each Edebug stop point
(@code{edebug-trace-mode}).

@item T
Rapid trace: update the display at each stop point, but don't actually
pause (@code{edebug-Trace-fast-mode}).

the value of the variable @code{edebug-initial-mode}.  By default, this
specifies step mode.  Note that you may reenter the same Edebug level
several times if, for example, an instrumented function is called
several times from one command.

@defopt edebug-sit-for-seconds
This option specifies how many seconds to wait between execution steps
in trace mode.  The default is 1 second.
@end defvar

@node Jumping
@subsection Jumping

  The commands described in this section execute until they reach a

@code{edebug-test-coverage} is non-@code{nil}.  Frequency counting is
performed for all execution of an instrumented function, even if the
execution mode is Go-nonstop, and regardless of whether coverage testing
is enabled.

@kindex C-x X =
@findex edebug-temp-display-freq-count
  Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both
the coverage information and the frequency counts for a definition.
Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same
information temporarily, only until you type another key.

@deffn Command edebug-display-freq-count
This command displays the frequency count data for each line of the
current definition.

For example, (for i from 1 to 10 do (print i))."
  (declare (edebug symbolp "from" form "to" form "do" &rest form))
  ...)
@end example

  The Edebug specification says which parts of a call to the macro are
forms to be evaluated.  For simple macros, the @var{specification}
often looks very similar to the formal argument list of the macro
definition, but specifications are much more general than macro
arguments.  @xref{Defining Macros}, for more explanation of
the @code{declare} special form.

@item lambda-expr
A lambda expression with no quoting.

@item &optional
@c @kindex &optional @r{(Edebug)}
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 @code{[&optional @var{specs}@dots{}]}.  To specify that several
elements must all match or none, use @code{&optional
[@var{specs}@dots{}]}.  See the @code{defun} example below.

@item &rest
@c @kindex &rest @r{(Edebug)}
All following elements in the specification list are repeated zero or
more times.  In the last repetition, however, it is not a problem if the
expression runs out before matching all of the elements of the
specification list.

To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
To specify several elements that must all match on every repetition, use
@code{&rest [@var{specs}@dots{}]}.

@item &or
@c @kindex &or @r{(Edebug)}
Each of the following elements in the specification list is an
alternative.  One of the alternatives must match, or the @code{&or}
specification fails.

Each list element following @code{&or} is a single alternative.  To
group two or more list elements as a single alternative, enclose them in
@code{[@dots{}]}.

@item &not
@c @kindex &not @r{(Edebug)}
Each of the following elements is matched as alternatives as if by using
@code{&or}, but if any of them match, the specification fails.  If none
of them match, nothing is matched, but the @code{&not} specification
succeeds.

@item &define
@c @kindex &define @r{(Edebug)}
Indicates that the specification is for a defining form.  The defining
form itself is not instrumented (that is, Edebug does not stop before and
after the defining form), but forms inside it typically will be
instrumented.  The @code{&define} keyword should be the first element in
a list specification.