diff options
Diffstat (limited to 'doc/ref/api-debug.texi')
-rw-r--r-- | doc/ref/api-debug.texi | 361 |
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: |