dmbcs/guile
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

finish cleaning out api-options.texi

Browse source 
* doc/ref/api-debug.texi (Debug on Error): Move debug options here (for
  now). Leave debug-options-interface undocumented.

* doc/ref/api-options.texi (Runtime Options): Remove debug options. Link
  to the sections where the options documentation is now. Update the
  options example transcript.
This commit is contained in:
Andy Wingo 2010-10-01 11:47:53 +02:00
commit 1cfdb1bbca
2 changed files with 105 additions and 111 deletions
Download patch file Download diff file Expand all files Collapse all files

77
doc/ref/api-debug.texi
View file

@ -508,6 +508,83 @@ Debugging} for more information about this.
Invoke the Guile debugger to explore the context of the last error. Invoke the Guile debugger to explore the context of the last error.
@end deffn @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 @node Traps
@subsection Traps @subsection Traps

139
doc/ref/api-options.texi
View file

@ -374,79 +374,17 @@ than to test for the corresponding feature using @code{provided?}.
@node Runtime Options @node Runtime Options
@subsection Runtime Options @subsection Runtime Options
Guile's runtime behaviour can be modified by setting options. For There are a number of runtime options available for paramaterizing
example, is the language that Guile accepts case sensitive, or should built-in procedures, like @code{read}, and built-in behavior, like what
the debugger automatically show a backtrace on error? happens on an uncaught error.
Guile has two levels of interface for managing options: a low-level For more information on reader options, @xref{Scheme Read}.
control interface, and a user-level interface which allows the enabling
or disabling of options.
Moreover, the options are classified in groups according to whether they For more information on print options, @xref{Scheme Write}.
configure @emph{reading}, @emph{printing}, or @emph{debugging}.
@menu Finally, for more information on debugger options, @xref{Debug on
* Debugger options:: Error}.
* 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
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 @subsubsection Examples of option use
Here is an example of a session in which some read and debug option Here is an example of a session in which some read and debug option
@ -461,53 +399,32 @@ is set to ``no''.
@item @item
Enables @code{case-insensitive} Enables @code{case-insensitive}
@item @item
Quits the recursive prompt
@item
Verifies that now @code{aBc} and @code{abc} are the same Verifies that now @code{aBc} and @code{abc} are the same
@item
Disables @code{case-insensitive} and enables debugging @code{backtrace}
@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.]
@end enumerate @end enumerate
@smalllisp @smalllisp
guile> (define abc "hello") scheme@@(guile-user)> (define abc "hello")
guile> abc scheme@@(guile-user)> abc
"hello" $1 = "hello"
guile> aBc scheme@@(guile-user)> aBc
ERROR: In expression aBc: <unknown-location>: warning: possibly unbound variable `aBc'
ERROR: In procedure module-lookup:
ERROR: Unbound variable: aBc ERROR: Unbound variable: aBc
ABORT: (misc-error) Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
scheme@@(guile-user) [1]> (read-options 'help)
Type "(backtrace)" to get more information. copy no Copy source code expressions.
guile> (read-options 'help) positions yes Record positions of source code expressions.
keywords #f Style of keyword recognition: #f, 'prefix or 'postfix case-insensitive no Convert symbols to lower case.
case-insensitive no Convert symbols to lower case. keywords #f Style of keyword recognition: #f, 'prefix or 'postfix.
positions yes Record positions of source code expressions. r6rs-hex-escapes no Use R6RS variable-length character and string hex escapes.
copy no Copy source code expressions. square-brackets yes Treat `[' and `]' as parentheses, for R6RS compatibility.
guile> (debug-options 'help) scheme@@(guile-user) [1]> (read-enable 'case-insensitive)
stack 20000 Stack size limit (0 = no check). $2 = (square-brackets keywords #f case-insensitive positions)
backtrace no Show backtrace on error. scheme@@(guile-user) [1]> ,q
depth 20 Maximal length of printed backtrace. scheme@@(guile-user)> aBc
backwards no Display backtrace in anti-chronological order. $3 = "hello"
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:
ERROR: Unbound variable: aBc
ABORT: (misc-error)
guile>
@end smalllisp @end smalllisp