summaryrefslogtreecommitdiff
path: root/doc/ref/api-debug.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/api-debug.texi')
-rw-r--r--doc/ref/api-debug.texi361
1 files changed, 361 insertions, 0 deletions
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
new file mode 100644
index 000000000..cf4b2800a
--- /dev/null
+++ b/doc/ref/api-debug.texi
@@ -0,0 +1,361 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
+@page
+@node Debugging
+@section Debugging Infrastructure
+
+@menu
+* Interactive Debugging:: Functions intended for interactive use.
+* Breakpoints::
+* Source Properties:: Remembering the source of an expression.
+* Using Traps::
+* Capturing the Stack or Innermost Stack Frame::
+* Examining the Stack::
+* Examining Stack Frames::
+* Decoding Memoized Source Expressions::
+* Starting a New Stack::
+@end menu
+
+@node Interactive Debugging
+@subsection Interactive Debugging
+
+@deffn {Scheme Procedure} backtrace
+@deffnx {C Function} scm_backtrace ()
+Display a backtrace of the stack saved by the last error
+to the current output port.
+@end deffn
+
+@deffn {Scheme Procedure} debug
+Invoke the Guile debugger to explore the context of the last error.
+@end deffn
+
+@node Breakpoints
+@subsection Breakpoints
+
+@deffn {Generic Function} set-breakpoint! behaviour . location-args
+Set a breakpoint with behaviour @var{behaviour} at the location
+specified by @var{location-args}.
+
+The form of the @var{location-args} depends upon what methods for
+@code{set-breakpoint!} have been provided by the implementations of
+subclasses of the @code{<breakpoint>} base class.
+@end deffn
+
+@deffn {Generic Function} get-breakpoint . location-args
+Find and return the breakpoint instance at the location specified by
+@var{location-args}.
+
+The form of the @var{location-args} depends upon what methods for
+@code{get-breakpoint} have been provided by the implementations of
+subclasses of the @code{<breakpoint>} base class.
+@end deffn
+
+@deffn {Method} set-breakpoint! behaviour (proc <procedure>)
+Set a breakpoint with behaviour @var{behaviour} before applications of
+the procedure @var{proc}.
+@end deffn
+
+@deffn {Method} set-breakpoint! behaviour x-as-read (x-pairified <pair>)
+Set a breakpoint with behaviour @var{behaviour} on the source expression
+@var{x-pairified}, storing @var{x-as-read} for use in messages
+describing the breakpoint.
+@end deffn
+
+@deffn {Method} set-breakpoint! behaviour (number <integer>)
+Change the behaviour of existing breakpoint number @var{number} to
+@var{behaviour}.
+@end deffn
+
+@deffn {Accessor} bp-behaviour breakpoint
+Get or set the behaviour of the breakpoint instance @var{breakpoint}.
+@end deffn
+
+@deffn {Accessor} bp-enabled? breakpoint
+Get or set the enabled state of the specified @var{breakpoint}.
+@end deffn
+
+@deffn {Procedure} enable-breakpoint! . location-args
+@deffnx {Procedure} disable-breakpoint! . location-args
+Enable or disable the breakpoint at the location specified by
+@var{location-args}.
+@end deffn
+
+@deffn {Generic Function} bp-delete! breakpoint
+Delete breakpoint @var{breakpoint}. This means (1) doing whatever is
+needed to prevent the breakpoint from triggering again, and (2) removing
+it from the global list of current breakpoints.
+@end deffn
+
+@deffn {Procedure} delete-breakpoint! . location-args
+Delete the breakpoint at the location specified by @var{location-args}.
+@end deffn
+
+@deffn {Generic Function} bp-describe breakpoint port
+Print a description of @var{breakpoint} to the specified @var{port}.
+@var{port} can be @code{#t} for standard output, or else any output
+port.
+@end deffn
+
+@deffn {Procedure} describe-breakpoint . location-args
+Print (to standard output) a description of the breakpoint at location
+specified by @var{location-args}.
+@end deffn
+
+@deffn {Procedure} all-breakpoints
+Return a list of all current breakpoints, ordered by breakpoint number.
+@end deffn
+
+@deffn {Procedure} describe-all-breakpoints
+Print a description of all current breakpoints to standard output.
+@end deffn
+
+
+@node Source Properties
+@subsection Source Properties
+
+@cindex source properties
+As Guile reads in Scheme code from file or from standard input, it
+remembers the file name, line number and column number where each
+expression begins. These pieces of information are known as the
+@dfn{source properties} of the expression. If an expression undergoes
+transformation --- for example, if there is a syntax transformer in
+effect, or the expression is a macro call --- the source properties are
+copied from the untransformed to the transformed expression so that, if
+an error occurs when evaluating the transformed expression, Guile's
+debugger can point back to the file and location where the expression
+originated.
+
+The way that source properties are stored means that Guile can only
+associate source properties with parenthesized expressions, and not, for
+example, with individual symbols, numbers or strings. The difference
+can be seen by typing @code{(xxx)} and @code{xxx} at the Guile prompt
+(where the variable @code{xxx} has not been defined):
+
+@example
+guile> (xxx)
+standard input:2:1: In expression (xxx):
+standard input:2:1: Unbound variable: xxx
+ABORT: (unbound-variable)
+guile> xxx
+<unnamed port>: In expression xxx:
+<unnamed port>: Unbound variable: xxx
+ABORT: (unbound-variable)
+@end example
+
+@noindent
+In the latter case, no source properties were stored, so the best that
+Guile could say regarding the location of the problem was ``<unnamed
+port>''.
+
+The recording of source properties is controlled by the read option
+named ``positions'' (@pxref{Reader options}). This option is switched
+@emph{on} by default, together with the debug options ``debug'' and
+``backtrace'' (@pxref{Debugger options}), when Guile is run
+interactively; all these options are @emph{off} by default when Guile
+runs a script non-interactively.
+
+
+@node Using Traps
+@subsection Using Traps
+
+@deffn {Scheme Procedure} with-traps thunk
+@deffnx {C Function} scm_with_traps (thunk)
+Call @var{thunk} with traps enabled.
+@end deffn
+
+@deffn {Scheme Procedure} debug-object? obj
+@deffnx {C Function} scm_debug_object_p (obj)
+Return @code{#t} if @var{obj} is a debug object.
+@end deffn
+
+
+@node Capturing the Stack or Innermost Stack Frame
+@subsection Capturing the Stack or Innermost Stack Frame
+
+When an error occurs in a running program, or the program hits a
+breakpoint, its state at that point can be represented by a @dfn{stack}
+of all the evaluations and procedure applications that are logically in
+progress at that time, each of which is known as a @dfn{frame}. The
+programmer can learn more about the program's state at the point of
+interruption or error by inspecting the stack and its frames.
+
+@deffn {Scheme Procedure} make-stack obj . args
+@deffnx {C Function} scm_make_stack (obj, args)
+Create a new stack. If @var{obj} is @code{#t}, the current
+evaluation stack is used for creating the stack frames,
+otherwise the frames are taken from @var{obj} (which must be
+either a debug object or a continuation).
+
+@var{args} should be a list containing any combination of
+integer, procedure and @code{#t} values.
+
+These values specify various ways of cutting away uninteresting
+stack frames from the top and bottom of the stack that
+@code{make-stack} returns. They come in pairs like this:
+@code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2}
+@var{outer_cut_2} @dots{})}.
+
+Each @var{inner_cut_N} can be @code{#t}, an integer, or a
+procedure. @code{#t} means to cut away all frames up to but
+excluding the first user module frame. An integer means to cut
+away exactly that number of frames. A procedure means to cut
+away all frames up to but excluding the application frame whose
+procedure matches the specified one.
+
+Each @var{outer_cut_N} can be an integer or a procedure. An
+integer means to cut away that number of frames. A procedure
+means to cut away frames down to but excluding the application
+frame whose procedure matches the specified one.
+
+If the @var{outer_cut_N} of the last pair is missing, it is
+taken as 0.
+@end deffn
+
+@deffn {Scheme Procedure} last-stack-frame obj
+@deffnx {C Function} scm_last_stack_frame (obj)
+Return a stack which consists of a single frame, which is the
+last stack frame for @var{obj}. @var{obj} must be either a
+debug object or a continuation.
+@end deffn
+
+
+@node Examining the Stack
+@subsection Examining the Stack
+
+@deffn {Scheme Procedure} stack? obj
+@deffnx {C Function} scm_stack_p (obj)
+Return @code{#t} if @var{obj} is a calling stack.
+@end deffn
+
+@deffn {Scheme Procedure} stack-id stack
+@deffnx {C Function} scm_stack_id (stack)
+Return the identifier given to @var{stack} by @code{start-stack}.
+@end deffn
+
+@deffn {Scheme Procedure} stack-length stack
+@deffnx {C Function} scm_stack_length (stack)
+Return the length of @var{stack}.
+@end deffn
+
+@deffn {Scheme Procedure} stack-ref stack index
+@deffnx {C Function} scm_stack_ref (stack, index)
+Return the @var{index}'th frame from @var{stack}.
+@end deffn
+
+@deffn {Scheme Procedure} display-backtrace stack port [first [depth]]
+@deffnx {C Function} scm_display_backtrace (stack, port, first, depth)
+Display a backtrace to the output port @var{port}. @var{stack}
+is the stack to take the backtrace from, @var{first} specifies
+where in the stack to start and @var{depth} how much frames
+to display. Both @var{first} and @var{depth} can be @code{#f},
+which means that default values will be used.
+@end deffn
+
+
+@node Examining Stack Frames
+@subsection Examining Stack Frames
+
+@deffn {Scheme Procedure} frame? obj
+@deffnx {C Function} scm_frame_p (obj)
+Return @code{#t} if @var{obj} is a stack frame.
+@end deffn
+
+@deffn {Scheme Procedure} frame-number frame
+@deffnx {C Function} scm_frame_number (frame)
+Return the frame number of @var{frame}.
+@end deffn
+
+@deffn {Scheme Procedure} frame-previous frame
+@deffnx {C Function} scm_frame_previous (frame)
+Return the previous frame of @var{frame}, or @code{#f} if
+@var{frame} is the first frame in its stack.
+@end deffn
+
+@deffn {Scheme Procedure} frame-next frame
+@deffnx {C Function} scm_frame_next (frame)
+Return the next frame of @var{frame}, or @code{#f} if
+@var{frame} is the last frame in its stack.
+@end deffn
+
+@deffn {Scheme Procedure} frame-source frame
+@deffnx {C Function} scm_frame_source (frame)
+Return the source of @var{frame}.
+@end deffn
+
+@deffn {Scheme Procedure} frame-procedure? frame
+@deffnx {C Function} scm_frame_procedure_p (frame)
+Return @code{#t} if a procedure is associated with @var{frame}.
+@end deffn
+
+@deffn {Scheme Procedure} frame-procedure frame
+@deffnx {C Function} scm_frame_procedure (frame)
+Return the procedure for @var{frame}, or @code{#f} if no
+procedure is associated with @var{frame}.
+@end deffn
+
+@deffn {Scheme Procedure} frame-arguments frame
+@deffnx {C Function} scm_frame_arguments (frame)
+Return the arguments of @var{frame}.
+@end deffn
+
+@deffn {Scheme Procedure} frame-evaluating-args? frame
+@deffnx {C Function} scm_frame_evaluating_args_p (frame)
+Return @code{#t} if @var{frame} contains evaluated arguments.
+@end deffn
+
+@deffn {Scheme Procedure} frame-overflow? frame
+@deffnx {C Function} scm_frame_overflow_p (frame)
+Return @code{#t} if @var{frame} is an overflow frame.
+@end deffn
+
+@deffn {Scheme Procedure} frame-real? frame
+@deffnx {C Function} scm_frame_real_p (frame)
+Return @code{#t} if @var{frame} is a real frame.
+@end deffn
+
+@deffn {Scheme Procedure} display-application frame [port [indent]]
+@deffnx {C Function} scm_display_application (frame, port, indent)
+Display a procedure application @var{frame} to the output port
+@var{port}. @var{indent} specifies the indentation of the
+output.
+@end deffn
+
+
+@node Decoding Memoized Source Expressions
+@subsection Decoding Memoized Source Expressions
+
+@deffn {Scheme Procedure} memoized? obj
+@deffnx {C Function} scm_memoized_p (obj)
+Return @code{#t} if @var{obj} is memoized.
+@end deffn
+
+@deffn {Scheme Procedure} unmemoize m
+@deffnx {C Function} scm_unmemoize (m)
+Unmemoize the memoized expression @var{m},
+@end deffn
+
+@deffn {Scheme Procedure} memoized-environment m
+@deffnx {C Function} scm_memoized_environment (m)
+Return the environment of the memoized expression @var{m}.
+@end deffn
+
+
+@node Starting a New Stack
+@subsection Starting a New Stack
+
+@deffn {Scheme Syntax} start-stack id exp
+Evaluate @var{exp} on a new calling stack with identity @var{id}. If
+@var{exp} is interrupted during evaluation, backtraces will not display
+frames farther back than @var{exp}'s top-level form. This macro is a
+way of artificially limiting backtraces and stack procedures, largely as
+a convenience to the user.
+@end deffn
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End: