Go to the first, previous, next, last section, table of contents.

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 section 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 section 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 section Scripting Examples.

\

Read more command-line arguments, starting from the second line of the script file. See section 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. @vnew{1.8}

--no-debug

Do not use the debugging evaluator, even when entering an interactive session.

-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.

Go to the first, previous, next, last section, table of contents.