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 reading, printing, debugging or evaluating.

General option interface
========================

We will use the expression <group> to represent read, print, debug or evaluator.

Low level
---------

 -- primitive: <group>-options-interface
 -- primitive: read-options-interface [SOME-INT]
 -- primitive: print-options-interface [SOME-INT]
 -- primitive: evaluator-traps-interface [SOME-INT]
 -- 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.

User level
----------

 -- procedure: <group>-options [arg]
 -- procedure: read-options [arg]
 -- procedure: print-options [arg]
 -- procedure: debug-options [arg]
 -- procedure: traps [arg]
     These functions list the options in their group.  The optional argument ARG is a symbol which modifies the form in which the options are presented.

     With no arguments, <group>-options returns the values of the options in that particular group.  If ARG is 'help, a description of each option is given.  If ARG is 'full, programmers' options are also shown.

     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.

[FIXME: I don't think 'full is ever any different from 'help.  What's up?]

 -- procedure: <group>-enable option-symbol
 -- procedure: read-enable option-symbol
 -- procedure: print-enable option-symbol
 -- procedure: debug-enable option-symbol
 -- procedure: trap-enable option-symbol
     These functions set the specified OPTION-SYMBOL in their options group.  They only work if the option is boolean, and throw an error otherwise.

 -- procedure: <group>-disable option-symbol
 -- procedure: read-disable option-symbol
 -- procedure: print-disable option-symbol
 -- procedure: debug-disable option-symbol
 -- procedure: trap-disable option-symbol
     These functions turn off the specified OPTION-SYMBOL in their options group.  They only work if the option is boolean, and throw an error otherwise.

 -- syntax: <group>-set! option-symbol value
 -- syntax: read-set! option-symbol value
 -- syntax: print-set! option-symbol value
 -- syntax: debug-set! option-symbol value
 -- syntax: trap-set! option-symbol value
     These functions set a non-boolean OPTION-SYMBOL to the specified VALUE.

Reader options
==============

Here is the list of reader options generated by typing (read-options 'full) in Guile.  You can also see the default values.

     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.

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

     (read-enable 'case-insensitive)

Printing options
================

Here is the list of print options generated by typing (print-options 'full) in Guile.  You can also see the default values.

     source          no      Print closures with source.
     closure-hook    #f      Hook for printing closures.

Evaluator options
=================

These are the evaluator options with their default values, as they are printed by typing (eval-options 'full) in Guile.

     stack           22000   Size of thread stacks (in machine words).

Here is the list of evaluator trap options generated by typing (traps 'full) in Guile.  You can also see the default values.

     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.

Debugger options
================

Here is the list of print options generated by typing (debug-options 'full) in Guile.  You can also see the default values.

     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.

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

 1. Notices that the symbols abc and aBc are not the same

 2. Examines the read-options, and sees that case-insensitive is set to ``no''.

 3. Enables case-insensitive

 4. Verifies that now aBc and abc are the same

 5. Disables case-insensitive and enables debugging backtrace

 6. Reproduces the error of displaying 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.]

     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>

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.

 -- primitive: version
 -- primitive: major-version
 -- primitive: minor-version
     Return a string describing Guile's version number, or its major or minor version numbers, respectively.

          (version) => "1.3a"
          (major-version) => "1"
          (minor-version) => "3a"

 -- primitive: libguile-config-stamp
     Return a string describing the date on which 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.

 -- 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 /usr/local/share/guile.

 -- primitive: %library-dir
     Return the directory where the Guile Scheme library files are installed. E.g., may return "/usr/share/guile/1.3.5".

 -- primitive: %site-dir
     Return the directory where the Guile site files are installed. E.g., may return "/usr/share/guile/site".

 -- primitive: parse-path path [tail]
     Parse PATH, which is expected to be a colon-separated string, into a list and return the resulting list with TAIL appended. If PATH is #f, TAIL is returned.

 -- primitive: search-path path filename [extensions]
     Search PATH for a directory containing a file named FILENAME. The file must be readable, and not a directory. If we find one, return its full filename; otherwise, return #f.  If FILENAME is absolute, return it unchanged. If given, EXTENSIONS is a list of strings; for each directory in PATH, we search for FILENAME concatenated with each EXTENSION.

 -- Variable: %load-path
     Return the list of directories which should be searched for Scheme modules and libraries.