diff options
-rw-r--r-- | doc/ref/api-debug.texi | 77 | ||||
-rw-r--r-- | doc/ref/api-options.texi | 139 |
2 files changed, 105 insertions, 111 deletions
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index 04dc25c1c..46d0a39c8 100644 --- a/doc/ref/api-debug.texi +++ b/doc/ref/api-debug.texi @@ -508,6 +508,83 @@ Debugging} for more information about this. 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 diff --git a/doc/ref/api-options.texi b/doc/ref/api-options.texi index 3b600dbdc..6c84c7be4 100644 --- a/doc/ref/api-options.texi +++ b/doc/ref/api-options.texi @@ -374,79 +374,17 @@ than to test for the corresponding feature using @code{provided?}. @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 @@ -461,53 +399,32 @@ is set to ``no''. @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 |