summaryrefslogtreecommitdiff
path: root/doc/ref/api-options.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2010-10-01 11:47:53 +0200
committerAndy Wingo <wingo@pobox.com>2010-10-01 11:47:53 +0200
commit1cfdb1bbcadfdba7b83677e5b25772ff0f38163e (patch)
tree44686f3a7a1f6537d1650c528fdbee8ee3e84ab8 /doc/ref/api-options.texi
parent84898084c0a56dbcf1e4753ae73d4462425cf9fa (diff)
downloadguile-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.texi139
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