diff options
author | Marius Vollmer <mvo@zagadka.de> | 2004-04-21 14:33:05 +0000 |
---|---|---|
committer | Marius Vollmer <mvo@zagadka.de> | 2004-04-21 14:33:05 +0000 |
commit | 3229f68b5ae839715d8b27ac916259f4d4113804 (patch) | |
tree | 2c7547b292a8c0464aa9ebff3fd238fe874f1c97 /doc/ref/scheme-debug.texi | |
parent | b1cb24ff0a1f5b9f85dc59cae7638a26dc693b8d (diff) | |
download | guile-3229f68b5ae839715d8b27ac916259f4d4113804.tar.gz |
Big reorganization of the whole manual to give it a simpler structure.
Diffstat (limited to 'doc/ref/scheme-debug.texi')
-rw-r--r-- | doc/ref/scheme-debug.texi | 266 |
1 files changed, 0 insertions, 266 deletions
diff --git a/doc/ref/scheme-debug.texi b/doc/ref/scheme-debug.texi index 74465014f..e69de29bb 100644 --- a/doc/ref/scheme-debug.texi +++ b/doc/ref/scheme-debug.texi @@ -1,266 +0,0 @@ -@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 -@chapter Debugging Infrastructure - -@menu -* 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 Source Properties -@section 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 -@section 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 -@section 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 -@section 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 -@section 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 -@section 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 -@section 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: |