diff options
author | Andy Wingo <wingo@pobox.com> | 2010-10-01 11:47:53 +0200 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2010-10-01 11:47:53 +0200 |
commit | 1cfdb1bbcadfdba7b83677e5b25772ff0f38163e (patch) | |
tree | 44686f3a7a1f6537d1650c528fdbee8ee3e84ab8 /doc/ref/api-options.texi | |
parent | 84898084c0a56dbcf1e4753ae73d4462425cf9fa (diff) | |
download | guile-1cfdb1bbcadfdba7b83677e5b25772ff0f38163e.tar.gz |
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.
Diffstat (limited to 'doc/ref/api-options.texi')
-rw-r--r-- | doc/ref/api-options.texi | 139 |
1 files changed, 28 insertions, 111 deletions
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 |