This is guile.info, produced by makeinfo version 4.3 from guile.texi. INFO-DIR-SECTION The Algorithmic Language Scheme START-INFO-DIR-ENTRY * Guile Reference: (guile). The Guile reference manual. END-INFO-DIR-ENTRY 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.  File: guile.info, Node: Reporting Bugs, Next: Running Intro, Prev: Obtaining and Installing Guile, Up: Top Reporting Bugs ************** Any problems with the installation should be reported to . 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).  File: guile.info, Node: Running Intro, Next: Guile Scheme, Prev: Reporting Bugs, Up: Top 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 (*note Part IV -- Guile API Reference: Reference Intro.).  File: guile.info, Node: Guile Scheme, Next: Guile Scripting, Prev: Running Intro, Up: Top 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 (*note R5RS: (r5rs)Top.), 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.  File: guile.info, Node: Guile Scripting, Next: Command Line Handling, Prev: Guile Scheme, Up: Top 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. * Menu: * Invoking Guile:: How to start a Guile script. * The Meta Switch:: Passing complex argument lists to Guile from shell scripts.  File: guile.info, Node: Invoking Guile, Next: The Meta Switch, Up: Guile Scripting 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 *Note 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. *Note 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 *Note Scripting Examples::. `\' Read more command-line arguments, starting from the second line of the script file. *Note 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.  File: guile.info, Node: The Meta Switch, Prev: Invoking Guile, Up: Guile Scripting 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.  File: guile.info, Node: Command Line Handling, Next: Debugging Features, Prev: Guile Scripting, Up: Top 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. * Menu: * Command Line Args:: Using command line arguments. * getopt-long:: The (ice-9 getopt-long) module.  File: guile.info, Node: Command Line Args, Next: getopt-long, Up: Command Line Handling 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: *Note 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.  File: guile.info, Node: getopt-long, Prev: Command Line Args, Up: Command Line Handling 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'. * Menu: * getopt-long Example:: A short getopt-long example. * Option Specification:: How to write an option specification. * Command Line Format:: The expected command line format. * getopt-long Reference:: Full documentation for `getopt-long'. * option-ref Reference:: Full documentation for `option-ref'.  File: guile.info, Node: getopt-long Example, Next: Option Specification, Up: getopt-long 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)))))  File: guile.info, Node: Option Specification, Next: Command Line Format, Prev: getopt-long Example, Up: getopt-long How to Write an Option Specification ------------------------------------ An option specification is an association list (*note 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.  File: guile.info, Node: Command Line Format, Next: getopt-long Reference, Prev: Option Specification, Up: getopt-long 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.  File: guile.info, Node: getopt-long Reference, Next: option-ref Reference, Prev: Command Line Format, Up: getopt-long 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.  File: guile.info, Node: option-ref Reference, Prev: getopt-long Reference, Up: getopt-long 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.  File: guile.info, Node: Debugging Features, Next: Autoconf Support, Prev: Command Line Handling, Up: Top 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 *Note 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?] * Menu: * Single-Step:: Execute a program or function one step at a time. * Trace:: Print a report each time a given function is called. * Backtrace:: See a list of the statements that caused an error.  File: guile.info, Node: Single-Step, Next: Trace, Up: Debugging Features Single-Step ===========  File: guile.info, Node: Trace, Next: Backtrace, Prev: Single-Step, Up: Debugging Features 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.  File: guile.info, Node: Backtrace, Prev: Trace, Up: Debugging Features Backtrace ========= - Scheme Procedure: backtrace - C Function: scm_backtrace () Display a backtrace of the stack saved by the last error to the current output port.  File: guile.info, Node: Autoconf Support, Next: Miscellaneous Tools, Prev: Debugging Features, Up: Top 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. *Note The GNU Autoconf Manual: (autoconf)Top, for more info. * Menu: * Autoconf Background:: Why use autoconf? * Autoconf Macros:: The GUILE_* macros. * Using Autoconf Macros:: How to use them, plus examples. * Autofrisk:: AUTOFRISK_CHECKS and AUTOFRISK_SUMMARY. * Using Autofrisk:: Example modules.af files.  File: guile.info, Node: Autoconf Background, Next: Autoconf Macros, Up: Autoconf Support Autoconf Background =================== As explained elsewhere (*note The GNU Autoconf Manual: (autoconf)Top.), 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 (*note Existing Tests: (autoconf)Existing Tests.), and Guile installation provides Guile-specific tests in the areas of: program detection, compilation flags reporting, and Scheme module checks.  File: guile.info, Node: Autoconf Macros, Next: Using Autoconf Macros, Prev: Autoconf Background, Up: Autoconf Support 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.  File: guile.info, Node: Using Autoconf Macros, Next: Autofrisk, Prev: Autoconf Macros, Up: Autoconf Support 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)  File: guile.info, Node: Autofrisk, Next: Using Autofrisk, Prev: Using Autoconf Macros, Up: Autoconf Support 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'. *Note Autoconf Background::, and *Note 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 (*note 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'. *Note Using Autofrisk::, for some modules.af examples.  File: guile.info, Node: Using Autofrisk, Prev: Autofrisk, Up: Autoconf Support Using Autofrisk =============== Using Autofrisk (*note 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 (*note 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 (*note 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)  File: guile.info, Node: Miscellaneous Tools, Next: Basic Ideas, Prev: Autoconf Support, Up: Top 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! * Menu: * Snarfing:: Grepping the source in various ways. * Executable Modules:: Modules callable via guile-tools.  File: guile.info, Node: Snarfing, Next: Executable Modules, Up: Miscellaneous Tools 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). * Menu: * Init Snarfing with guile-snarf:: Exposing C subrs and friends to Scheme. * Doc Snarfing:: Generating GDFv2 or texi from source.