diff options
Diffstat (limited to 'doc/scheme-options.texi')
-rw-r--r-- | doc/scheme-options.texi | 342 |
1 files changed, 0 insertions, 342 deletions
diff --git a/doc/scheme-options.texi b/doc/scheme-options.texi index 4e711764a..e69de29bb 100644 --- a/doc/scheme-options.texi +++ b/doc/scheme-options.texi @@ -1,342 +0,0 @@ -@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:: -* 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 - -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. -@end smallexample - - -@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: |