Invoke the Guile debugger to explore the context of the last error.
@end deffn
+@subsubsection Debug options
+
+The behavior when an error is the @code{backtrace} procedure and of the
+default error handler can be parameterized via the debug options.
+
+@cindex options - debug
+@cindex debug options
+@deffn {Scheme Procedure} debug-options [setting]
+Display the current settings of the debug options. If @var{setting} is
+omitted, only a short form of the current read options is printed.
+Otherwise if @var{setting} is the symbol @code{help}, a complete options
+description is displayed.
+@end deffn
+
+The set of available options, and their default values, may be had by
+invoking @code{debug-options} at the prompt.
+
+@smallexample
+scheme@@(guile-user)>
+backwards no Display backtrace in anti-chronological order.
+width 79 Maximal width of backtrace.
+depth 20 Maximal length of printed backtrace.
+backtrace yes Show backtrace on error.
+stack 1048576 Stack size limit (measured in words;
+ 0 = no check).
+show-file-name #t Show file names and line numbers in backtraces
+ when not `#f'. A value of `base' displays only
+ base names, while `#t' displays full names.
+warn-deprecated no Warn when deprecated features are used.
+@end smallexample
+
+The boolean options may be toggled with @code{debug-enable} and
+@code{debug-disable}. The non-boolean @code{keywords} option must be set
+using @code{debug-set!}.
+
+@deffn {Scheme Procedure} debug-enable option-name
+@deffnx {Scheme Procedure} debug-disable option-name
+@deffnx {Scheme Procedure} debug-set! option-name value
+Modify the debug options. @code{debug-enable} should be used with boolean
+options and switches them on, @code{debug-disable} switches them off.
+@code{debug-set!} can be used to set an option to a specific value.
+@end deffn
+
+@subsubheading Stack overflow
+
+@cindex overflow, stack
+@cindex stack overflow
+Stack overflow errors are caused by a computation trying to use more
+stack space than has been enabled by the @code{stack} option. They are
+reported like this:
+
+@lisp
+(non-tail-recursive-factorial 500)
+@print{}
+ERROR: Stack overflow
+ABORT: (stack-overflow)
+@end lisp
+
+If you get an error like this, you can either try rewriting your code to
+use less stack space, or increase the maximum stack size. To increase
+the maximum stack size, use @code{debug-set!}, for example:
+
+@lisp
+(debug-set! stack 200000)
+@result{}
+(show-file-name #t stack 200000 debug backtrace depth 20
+ maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
+
+(non-tail-recursive-factorial 500)
+@result{}
+122013682599111006870123878542304692625357434@dots{}
+@end lisp
+
+If you prefer to try rewriting your code, you may be able to save stack
+space by making some of your procedures @dfn{tail recursive}
+(@pxref{Tail Calls}).
+
@node Traps
@subsection Traps
@node Runtime Options
@subsection Runtime Options
-Guile's runtime behaviour can be modified by setting options. For
-example, is the language that Guile accepts case sensitive, or should
-the debugger automatically show a backtrace on error?
+There are a number of runtime options available for paramaterizing
+built-in procedures, like @code{read}, and built-in behavior, like what
+happens on an uncaught error.
-Guile has two levels of interface for managing options: a low-level
-control interface, and a user-level interface which allows the enabling
-or disabling of options.
+For more information on reader options, @xref{Scheme Read}.
-Moreover, the options are classified in groups according to whether they
-configure @emph{reading}, @emph{printing}, or @emph{debugging}.
+For more information on print options, @xref{Scheme Write}.
-@menu
-* Debugger options::
-* Examples of option use::
-@end menu
-
-
-@node Debugger options
-@subsubsection Debugger options
-
-Here is the list of print options generated by typing
-@code{(debug-options 'help)} in Guile. You can also see the default
-values.
-
-@smallexample
-backwards no Display backtrace in anti-chronological order.
-width 79 Maximal width of backtrace.
-depth 20 Maximal length of printed backtrace.
-backtrace yes Show backtrace on error.
-stack 1048576 Stack size limit (measured in words;
- 0 = no check).
-show-file-name #t Show file names and line numbers in backtraces
- when not `#f'. A value of `base' displays only
- base names, while `#t' displays full names.
-warn-deprecated no Warn when deprecated features are used.
-@end smallexample
-
-@subsubheading Stack overflow
-
-@cindex overflow, stack
-@cindex stack overflow
-Stack overflow errors are caused by a computation trying to use more
-stack space than has been enabled by the @code{stack} option. They are
-reported like this:
-
-@lisp
-(non-tail-recursive-factorial 500)
-@print{}
-ERROR: Stack overflow
-ABORT: (stack-overflow)
-@end lisp
+Finally, for more information on debugger options, @xref{Debug on
+Error}.
-If you get an error like this, you can either try rewriting your code to
-use less stack space, or increase the maximum stack size. To increase
-the maximum stack size, use @code{debug-set!}, for example:
-
-@lisp
-(debug-set! stack 200000)
-@result{}
-(show-file-name #t stack 200000 debug backtrace depth 20
- maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
-
-(non-tail-recursive-factorial 500)
-@result{}
-122013682599111006870123878542304692625357434@dots{}
-@end lisp
-
-If you prefer to try rewriting your code, you may be able to save stack
-space by making some of your procedures @dfn{tail recursive}
-(@pxref{Tail Calls}).
-
-
-@node Examples of option use
@subsubsection Examples of option use
Here is an example of a session in which some read and debug option
@item
Enables @code{case-insensitive}
@item
-Verifies that now @code{aBc} and @code{abc} are the same
-@item
-Disables @code{case-insensitive} and enables debugging @code{backtrace}
+Quits the recursive prompt
@item
-Reproduces the error of displaying @code{aBc} with backtracing enabled
-[FIXME: this last example is lame because there is no depth in the
-backtrace. Need to give a better example, possibly putting debugging
-option examples in a separate session.]
+Verifies that now @code{aBc} and @code{abc} are the same
@end enumerate
@smalllisp
-guile> (define abc "hello")
-guile> abc
-"hello"
-guile> aBc
-ERROR: In expression aBc:
-ERROR: Unbound variable: aBc
-ABORT: (misc-error)
-
-Type "(backtrace)" to get more information.
-guile> (read-options 'help)
-keywords #f Style of keyword recognition: #f, 'prefix or 'postfix
-case-insensitive no Convert symbols to lower case.
-positions yes Record positions of source code expressions.
-copy no Copy source code expressions.
-guile> (debug-options 'help)
-stack 20000 Stack size limit (0 = no check).
-backtrace no Show backtrace on error.
-depth 20 Maximal length of printed backtrace.
-backwards no Display backtrace in anti-chronological order.
-guile> (read-enable 'case-insensitive)
-(keywords #f case-insensitive positions)
-guile> aBc
-"hello"
-guile> (read-disable 'case-insensitive)
-(keywords #f positions)
-guile> (debug-enable 'backtrace)
-(stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
-guile> aBc
-
-Backtrace:
-0* aBc
-
-ERROR: In expression aBc:
+scheme@@(guile-user)> (define abc "hello")
+scheme@@(guile-user)> abc
+$1 = "hello"
+scheme@@(guile-user)> aBc
+<unknown-location>: warning: possibly unbound variable `aBc'
+ERROR: In procedure module-lookup:
ERROR: Unbound variable: aBc
-ABORT: (misc-error)
-guile>
+Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
+scheme@@(guile-user) [1]> (read-options 'help)
+copy no Copy source code expressions.
+positions yes Record positions of source code expressions.
+case-insensitive no Convert symbols to lower case.
+keywords #f Style of keyword recognition: #f, 'prefix or 'postfix.
+r6rs-hex-escapes no Use R6RS variable-length character and string hex escapes.
+square-brackets yes Treat `[' and `]' as parentheses, for R6RS compatibility.
+scheme@@(guile-user) [1]> (read-enable 'case-insensitive)
+$2 = (square-brackets keywords #f case-insensitive positions)
+scheme@@(guile-user) [1]> ,q
+scheme@@(guile-user)> aBc
+$3 = "hello"
@end smalllisp
HCoop / bpt / guile.git / commitdiff