finish cleaning out api-options.texi
* 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
parent
84898084c0
commit
1cfdb1bbca
2 changed files with 105 additions and 111 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Finally, for more information on debugger options, @xref{Debug on
|
||||
Error}.
|
||||
|
||||
|
||||
@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
|
||||
|
||||
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
|
||||
Quits the recursive prompt
|
||||
@item
|
||||
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
|
||||
|
||||
@smalllisp
|
||||
guile> (define abc "hello")
|
||||
guile> abc
|
||||
"hello"
|
||||
guile> 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)
|
||||
|
||||
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:
|
||||
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
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue