diff options
Diffstat (limited to 'doc/ref/scheme-options.texi')
-rw-r--r-- | doc/ref/scheme-options.texi | 398 |
1 files changed, 398 insertions, 0 deletions
diff --git a/doc/ref/scheme-options.texi b/doc/ref/scheme-options.texi new file mode 100644 index 000000000..d591008fe --- /dev/null +++ b/doc/ref/scheme-options.texi @@ -0,0 +1,398 @@ +@page +@node Options and Config +@chapter Runtime Options and Configuration + +Guile's 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? + +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. + +Moreover, the options are classified in groups according to whether they +configure @emph{reading}, @emph{printing}, @emph{debugging} or +@emph{evaluating}. + +@menu +* General option interface:: +* Reader options:: +* Printing options:: +* Debugger options:: +* Evaluator options:: +* Evaluator trap options:: +* Examples of option use:: +* Install Config:: Installation and configuration data. +@end menu + +@node General option interface +@section General option interface + +We will use the expression @code{<group>} to represent @code{read}, +@code{print}, @code{debug} or @code{evaluator}. + +@subheading Low level + +@c NJFIXME +@deffn primitive <group>-options-interface +@deffnx primitive read-options-interface [SOME-INT] +@deffnx primitive print-options-interface [SOME-INT] +@deffnx primitive evaluator-traps-interface [SOME-INT] +@deffnx primitive read-options-interface [SOME-INT] +[FIXME: I have just taken the comments for C routine scm_options that +implements all of these. It needs to be presented better.] + +If scm_options is called without arguments, the current option setting +is returned. If the argument is an option setting, options are altered +and the old setting is returned. If the argument isn't a list, a list +of sublists is returned, where each sublist contains option name, value +and documentation string. +@end deffn + + +@subheading User level + +@c @deftp {Data type} scm_option +@c @code{scm_option} is used to represent run time options. It can be a +@c @emph{boolean} type, in which case the option will be set by the strings +@c @code{"yes"} and @code{"no"}. It can be a +@c @end deftp + +@c NJFIXME +@deffn procedure <group>-options [arg] +@deffnx procedure read-options [arg] +@deffnx procedure print-options [arg] +@deffnx procedure debug-options [arg] +@deffnx procedure traps [arg] +These functions list the options in their group. The optional argument +@var{arg} is a symbol which modifies the form in which the options are +presented. + +With no arguments, @code{<group>-options} returns the values of the +options in that particular group. If @var{arg} is @code{'help}, a +description of each option is given. If @var{arg} is @code{'full}, +programmers' options are also shown. + +@var{arg} can also be a list representing the state of all options. In +this case, the list contains single symbols (for enabled boolean +options) and symbols followed by values. +@end deffn +[FIXME: I don't think 'full is ever any different from 'help. What's +up?] + +@c NJFIXME +@deffn procedure <group>-enable option-symbol +@deffnx procedure read-enable option-symbol +@deffnx procedure print-enable option-symbol +@deffnx procedure debug-enable option-symbol +@deffnx procedure trap-enable option-symbol +These functions set the specified @var{option-symbol} in their options +group. They only work if the option is boolean, and throw an error +otherwise. +@end deffn + +@c NJFIXME +@deffn procedure <group>-disable option-symbol +@deffnx procedure read-disable option-symbol +@deffnx procedure print-disable option-symbol +@deffnx procedure debug-disable option-symbol +@deffnx procedure trap-disable option-symbol +These functions turn off the specified @var{option-symbol} in their +options group. They only work if the option is boolean, and throw an +error otherwise. +@end deffn + +@c NJFIXME +@deffn syntax <group>-set! option-symbol value +@deffnx syntax read-set! option-symbol value +@deffnx syntax print-set! option-symbol value +@deffnx syntax debug-set! option-symbol value +@deffnx syntax trap-set! option-symbol value +These functions set a non-boolean @var{option-symbol} to the specified +@var{value}. +@end deffn + + +@node Reader options +@section Reader options +@cindex options - read +@cindex read options + +Here is the list of reader options generated by typing +@code{(read-options 'full)} in Guile. You can also see the default +values. + +@smalllisp +keywords #f Style of keyword recognition: #f or 'prefix +case-insensitive no Convert symbols to lower case. +positions yes Record positions of source code expressions. +copy no Copy source code expressions. +@end smalllisp + +Notice that while Standard Scheme is case insensitive, to ease +translation of other Lisp dialects, notably Emacs Lisp, into Guile, +Guile is case-sensitive by default. + +To make Guile case insensitive, you can type + +@smalllisp +(read-enable 'case-insensitive) +@end smalllisp + +@node Printing options +@section Printing options + +Here is the list of print options generated by typing +@code{(print-options 'full)} in Guile. You can also see the default +values. + +@smallexample +source no Print closures with source. +closure-hook #f Hook for printing closures. +@end smallexample + + +@node Evaluator options +@section Evaluator options +These are the evaluator options with their default values, as they are +printed by typing @code{(eval-options 'full)} in Guile. + +@smallexample +stack 22000 Size of thread stacks (in machine words). +@end smallexample + +@node Evaluator trap options +@section Evaluator trap options +[FIXME: These flags, together with their corresponding handlers, are not +user level options. Probably this entire section should be moved to the +documentation about the low-level programmer debugging interface.] + +Here is the list of evaluator trap options generated by typing +@code{(traps 'full)} in Guile. You can also see the default values. + +@smallexample +exit-frame no Trap when exiting eval or apply. +apply-frame no Trap when entering apply. +enter-frame no Trap when eval enters new frame. +traps yes Enable evaluator traps. +@end smallexample + +@deffn apply-frame-handler key cont tailp +Called when a procedure is being applied. + +Called if: + +@itemize @bullet +@item +evaluator traps are enabled [traps interface], and +@item +either +@itemize @minus +@item +@code{apply-frame} is enabled [traps interface], or +@item +trace mode is on [debug-options interface], and the procedure being +called has the trace property enabled. +@end itemize +@end itemize + +If cheap traps are enabled [debug-options interface], @var{cont} is a +debug object, otherwise it is a restartable continuation. + +@var{tailp} is true if this is a tail call +@end deffn + +@deffn exit-frame-handler key cont retval +Called when a value is returned from a procedure. + +Called if: + +@itemize @bullet +@item +evaluator traps are enabled [traps interface], and +@item +either +@itemize @minus +@item + @code{exit-frame} is enabled [traps interface], or +@item +trace mode is on [debug-options interface], and the procedure being +called has the trace property enabled. +@end itemize +@end itemize + +If cheap traps are enabled [debug-options interface], @var{cont} is a +debug object, otherwise it is a restartable continuation. + +@var{retval} is the return value. +@end deffn + +@node Debugger options +@section Debugger options + +Here is the list of print options generated by typing +@code{(debug-options 'full)} in Guile. You can also see the default +values. + +@smallexample +stack 20000 Stack size limit (0 = no check). +debug yes Use the debugging evaluator. +backtrace no Show backtrace on error. +depth 20 Maximal length of printed backtrace. +maxdepth 1000 Maximal number of stored backtrace frames. +frames 3 Maximum number of tail-recursive frames in backtrace. +indent 10 Maximal indentation in backtrace. +backwards no Display backtrace in anti-chronological order. +procnames yes Record procedure names at definition. +trace no *Trace mode. +breakpoints no *Check for breakpoints. +cheap yes *Flyweight representation of the stack at traps. +@end smallexample + + +@node Examples of option use +@section Examples of option use + +Here is an example of a session in which some read and debug option +handling procedures are used. In this example, the user + +@enumerate +@item +Notices that the symbols @code{abc} and @code{aBc} are not the same +@item +Examines the @code{read-options}, and sees that @code{case-insensitive} +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} +@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: +ERROR: Unbound variable: aBc +ABORT: (misc-error) + +Type "(backtrace)" to get more information. +guile> (read-options 'help) +keywords #f Style of keyword recognition: #f or 'prefix +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). +debug yes Use the debugging evaluator. +backtrace no Show backtrace on error. +depth 20 Maximal length of printed backtrace. +maxdepth 1000 Maximal number of stored backtrace frames. +frames 3 Maximum number of tail-recursive frames in backtrace. +indent 10 Maximal indentation in backtrace. +backwards no Display backtrace in anti-chronological order. +procnames yes Record procedure names at definition. +trace no *Trace mode. +breakpoints no *Check for breakpoints. +cheap yes *Flyweight representation of the stack at traps. +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 + + +@node Install Config +@section Installation and Configuration Data + +It is often useful to have site-specific information about the current +Guile installation. This chapter describes how to find out about +Guile's configuration at run time. + +@deffn primitive version +@deffnx primitive major-version +@deffnx primitive minor-version +@deffnx primitive micro-version +Return a string describing Guile's version number, or its major or minor +version numbers, respectively. + +@lisp +(version) @result{} "1.6.5" +(major-version) @result{} "1" +(minor-version) @result{} "6" +(micro-version) @result{} "5" +@end lisp +@end deffn + +@c NJFIXME not in libguile! +@deffn primitive libguile-config-stamp +Return a string describing the date on which @code{libguile} was +configured. This is used to determine whether the Guile core +interpreter and the ice-9 runtime have grown out of date with one +another. +@end deffn + +@deffn primitive %package-data-dir +Return the name of the directory where Scheme packages, modules and +libraries are kept. On most Unix systems, this will be +@samp{/usr/local/share/guile}. +@end deffn + +@deffn primitive %library-dir +Return the directory where the Guile Scheme library files are installed. +E.g., may return "/usr/share/guile/1.3.5". +@end deffn + +@deffn primitive %site-dir +Return the directory where the Guile site files are installed. +E.g., may return "/usr/share/guile/site". +@end deffn + +@deffn primitive parse-path path [tail] +Parse @var{path}, which is expected to be a colon-separated +string, into a list and return the resulting list with +@var{tail} appended. If @var{path} is @code{#f}, @var{tail} +is returned. +@end deffn + +@deffn primitive search-path path filename [extensions] +Search @var{path} for a directory containing a file named +@var{filename}. The file must be readable, and not a directory. +If we find one, return its full filename; otherwise, return +@code{#f}. If @var{filename} is absolute, return it unchanged. +If given, @var{extensions} is a list of strings; for each +directory in @var{path}, we search for @var{filename} +concatenated with each @var{extension}. +@end deffn + +@defvar %load-path +Return the list of directories which should be searched for Scheme +modules and libraries. +@end defvar + + +@c Local Variables: +@c TeX-master: "guile.texi" +@c End: |