-
-@node Guile Scripting
-@chapter 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.
-@end menu
-
-@node Invoking Guile
-@section 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 @ref{Scripting Examples}.
-
-@table @code
-
-@item -s @var{script} @var{arg...}
-Read and evaluate Scheme source code from the file @var{script}, as the
-@code{load} function would. After loading @var{script}, exit. Any
-command-line arguments @var{arg...} following @var{script} become the
-script's arguments; the @code{command-line} function returns a list of
-strings of the form @code{(@var{script} @var{arg...})}.
-
-@item -c @var{expr} @var{arg...}
-Evaluate @var{expr} as Scheme code, and then exit. Any command-line
-arguments @var{arg...} following @var{expr} become command-line arguments; the
-@code{command-line} function returns a list of strings of the form
-@code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
-Guile executable.
-
-@item -- @var{arg...}
-Run interactively, prompting the user for expressions and evaluating
-them. Any command-line arguments @var{arg...} following the @code{--}
-become command-line arguments for the interactive session; the
-@code{command-line} function returns a list of strings of the form
-@code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
-Guile executable.
-
-@item -l @var{file}
-Load Scheme source code from @var{file}, and continue processing the
-command line.
-
-@item -e @var{function}
-Make @var{function} the @dfn{entry point} of the script. After loading
-the script file (with @code{-s}) or evaluating the expression (with
-@code{-c}), apply @var{function} to a list containing the program name
-and the command-line arguments --- the list provided by the
-@code{command-line} function.
-
-A @code{-e} switch can appear anywhere in the argument list, but Guile
-always invokes the @var{function} as the @emph{last} action it performs.
-This is weird, but because of the way script invocation works under
-POSIX, the @code{-s} option must always come last in the list.
-
-@xref{Scripting Examples}.
-
-@item -ds
-Treat a final @code{-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 @code{-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 @ref{Scripting
-Examples}.
-
-@item \
-Read more command-line arguments, starting from the second line of the
-script file. @xref{The Meta Switch}.
-
-@item --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 @code{#t}.
-
-This switch is still experimental.
-
-@item --use-srfi=@var{list}
-The option @code{--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.
-
-@example
-guile --use-srfi=8,13
-@end example
-
-@item -h@r{, }--help
-Display help on invoking Guile, and then exit.
-
-@item -v@r{, }--version
-Display the current version of Guile, and then exit.
-
-@end table
-
-
-@node The Meta Switch
-@section 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
-@samp{#!} 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:
-@example
-#!/usr/local/bin/guile -e main -s
-!#
-(define (main args)
- (map (lambda (arg) (display arg) (display " "))
- (cdr args))
- (newline))
-@end example
-The intended meaning is clear: load the file, and then call @code{main}
-on the command-line arguments. However, the system will treat
-everything after the Guile path as a single argument --- the string
-@code{"-e main -s"} --- which is not what we want.
-
-As a workaround, the meta switch @code{\} allows the Guile programmer to
-specify an arbitrary number of options without patching the kernel. If
-the first argument to Guile is @code{\}, Guile will open the script file
-whose name follows the @code{\}, parse arguments starting from the
-file's second line (according to rules described below), and substitute
-them for the @code{\} switch.
-
-Working in concert with the meta switch, Guile treats the characters
-@samp{#!} as the beginning of a comment which extends through the next
-line containing only the characters @samp{!#}. 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 @file{/u/jimb/ekko} which starts like this:
-@example
-#!/usr/local/bin/guile \
--e main -s
-!#
-(define (main args)
- (map (lambda (arg) (display arg) (display " "))
- (cdr args))
- (newline))
-@end example
-
-Suppose a user invokes this script as follows:
-@example
-$ /u/jimb/ekko a b c
-@end example
-
-Here's what happens:
-@itemize @bullet
-
-@item
-the operating system recognizes the @samp{#!} token at the top of the
-file, and rewrites the command line to:
-@example
-/usr/local/bin/guile \ /u/jimb/ekko a b c
-@end example
-This is the usual behavior, prescribed by POSIX.
-
-@item
-When Guile sees the first two arguments, @code{\ /u/jimb/ekko}, it opens
-@file{/u/jimb/ekko}, parses the three arguments @code{-e}, @code{main},
-and @code{-s} from it, and substitutes them for the @code{\} switch.
-Thus, Guile's command line now reads:
-@example
-/usr/local/bin/guile -e main -s /u/jimb/ekko a b c
-@end example
-
-@item
-Guile then processes these switches: it loads @file{/u/jimb/ekko} as a
-file of Scheme code (treating the first three lines as a comment), and
-then performs the application @code{(main "/u/jimb/ekko" "a" "b" "c")}.
-
-@end itemize
-
-
-When Guile sees the meta switch @code{\}, it parses command-line
-argument from the script file according to the following rules:
-@itemize @bullet
-
-@item
-Each space character terminates an argument. This means that two
-spaces in a row introduce an argument @code{""}.
-
-@item
-The tab character is not permitted (unless you quote it with the
-backslash character, as described below), to avoid confusion.
-
-@item
-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.)
-
-@item
-The backslash character is the escape character. It escapes backslash,
-space, tab, and newline. The ANSI C escape sequences like @code{\n} and
-@code{\t} are also supported. These produce argument constituents; the
-two-character combination @code{\n} doesn't act like a terminating
-newline. The escape sequence @code{\@var{NNN}} for exactly three octal
-digits reads as the character whose ASCII code is @var{NNN}. As above,
-characters produced this way are argument constituents. Backslash
-followed by other characters is not allowed.
-
-@end itemize
HCoop / bpt / guile.git / blobdiff