   Guile Reference Manual Copyright (C) 1996 Free Software Foundation
Copyright (C) 1997 Free Software Foundation
Copyright (C) 2000 Free Software Foundation
Copyright (C) 2001 Free Software Foundation
Copyright (C) 2002 Free Software Foundation

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Reporting Bugs
**************

   Any problems with the installation should be reported to
<bug-guile@gnu.org>.

   Whenever you have found a bug in Guile you are encouraged to report
it to the Guile developers, so they can fix it.  They may also be able
to suggest workarounds when it is not possible for you to apply the
bug-fix or install a new version of Guile yourself.

   Before sending in bug reports, please check with the following list
that you really have found a bug.

   * Whenever documentation and actual behavior differ, you have
     certainly found a bug, either in the documentation or in the
     program.

   * When Guile crashes, it is a bug.

   * When Guile hangs or takes forever to complete a task, it is a bug.

   * When calculations produce wrong results, it is a bug.

   * When Guile signals an error for valid Scheme programs, it is a bug.

   * When Guile does not signal an error for invalid Scheme programs,
     it may be a bug, unless this is explicitly documented.

   * When some part of the documentation is not clear and does not make
     sense to you even after re-reading the section, it is a bug.

   When you write a bug report, please make sure to include as much of
the information described below in the report.  If you can't figure out
some of the items, it is not a problem, but the more information we
get, the more likely we can diagnose and fix the bug.

   * The version number of Guile.  Without this, we won't know whether
     there is any point in looking for the bug in the current version
     of Guile.

     You can get the version number by invoking the command

          $ guile --version
          Guile 1.4.1
          Copyright (c) 1995, 1996, 1997, 2000 Free Software Foundation
          Guile may be distributed under the terms of the GNU General Public License;
          certain other uses are permitted as well.  For details, see the file
          `COPYING', which is included in the Guile distribution.
          There is no warranty, to the extent permitted by law.

   * The type of machine you are using, and the operating system name
     and version number.  On GNU systems, you can get it with `uname'.

          $ uname -a
          Linux tortoise 2.2.17 #1 Thu Dec 21 17:29:05 CET 2000 i586 unknown

   * The operands given to the `configure' command when Guile was
     installed.  It's often useful to augment this with the output of
     the command `guile-config info'.

   * A complete list of any modifications you have made to the Guile
     source.  (We may not have time to investigate the bug unless it
     happens in an unmodified Guile.  But if you've made modifications
     and you don't tell us, you are sending us on a wild goose chase.)

     Be precise about these changes.  A description in English is not
     enough--send a context diff for them.

     Adding files of your own, or porting to another machine, is a
     modification of the source.

   * Details of any other deviations from the standard procedure for
     installing Guile.

   * The complete text of any source files needed to reproduce the bug.

     If you can tell us a way to cause the problem without loading any
     source files, please do so.  This makes it much easier to debug.
     If you do need files, make sure you arrange for us to see their
     exact contents.

   * The precise Guile invocation command line we need to type to
     reproduce the bug.

   * A description of what behavior you observe that you believe is
     incorrect.  For example, "The Guile process gets a fatal signal,"
     or, "The resulting output is as follows, which I think is wrong."

     Of course, if the bug is that Guile gets a fatal signal, then one
     can't miss it.  But if the bug is incorrect results, the
     maintainer might fail to notice what is wrong.  Why leave it to
     chance?

     If the manifestation of the bug is a Guile error message, it is
     important to report the precise text of the error message, and a
     backtrace showing how the Scheme program arrived at the error.

     This can be done using the procedure `backtrace' in the REPL.

   * Check whether any programs you have loaded into Guile, including
     your `.guile' file, set any variables that may affect the
     functioning of Guile.  Also, see whether the problem happens in a
     freshly started Guile without loading your `.guile' file (start
     Guile with the `-q' switch to prevent loading the init file).  If
     the problem does _not_ occur then, you must report the precise
     contents of any programs that you must load into Guile in order to
     cause the problem to occur.

   * If the problem does depend on an init file or other Scheme
     programs that are not part of the standard Guile distribution,
     then you should make sure it is not a bug in those programs by
     complaining to their maintainers first.  After they verify that
     they are using Guile in a way that is supposed to work, they
     should report the bug.

   * If you wish to mention something in the Guile source, show the
     line of code with a few lines of context.  Don't just give a line
     number.

     The line numbers in the development sources might not match those
     in your sources.  It would take extra work for the maintainers to
     determine what code is in your version at a given line number, and
     we could not be certain.

   * Additional information from a C debugger such as GDB might enable
     someone to find a problem on a machine which he does not have
     available.  If you don't know how to use GDB, please read the GDB
     manual--it is not very long, and using GDB is easy.  You can find
     the GDB distribution, including the GDB manual in online form, in
     most of the same places you can find the Guile distribution.  To
     run Guile under GDB, you should switch to the `libguile'
     subdirectory in which Guile was compiled, then do `gdb guile' or
     `gdb .libs/guile' (if using GNU Libtool).

     However, you need to think when you collect the additional
     information if you want it to show what causes the bug.

     For example, many people send just a backtrace, but that is not
     very useful by itself.  A simple backtrace with arguments often
     conveys little about what is happening inside Guile, because most
     of the arguments listed in the backtrace are pointers to Scheme
     objects.  The numeric values of these pointers have no
     significance whatever; all that matters is the contents of the
     objects they point to (and most of the contents are themselves
     pointers).

Part II: Writing and Running Guile Scheme
*****************************************

   Guile's core language is Scheme, and an awful lot can be achieved
simply by using Guile to write and run Scheme programs.  In this part
of the manual, we explain how to use Guile in this mode, and describe
the tools that Guile provides to help you with script writing,
debugging and packaging your programs for distribution.

   For readers who are not yet familiar with the Scheme language, this
part includes a chapter that presents the basic concepts of the
language, and gives references to freely available Scheme tutorial
material on the web.

   For detailed reference information on the variables, functions etc.
that make up Guile's application programming interface (API), please
refer to Part IV (see Part IV -- Guile API Reference).

Guile's Implementation of Scheme
********************************

   Guile's core language is Scheme, which is specified and described in
the series of reports known as "RnRS".  "RnRS" is shorthand for the
"Revised^n Report on the Algorithmic Language Scheme".  The current
latest revision of RnRS is version 5 (see R5RS (r5rs)), and
Guile 1.4 is fully compliant with the Scheme specification in this
revision.

   But Guile, like most Scheme implementations, also goes beyond R5RS in
many ways, because R5RS does not give specifications (or even
recommendations) regarding many issues that are important in practical
programming.  Some of the areas where Guile extends R5RS are:

   * Guile's interactive documentation system

   * Guile's support for POSIX-compliant network programming

   * GOOPS - Guile's framework for object oriented programming.

Guile Scripting
***************

   Like AWK, Perl, or any shell, Guile can interpret script files.  A
Guile script is simply a file of Scheme code with some extra
information at the beginning which tells the operating system how to
invoke Guile, and then tells Guile how to handle the Scheme code.

Invoking Guile
==============

   Here we describe Guile's command-line processing in detail.  Guile
processes its arguments from left to right, recognizing the switches
described below.  For examples, see Scripting Examples.

`-s SCRIPT ARG...'
     Read and evaluate Scheme source code from the file SCRIPT, as the
     `load' function would.  After loading SCRIPT, exit.  Any
     command-line arguments ARG... following SCRIPT become the script's
     arguments; the `command-line' function returns a list of strings
     of the form `(SCRIPT ARG...)'.

`-c EXPR ARG...'
     Evaluate EXPR as Scheme code, and then exit.  Any command-line
     arguments ARG... following EXPR become command-line arguments; the
     `command-line' function returns a list of strings of the form
     `(GUILE ARG...)', where GUILE is the path of the Guile executable.

`-- ARG...'
     Run interactively, prompting the user for expressions and
     evaluating them.  Any command-line arguments ARG... following the
     `--' become command-line arguments for the interactive session; the
     `command-line' function returns a list of strings of the form
     `(GUILE ARG...)', where GUILE is the path of the Guile executable.

`-l FILE'
     Load Scheme source code from FILE, and continue processing the
     command line.

`-e FUNCTION'
     Make FUNCTION the "entry point" of the script.  After loading the
     script file (with `-s') or evaluating the expression (with `-c'),
     apply FUNCTION to a list containing the program name and the
     command-line arguments -- the list provided by the `command-line'
     function.

     A `-e' switch can appear anywhere in the argument list, but Guile
     always invokes the FUNCTION as the _last_ action it performs.
     This is weird, but because of the way script invocation works under
     POSIX, the `-s' option must always come last in the list.

     See Scripting Examples.

`-ds'
     Treat a final `-s' option as if it occurred at this point in the
     command line; load the script here.

     This switch is necessary because, although the POSIX script
     invocation mechanism effectively requires the `-s' option to
     appear last, the programmer may well want to run the script before
     other actions requested on the command line.  For examples, see
     Scripting Examples.

`\'
     Read more command-line arguments, starting from the second line of
     the script file.  See The Meta Switch.

`--emacs'
     Assume Guile is running as an inferior process of Emacs, and use a
     special protocol to communicate with Emacs's Guile interaction
     mode.  This switch sets the global variable use-emacs-interface to
     `#t'.

     This switch is still experimental.

`--use-srfi=LIST'
     The option `--use-srfi' expects a comma-separated list of numbers,
     each representing a SRFI number to be loaded into the interpreter
     before starting evaluating a script file or the REPL.
     Additionally, the feature identifier for the loaded SRFIs is
     recognized by `cond-expand' when using this option.

          guile --use-srfi=8,13

`--debug'
     Start with the debugging evaluator and enable backtraces.  Using
     the debugging evaluator will give you better error messages but it
     will slow down execution.  By default, the debugging evaluator is
     only used when entering an interactive session.  When executing a
     script with `-s' or `-c', the normal, faster evaluator is used by
     default.

`-h, --help'
     Display help on invoking Guile, and then exit.

`-v, --version'
     Display the current version of Guile, and then exit.

The Meta Switch
===============

   Guile's command-line switches allow the programmer to describe
reasonably complicated actions in scripts.  Unfortunately, the POSIX
script invocation mechanism only allows one argument to appear on the
`#!' line after the path to the Guile executable, and imposes arbitrary
limits on that argument's length.  Suppose you wrote a script starting
like this:
     #!/usr/local/bin/guile -e main -s
     !#
     (define (main args)
       (map (lambda (arg) (display arg) (display " "))
            (cdr args))
       (newline))
   The intended meaning is clear: load the file, and then call `main'
on the command-line arguments.  However, the system will treat
everything after the Guile path as a single argument -- the string `"-e
main -s"' -- which is not what we want.

   As a workaround, the meta switch `\' allows the Guile programmer to
specify an arbitrary number of options without patching the kernel.  If
the first argument to Guile is `\', Guile will open the script file
whose name follows the `\', parse arguments starting from the file's
second line (according to rules described below), and substitute them
for the `\' switch.

   Working in concert with the meta switch, Guile treats the characters
`#!' as the beginning of a comment which extends through the next line
containing only the characters `!#'.  This sort of comment may appear
anywhere in a Guile program, but it is most useful at the top of a
file, meshing magically with the POSIX script invocation mechanism.

   Thus, consider a script named `/u/jimb/ekko' which starts like this:
     #!/usr/local/bin/guile \
     -e main -s
     !#
     (define (main args)
             (map (lambda (arg) (display arg) (display " "))
                  (cdr args))
             (newline))

   Suppose a user invokes this script as follows:
     $ /u/jimb/ekko a b c

   Here's what happens:
   * the operating system recognizes the `#!' token at the top of the
     file, and rewrites the command line to:
          /usr/local/bin/guile \ /u/jimb/ekko a b c
     This is the usual behavior, prescribed by POSIX.

   * When Guile sees the first two arguments, `\ /u/jimb/ekko', it opens
     `/u/jimb/ekko', parses the three arguments `-e', `main', and `-s'
     from it, and substitutes them for the `\' switch.  Thus, Guile's
     command line now reads:
          /usr/local/bin/guile -e main -s /u/jimb/ekko a b c

   * Guile then processes these switches: it loads `/u/jimb/ekko' as a
     file of Scheme code (treating the first three lines as a comment),
     and then performs the application `(main "/u/jimb/ekko" "a" "b"
     "c")'.

   When Guile sees the meta switch `\', it parses command-line argument
from the script file according to the following rules:
   * Each space character terminates an argument.  This means that two
     spaces in a row introduce an argument `""'.

   * The tab character is not permitted (unless you quote it with the
     backslash character, as described below), to avoid confusion.

   * The newline character terminates the sequence of arguments, and
     will also terminate a final non-empty argument.  (However, a
     newline following a space will not introduce a final empty-string
     argument; it only terminates the argument list.)

   * The backslash character is the escape character.  It escapes
     backslash, space, tab, and newline.  The ANSI C escape sequences
     like `\n' and `\t' are also supported.  These produce argument
     constituents; the two-character combination `\n' doesn't act like
     a terminating newline.  The escape sequence `\NNN' for exactly
     three octal digits reads as the character whose ASCII code is NNN.
     As above, characters produced this way are argument constituents.
     Backslash followed by other characters is not allowed.

Handling Command Line Options and Arguments
*******************************************

   The ability to accept and handle command line arguments is very
important when writing Guile scripts to solve particular problems, such
as extracting information from text files or interfacing with existing
command line applications.  This chapter describes how Guile makes
command line arguments available to a Guile script, and the utilities
that Guile provides to help with the processing of command line
arguments.

Using Command Line Arguments
============================

   When a Guile script is invoked, Guile makes the command line
arguments accessible via the procedure `command-line', which returns the
arguments as a list of strings.

   For example, if the script

     #! /usr/local/bin/guile -s
     !#
     (write (command-line))
     (newline)

is saved in a file `cmdline-test.scm' and invoked using the command
line `./cmdline-test.scm bar.txt -o foo -frumple grob', the output is

     ("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob")

   If the script invocation includes a `-e' option, specifying a
procedure to call after loading the script, Guile will call that
procedure with `(command-line)' as its argument.  So a script that uses
`-e' doesn't need to refer explicitly to `command-line' in its code.
For example, the script above would have identical behaviour if it was
written instead like this:

     #! /usr/local/bin/guile \
     -e main -s
     !#
     (define (main args)
       (write args)
       (newline))

   (Note the use of the meta switch `\' so that the script invocation
can include more than one Guile option: The Meta Switch.)

   These scripts use the `#!' POSIX convention so that they can be
executed using their own file names directly, as in the example command
line `./cmdline-test.scm bar.txt -o foo -frumple grob'.  But they can
also be executed by typing out the implied Guile command line in full,
as in:

     $ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob

or

     $ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob

   Even when a script is invoked using this longer form, the arguments
that the script receives are the same as if it had been invoked using
the short form.  Guile ensures that the `(command-line)' or `-e'
arguments are independent of how the script is invoked, by stripping off
the arguments that Guile itself processes.

The (ice-9 getopt-long) Module
==============================

   A script is free to parse and handle its command line arguments in
any way that it chooses.  Where the set of possible options and
arguments is complex, however, it can get tricky to extract all the
options, check the validity of given arguments, and so on.  This task
can be greatly simplified by taking advantage of the module `(ice-9
getopt-long)', which is distributed with Guile.

   The `(ice-9 getopt-long)' module exports two procedures:
`getopt-long' and `option-ref'.

   * `getopt-long' takes a list of strings -- the command line
     arguments -- and an "option specification".  It parses the command
     line arguments according to the option specification and returns a
     data structure that encapsulates the results of the parsing.

   * `option-ref' then takes the parsed data structure and a specific
     option's name, and returns information about that option in
     particular.

   To make these procedures available to your Guile script, include the
expression `(use-modules (ice-9 getopt-long))' somewhere near the top,
before the first usage of `getopt-long' or `option-ref'.

A Short getopt-long Example
---------------------------

   This subsection illustrates how `getopt-long' is used by presenting
and dissecting a simple example.  The first thing that we need is an
"option specification" that tells `getopt-long' how to parse the
command line.  This specification is an association list with the long
option name as the key.  Here is how such a specification might look:

     (define option-spec
       '((version (single-char #\v) (value #f))
         (help    (single-char #\h) (value #f))))

   This alist tells `getopt-long' that it should accept two long
options, called _version_ and _help_, and that these options can also
be selected by the single-letter abbreviations _v_ and _h_,
respectively.  The `(value #f)' clauses indicate that neither of the
options accepts a value.

   With this specification we can use `getopt-long' to parse a given
command line:

     (define options (getopt-long (command-line) option-spec))

   After this call, `options' contains the parsed command line and is
ready to be examined by `option-ref'.  `option-ref' is called like this:

     (option-ref options 'help #f)

It expects the parsed command line, a symbol indicating the option to
examine, and a default value.  The default value is returned if the
option was not present in the command line, or if the option was present
but without a value; otherwise the value from the command line is
returned.  Usually `option-ref' is called once for each possible option
that a script supports.

   The following example shows a main program which puts all this
together to parse its command line and figure out what the user wanted.

     (define (main args)
       (let* ((option-spec '((version (single-char #\v) (value #f))
                             (help    (single-char #\h) (value #f))))
              (options (getopt-long args option-spec))
              (help-wanted (option-ref options 'help #f))
              (version-wanted (option-ref options 'version #f)))
         (if (or version-wanted help-wanted)
             (begin
               (if version-wanted
                   (display "getopt-long-example version 0.3\n"))
               (if help-wanted
                   (display "\
     getopt-long-example [options]
       -v, --version    Display version
       -h, --help       Display this help
     ")))
             (begin
               (display "Hello, World!") (newline)))))

How to Write an Option Specification
------------------------------------

   An option specification is an association list (see Association Lists)
with one list element for each supported option. The key of
each list element is a symbol that names the option, while the value is
a list of option properties:

     OPTION-SPEC ::=  '( (OPT-NAME1 (PROP-NAME PROP-VALUE) ...)
                         (OPT-NAME2 (PROP-NAME PROP-VALUE) ...)
                         (OPT-NAME3 (PROP-NAME PROP-VALUE) ...)
                         ...
                       )

   Each OPT-NAME specifies the long option name for that option.  For
example, a list element with OPT-NAME `background' specifies an option
that can be specified on the command line using the long option
`--background'.  Further information about the option -- whether it
takes a value, whether it is required to be present in the command
line, and so on -- is specified by the option properties.

   In the example of the preceding subsection, we already saw that a
long option name can have a equivalent "short option" character.  The
equivalent short option character can be set for an option by specifying
a `single-char' property in that option's property list.  For example,
a list element like `'(output (single-char #\o) ...)' specifies an
option with long name `--output' that can also be specified by the
equivalent short name `-o'.

   The `value' property specifies whether an option requires or accepts
a value.  If the `value' property is set to `#t', the option requires a
value: `getopt-long' will signal an error if the option name is present
without a corresponding value.  If set to `#f', the option does not
take a value; in this case, a non-option word that follows the option
name in the command line will be treated as a non-option argument.  If
set to the symbol `optional', the option accepts a value but does not
require one: a non-option word that follows the option name in the
command line will be interpreted as that option's value.  If the option
name for an option with `'(value optional)' is immediately followed in
the command line by _another_ option name, the value for the first
option is implicitly `#t'.

   The `required?' property indicates whether an option is required to
be present in the command line.  If the `required?'  property is set to
`#t', `getopt-long' will signal an error if the option is not specified.

   Finally, the `predicate' property can be used to constrain the
possible values of an option.  If used, the `predicate' property should
be set to a procedure that takes one argument -- the proposed option
value as a string -- and returns either `#t' or `#f' according as the
proposed value is or is not acceptable.  If the predicate procedure
returns `#f', `getopt-long' will signal an error.

   By default, options do not have single-character equivalents, are not
required, and do not take values.  Where the list element for an option
includes a `value' property but no `predicate' property, the option
values are unconstrained.

Expected Command Line Format
----------------------------

   In order for `getopt-long' to correctly parse a command line, that
command line must conform to a standard set of rules for how command
line options are specified.  This subsection explains what those rules
are.

   `getopt-long' splits a given command line into several pieces.  All
elements of the argument list are classified to be either options or
normal arguments.  Options consist of two dashes and an option name
(so-called "long" options), or of one dash followed by a single letter
("short" options).

   Options can behave as switches, when they are given without a value,
or they can be used to pass a value to the program.  The value for an
option may be specified using an equals sign, or else is simply the next
word in the command line, so the following two invocations are
equivalent:

     $ ./foo.scm --output=bar.txt
     $ ./foo.scm --output bar.txt

   Short options can be used instead of their long equivalents and can
be grouped together after a single dash.  For example, the following
commands are equivalent.

     $ ./foo.scm --version --help
     $ ./foo.scm -v --help
     $ ./foo.scm -vh

   If an option requires a value, it can only be grouped together with
other short options if it is the last option in the group; the value is
the next argument.  So, for example, with the following option
specification --

     ((apples    (single-char #\a))
      (blimps    (single-char #\b) (value #t))
      (catalexis (single-char #\c) (value #t)))

-- the following command lines would all be acceptable:

     $ ./foo.scm -a -b bang -c couth
     $ ./foo.scm -ab bang -c couth
     $ ./foo.scm -ac couth -b bang

   But the next command line is an error, because `-b' is not the last
option in its combination, and because a group of short options cannot
include two options that both require values:

     $ ./foo.scm -abc couth bang

   If an option's value is optional, `getopt-long' decides whether the
option has a value by looking at what follows it in the argument list.
If the next element is a string, and it does not appear to be an option
itself, then that string is the option's value.

   If the option `--' appears in the argument list, argument parsing
stops there and subsequent arguments are returned as ordinary arguments,
even if they resemble options.  So, with the command line

     $ ./foo.scm --apples "Granny Smith" -- --blimp Goodyear

`getopt-long' will recognize the `--apples' option as having the value
"Granny Smith", but will not treat `--blimp' as an option.  The strings
`--blimp' and `Goodyear' will be returned as ordinary argument strings.

Reference Documentation for `getopt-long'
-----------------------------------------

 - Scheme Procedure: getopt-long args grammar
     Parse the command line given in ARGS (which must be a list of
     strings) according to the option specification GRAMMAR.

     The GRAMMAR argument is expected to be a list of this form:

     `((OPTION (PROPERTY VALUE) ...) ...)'

     where each OPTION is a symbol denoting the long option, but
     without the two leading dashes (e.g. `version' if the option is
     called `--version').

     For each option, there may be list of arbitrarily many
     property/value pairs.  The order of the pairs is not important,
     but every property may only appear once in the property list.  The
     following table lists the possible properties:

    `(single-char CHAR)'
          Accept `-CHAR' as a single-character equivalent to
          `--OPTION'.  This is how to specify traditional Unix-style
          flags.

    `(required? BOOL)'
          If BOOL is true, the option is required.  `getopt-long' will
          raise an error if it is not found in ARGS.

    `(value BOOL)'
          If BOOL is `#t', the option accepts a value; if it is `#f',
          it does not; and if it is the symbol `optional', the option
          may appear in ARGS with or without a value.

    `(predicate FUNC)'
          If the option accepts a value (i.e. you specified `(value
          #t)' for this option), then `getopt-long' will apply FUNC to
          the value, and throw an exception if it returns `#f'.  FUNC
          should be a procedure which accepts a string and returns a
          boolean value; you may need to use quasiquotes to get it into
          GRAMMAR.

   `getopt-long''s ARGS parameter is expected to be a list of strings
like the one returned by `command-line', with the first element being
the name of the command.  Therefore `getopt-long' ignores the first
element in ARGS and starts argument interpretation with the second
element.

   `getopt-long' signals an error if any of the following conditions
hold.

   * The option grammar has an invalid syntax.

   * One of the options in the argument list was not specified by the
     grammar.

   * A required option is omitted.

   * An option which requires an argument did not get one.

   * An option that doesn't accept an argument does get one (this can
     only happen using the long option `--opt=VALUE' syntax).

   * An option predicate fails.

Reference Documentation for `option-ref'
----------------------------------------

 - Scheme Procedure: option-ref options key default
     Search OPTIONS for a command line option named KEY and return its
     value, if found.  If the option has no value, but was given,
     return `#t'.  If the option was not given, return DEFAULT.
     OPTIONS must be the result of a call to `getopt-long'.

   `option-ref' always succeeds, either by returning the requested
option value from the command line, or the default value.

   The special key `'()' can be used to get a list of all non-option
arguments.

Debugging Features
******************

   When debugging a program, programmers often find it helpful to
examine the program's internal status while it runs: the values of
internal variables, the choices made in `if' and `cond' statements, and
so forth.  Guile Scheme provides a debugging interface that programmers
can use to single-step through Scheme functions and examine symbol
bindings.  This is different from the Debugging, which permits
programmers to debug the Guile interpreter itself.  Most programmers
will be more interested in debugging their own Scheme programs than the
interpreter which evaluates them.

   [FIXME: should we include examples of traditional debuggers and
explain why they can't be used to debug interpreted Scheme or Lisp?]

Single-Step
===========

Trace
=====

   When a function is "traced", it means that every call to that
function is reported to the user during a program run.  This can help a
programmer determine whether a function is being called at the wrong
time or with the wrong set of arguments.

 - Function: trace function
     Enable debug tracing on `function'.  While a program is being run,
     Guile will print a brief report at each call to a traced function,
     advising the user which function was called and the arguments that
     were passed to it.

 - Function: untrace function
     Disable debug tracing for `function'.

   Example:

     (define (rev ls)
       (if (null? ls)
           '()
           (append (rev (cdr ls))
                   (cons (car ls) '())))) => rev

     (trace rev) => (rev)

     (rev '(a b c d e))
     => [rev (a b c d e)]
        |  [rev (b c d e)]
        |  |  [rev (c d e)]
        |  |  |  [rev (d e)]
        |  |  |  |  [rev (e)]
        |  |  |  |  |  [rev ()]
        |  |  |  |  |  ()
        |  |  |  |  (e)
        |  |  |  (e d)
        |  |  (e d c)
        |  (e d c b)
        (e d c b a)
        (e d c b a)

   Note the way Guile indents the output, illustrating the depth of
execution at each function call.  This can be used to demonstrate, for
example, that Guile implements self-tail-recursion properly:

     (define (rev ls sl)
       (if (null? ls)
           sl
           (rev (cdr ls)
                (cons (car ls) sl)))) => rev

     (trace rev) => (rev)

     (rev '(a b c d e) '())
     => [rev (a b c d e) ()]
        [rev (b c d e) (a)]
        [rev (c d e) (b a)]
        [rev (d e) (c b a)]
        [rev (e) (d c b a)]
        [rev () (e d c b a)]
        (e d c b a)
        (e d c b a)

   Since the tail call is effectively optimized to a `goto' statement,
there is no need for Guile to create a new stack frame for each
iteration.  Using `trace' here helps us see why this is so.

Backtrace
=========

 - Scheme Procedure: backtrace
 - C Function: scm_backtrace ()
     Display a backtrace of the stack saved by the last error to the
     current output port.

Autoconf Support
****************

   When Guile is installed, a set of autoconf macros is also installed
as PREFIX/share/aclocal/guile.m4.  This chapter documents the macros
provided in that file, as well as the high-level guile-tool Autofrisk.
See The GNU Autoconf Manual (autoconf), for more info.

Autoconf Background
===================

   As explained elsewhere (see The GNU Autoconf Manual (autoconf)),
any package needs configuration at build-time.  If
your package uses Guile (or uses a package that in turn uses Guile),
you probably need to know what specific Guile features are available
and details about them.

   The way to do this is to write feature tests and arrange for their
execution by the `configure' script, typically by adding the tests to
`configure.ac', and running `autoconf' to create `configure'.  Users of
your package then run `configure' in the normal way.

   Macros are a way to make common feature tests easy to express.
Autoconf provides a wide range of macros (see Existing Tests (autoconf)),
and Guile installation provides
Guile-specific tests in the areas of: program detection, compilation
flags reporting, and Scheme module checks.

Autoconf Macros
===============

   The macro names all begin with "GUILE_".

 - Autoconf Macro: GUILE_PROGS
     This macro looks for programs `guile', `guile-config' and
     `guile-tools', and sets variables GUILE, GUILE_CONFIG and
     GUILE_TOOLS, to their paths, respectively.  If either of the first
     two is not found, signal error.

     The variables are marked for substitution, as by `AC_SUBST'.

 - Autoconf Macro: GUILE_FLAGS
     This macro runs the `guile-config' script, installed with Guile, to
     find out where Guile's header files and libraries are installed.
     It sets two variables, GUILE_CFLAGS and GUILE_LDFLAGS.

     GUILE_CFLAGS: flags to pass to a C or C++ compiler to build code
     that uses Guile header files.  This is almost always just a `-I'
     flag.

     GUILE_LDFLAGS: flags to pass to the linker to link a program
     against Guile.  This includes `-lguile' for the Guile library
     itself, any libraries that Guile itself requires (like
     -lqthreads), and so on.  It may also include a `-L' flag to tell
     the compiler where to find the libraries.

     The variables are marked for substitution, as by `AC_SUBST'.

 - Autoconf Macro: GUILE_SITE_DIR
     This looks for Guile's "site" directory, usually something like
     PREFIX/share/guile/site, and sets var GUILE_SITE to the path.
     Note that the var name is different from the macro name.

     The variable is marked for substitution, as by `AC_SUBST'.

 - Autoconf Macro: GUILE_CHECK_RETVAL var check
     VAR is a shell variable name to be set to the return value.  CHECK
     is a Guile Scheme expression, evaluated with "$GUILE -c", and
     returning either 0 or non-#f to indicate the check passed.
     Non-0 number or #f indicates failure.     Avoid using the
     character "#" since that confuses autoconf.

 - Autoconf Macro: GUILE_MODULE_CHECK var module featuretest description
     VAR is a shell variable name to be set to "yes" or "no".  MODULE
     is a list of symbols, like: (ice-9 common-list).  FEATURETEST is
     an expression acceptable to GUILE_CHECK, q.v.  DESCRIPTION is a
     present-tense verb phrase (passed to AC_MSG_CHECKING).

 - Autoconf Macro: GUILE_MODULE_AVAILABLE var module
     VAR is a shell variable name to be set to "yes" or "no".  MODULE
     is a list of symbols, like: (ice-9 common-list).

 - Autoconf Macro: GUILE_MODULE_REQUIRED symlist
     SYMLIST is a list of symbols, WITHOUT surrounding parens, like:
     ice-9 common-list.

 - Autoconf Macro: GUILE_MODULE_EXPORTS var module modvar
     VAR is a shell variable to be set to "yes" or "no".  MODULE is a
     list of symbols, like: (ice-9 common-list).  MODVAR is the Guile
     Scheme variable to check.

 - Autoconf Macro: GUILE_MODULE_REQUIRED_EXPORT module modvar
     MODULE is a list of symbols, like: (ice-9 common-list).  MODVAR is
     the Guile Scheme variable to check.

Using Autoconf Macros
=====================

   Using the autoconf macros is straightforward: Add the macro "calls"
(actually instantiations) to `configure.ac', run `aclocal', and finally,
run `autoconf'.  If your system doesn't have guile.m4 installed, place
the desired macro definitions (`AC_DEFUN' forms) in `acinclude.m4', and
`aclocal' will do the right thing.

   Some of the macros can be used inside normal shell constructs: `if
foo ; then GUILE_BAZ ; fi', but this is not guaranteed.  It's probably
a good idea to instantiate macros at top-level.

   We now include two examples, one simple and one complicated.

   The first example is for a package that uses libguile, and thus
needs to know how to compile and link against it.  So we use
`GUILE_FLAGS' to set the vars `GUILE_CFLAGS' and `GUILE_LDFLAGS', which
are automatically substituted in the Makefile.

     In configure.ac:

       GUILE_FLAGS

     In Makefile.in:

       GUILE_CFLAGS  = @GUILE_CFLAGS@
       GUILE_LDFLAGS = @GUILE_LDFLAGS@

       myprog.o: myprog.c
               $(CC) -o $ $(GUILE_CFLAGS) $<
       myprog: myprog.o
               $(CC) -o $ $< $(GUILE_LDFLAGS)

   The second example is for a package of Guile Scheme modules that
uses an external program and other Guile Scheme modules (some might
call this a "pure scheme" package).  So we use the `GUILE_SITE_DIR'
macro, a regular `AC_PATH_PROG' macro, and the `GUILE_MODULE_AVAILABLE'
macro.

     In configure.ac:

       GUILE_SITE_DIR

       probably_wont_work=""

       # pgtype pgtable
       GUILE_MODULE_AVAILABLE(have_guile_pg, (database postgres))
       test $have_guile_pg = no &&
           probably_wont_work="(my pgtype) (my pgtable) $probably_wont_work"

       # gpgutils
       AC_PATH_PROG(GNUPG,gpg)
       test x"$GNUPG" = x &&
           probably_wont_work="(my gpgutils) $probably_wont_work"

       if test ! "$probably_wont_work" = "" ; then
           p="         ***"
           echo
           echo "$p"
           echo "$p NOTE:"
           echo "$p The following modules probably won't work:"
           echo "$p   $probably_wont_work"
           echo "$p They can be installed anyway, and will work if their"
           echo "$p dependencies are installed later.  Please see README."
           echo "$p"
           echo
       fi

     In Makefile.in:

       instdir = @GUILE_SITE@/my

       install:
             $(INSTALL) my/*.scm $(instdir)

Autofrisk
=========

   The "guile-tools autofrisk" command looks for the file `modules.af'
in the current directory and writes out `modules.af.m4' containing
autoconf definitions for `AUTOFRISK_CHECKS' and `AUTOFRISK_SUMMARY'.
See Autoconf Background, and Using Autoconf Macros, for
more info.

   The modules.af file consists of a series of configuration forms
(Scheme lists), which have one of the following formats:

       (files-glob PATTERN ...)                      ;; required
       (non-critical-external MODULE ...)            ;; optional
       (non-critical-internal MODULE ...)            ;; optional
       (programs (MODULE PROG ...) ...)              ;; optional
       (pww-varname VARNAME)                         ;; optional

   PATTERN is a string that may contain "*" and "?" characters to be
expanded into filenames.  MODULE is a list of symbols naming a module,
such as `(srfi srfi-1)'.  VARNAME is a shell-safe name to use instead of
`probably_wont_work', the default.  This var is passed to `AC_SUBST'.
PROG is a string that names a program, such as "gpg".

   Autofrisk expands the `files-glob' pattern(s) into a list of files,
scans each file's module definition form(s), and constructs a module
dependency graph wherein modules defined by `define-module' are
considered "internal" and the remaining, "external".  For each external
module that has an internal dependency, Autofrisk emits a
`GUILE_MODULE_REQUIRED' check (see Autoconf Macros), which
altogether form the body of `AUTOFRISK_CHECKS'.

   `GUILE_MODULE_REQUIRED' causes the `configure' script to exit with
an error message if the specified module is not available; it enforces a
strong dependency.  You can temper dependency strength by using the
`non-critical-external' and `non-critical-internal' configuration forms
in modules.af.  For graph edges that touch such non-critical modules,
Autofrisk uses `GUILE_MODULE_AVAILABLE', and arranges for
`AUTOFRISK_SUMMARY' to display a warning if they are not found.

   The shell code resulting from the expansion of `AUTOFRISK_CHECKS' and
`AUTOFRISK_SUMMARY' uses the shell variable `probably_wont_work' to
collect the names of unfound non-critical modules.  If this bothers
you, use configuration form `(pww-name foo)' in modules.af.

   Although Autofrisk does not detect when a module uses a program (for
example, in a `system' call), it can generate `AC_PATH_PROG' forms
anyway if you use the `programs' configuration form in modules.af.
These are collected into `AUTOCONF_CHECKS'.

   See Using Autofrisk, for some modules.af examples.

Using Autofrisk
===============

   Using Autofrisk (see Autofrisk) involves writing `modules.af' and
adding two macro calls to `configure.in'.  Here is an example of the
latter:

     AUTOFRISK_CHECKS
     AUTOFRISK_SUMMARY

   Here is an adaptation of the second "GUILE_*" example (see Using Autoconf Macros)
that does basically the same thing.

     (files-glob "my/*.scm")
     (non-critical-external (database postgres))
     (programs ((my gpgutils) "gpg"))        ;; (my gpgutils) uses "gpg"

   If the SRFI modules (see SRFI Support) were a separate package,
we could use `guile-tools frisk' to find out its dependencies:

     $ guile-tools frisk srfi/*.scm
     13 files, 18 modules (13 internal, 5 external), 9 edges

     x (ice-9 and-let-star)
     			 regular	(srfi srfi-2)
     x (ice-9 syncase)
     			 regular	(srfi srfi-11)
     x (ice-9 rdelim)
     			 regular	(srfi srfi-10)
     x (ice-9 receive)
     			 regular	(srfi srfi-8)
     			 regular	(srfi srfi-1)
     x (ice-9 session)
     			 regular	(srfi srfi-1)

   Then, we could use the following modules.af to help configure it:

     (files-glob "srfi/*.scm")
     (non-critical-external          ;; relatively recent
       (ice-9 rdelim)
       (ice-9 receive)
       (ice-9 and-let-star))
     (pww-varname not_fully_supported)

Miscellaneous Tools
*******************

   Programming is more fun with a good tools.  This chapter describes
snarfing tools, and the `guile-tools' program which can be used to
invoke the rest of the tools (which are self-documenting).  Some of
these are used in Guile development, too.  Imagine that!

Snarfing
========

   Because it's easier to maintain documentation, code, and other
metainfo in one source file than in many files, there have evolved many
methods for grepping source to lift and separate these kinds of info,
in the process generating docs or fragments of source or what have you.
This is known generally as "snarfing", which comes from the verb "to
snarf", here meaning "to unceremoniously extract information from a
somewhat unwilling source."

   This section documents the installed program `guile-snarf' which does
"init snarfing", and also touches upon guile's doc snarfing process
which is not yet finalized (i.e., doc snarfing programs are not
installed at this time).