doc/ref/scripts.texi

   1 @page
   2 @node Guile Scripting
   3 @chapter Guile Scripting
   4
   5 Like AWK, Perl, or any shell, Guile can interpret script files.  A Guile
   6 script is simply a file of Scheme code with some extra information at
   7 the beginning which tells the operating system how to invoke Guile, and
   8 then tells Guile how to handle the Scheme code.
   9
  10 @menu
  11 * Invoking Guile::              How to start a Guile script.
  12 * The Meta Switch::             Passing complex argument lists to Guile
  13                                 from shell scripts.
  14 @end menu
  15
  16 @node Invoking Guile
  17 @section Invoking Guile
  18
  19 Here we describe Guile's command-line processing in detail.  Guile
  20 processes its arguments from left to right, recognizing the switches
  21 described below.  For examples, see @ref{Scripting Examples}.
  22
  23 @table @code
  24
  25 @item -s @var{script} @var{arg...}
  26 Read and evaluate Scheme source code from the file @var{script}, as the
  27 @code{load} function would.  After loading @var{script}, exit.  Any
  28 command-line arguments @var{arg...} following @var{script} become the
  29 script's arguments; the @code{command-line} function returns a list of
  30 strings of the form @code{(@var{script} @var{arg...})}.
  31
  32 @item -c @var{expr} @var{arg...}
  33 Evaluate @var{expr} as Scheme code, and then exit.  Any command-line
  34 arguments @var{arg...} following @var{expr} become command-line arguments; the
  35 @code{command-line} function returns a list of strings of the form
  36 @code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
  37 Guile executable.
  38
  39 @item -- @var{arg...}
  40 Run interactively, prompting the user for expressions and evaluating
  41 them.  Any command-line arguments @var{arg...} following the @code{--}
  42 become command-line arguments for the interactive session; the
  43 @code{command-line} function returns a list of strings of the form
  44 @code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
  45 Guile executable.
  46
  47 @item -l @var{file}
  48 Load Scheme source code from @var{file}, and continue processing the
  49 command line.
  50
  51 @item -e @var{function}
  52 Make @var{function} the @dfn{entry point} of the script.  After loading
  53 the script file (with @code{-s}) or evaluating the expression (with
  54 @code{-c}), apply @var{function} to a list containing the program name
  55 and the command-line arguments --- the list provided by the
  56 @code{command-line} function.
  57
  58 A @code{-e} switch can appear anywhere in the argument list, but Guile
  59 always invokes the @var{function} as the @emph{last} action it performs.
  60 This is weird, but because of the way script invocation works under
  61 POSIX, the @code{-s} option must always come last in the list.
  62
  63 @xref{Scripting Examples}.
  64
  65 @item -ds
  66 Treat a final @code{-s} option as if it occurred at this point in the
  67 command line; load the script here.
  68
  69 This switch is necessary because, although the POSIX script invocation
  70 mechanism effectively requires the @code{-s} option to appear last, the
  71 programmer may well want to run the script before other actions
  72 requested on the command line.  For examples, see @ref{Scripting
  73 Examples}.
  74
  75 @item \
  76 Read more command-line arguments, starting from the second line of the
  77 script file.  @xref{The Meta Switch}.
  78
  79 @item --emacs
  80 Assume Guile is running as an inferior process of Emacs, and use a
  81 special protocol to communicate with Emacs's Guile interaction mode.
  82 This switch sets the global variable use-emacs-interface to @code{#t}.
  83
  84 This switch is still experimental.
  85
  86 @item --use-srfi=@var{list}
  87 The option @code{--use-srfi} expects a comma-separated list of numbers,
  88 each representing a SRFI number to be loaded into the interpreter
  89 before starting evaluating a script file or the REPL.  Additionally,
  90 the feature identifier for the loaded SRFIs is recognized by
  91 `cond-expand' when using this option.
  92
  93 @example
  94 guile --use-srfi=8,13
  95 @end example
  96
  97 @item --debug
  98 Start with the debugging evaluator and enable backtraces.  Using the
  99 debugging evaluator will give you better error messages but it will
 100 slow down execution.  By default, the debugging evaluator is only used
 101 when entering an interactive session.  When executing a script with
 102 @code{-s} or @code{-c}, the normal, faster evaluator is used by default.
 103
 104 @item --no-debug
 105 Do not use the debugging evaluator, even when entering an interactive
 106 session.
 107
 108 @item -h@r{, }--help
 109 Display help on invoking Guile, and then exit.
 110
 111 @item -v@r{, }--version
 112 Display the current version of Guile, and then exit.
 113
 114 @end table
 115
 116
 117 @node The Meta Switch
 118 @section The Meta Switch
 119
 120 Guile's command-line switches allow the programmer to describe
 121 reasonably complicated actions in scripts.  Unfortunately, the POSIX
 122 script invocation mechanism only allows one argument to appear on the
 123 @samp{#!} line after the path to the Guile executable, and imposes
 124 arbitrary limits on that argument's length.  Suppose you wrote a script
 125 starting like this:
 126 @example
 127 #!/usr/local/bin/guile -e main -s
 128 !#
 129 (define (main args)
 130   (map (lambda (arg) (display arg) (display " "))
 131        (cdr args))
 132   (newline))
 133 @end example
 134 The intended meaning is clear: load the file, and then call @code{main}
 135 on the command-line arguments.  However, the system will treat
 136 everything after the Guile path as a single argument --- the string
 137 @code{"-e main -s"} --- which is not what we want.
 138
 139 As a workaround, the meta switch @code{\} allows the Guile programmer to
 140 specify an arbitrary number of options without patching the kernel.  If
 141 the first argument to Guile is @code{\}, Guile will open the script file
 142 whose name follows the @code{\}, parse arguments starting from the
 143 file's second line (according to rules described below), and substitute
 144 them for the @code{\} switch.
 145
 146 Working in concert with the meta switch, Guile treats the characters
 147 @samp{#!} as the beginning of a comment which extends through the next
 148 line containing only the characters @samp{!#}.  This sort of comment may
 149 appear anywhere in a Guile program, but it is most useful at the top of
 150 a file, meshing magically with the POSIX script invocation mechanism.
 151
 152 Thus, consider a script named @file{/u/jimb/ekko} which starts like this:
 153 @example
 154 #!/usr/local/bin/guile \
 155 -e main -s
 156 !#
 157 (define (main args)
 158         (map (lambda (arg) (display arg) (display " "))
 159              (cdr args))
 160         (newline))
 161 @end example
 162
 163 Suppose a user invokes this script as follows:
 164 @example
 165 $ /u/jimb/ekko a b c
 166 @end example
 167
 168 Here's what happens:
 169 @itemize @bullet
 170
 171 @item
 172 the operating system recognizes the @samp{#!} token at the top of the
 173 file, and rewrites the command line to:
 174 @example
 175 /usr/local/bin/guile \ /u/jimb/ekko a b c
 176 @end example
 177 This is the usual behavior, prescribed by POSIX.
 178
 179 @item
 180 When Guile sees the first two arguments, @code{\ /u/jimb/ekko}, it opens
 181 @file{/u/jimb/ekko}, parses the three arguments @code{-e}, @code{main},
 182 and @code{-s} from it, and substitutes them for the @code{\} switch.
 183 Thus, Guile's command line now reads:
 184 @example
 185 /usr/local/bin/guile -e main -s /u/jimb/ekko a b c
 186 @end example
 187
 188 @item
 189 Guile then processes these switches: it loads @file{/u/jimb/ekko} as a
 190 file of Scheme code (treating the first three lines as a comment), and
 191 then performs the application @code{(main "/u/jimb/ekko" "a" "b" "c")}.
 192
 193 @end itemize
 194
 195
 196 When Guile sees the meta switch @code{\}, it parses command-line
 197 argument from the script file according to the following rules:
 198 @itemize @bullet
 199
 200 @item
 201 Each space character terminates an argument.  This means that two
 202 spaces in a row introduce an argument @code{""}.
 203
 204 @item
 205 The tab character is not permitted (unless you quote it with the
 206 backslash character, as described below), to avoid confusion.
 207
 208 @item
 209 The newline character terminates the sequence of arguments, and will
 210 also terminate a final non-empty argument.  (However, a newline
 211 following a space will not introduce a final empty-string argument;
 212 it only terminates the argument list.)
 213
 214 @item
 215 The backslash character is the escape character.  It escapes backslash,
 216 space, tab, and newline.  The ANSI C escape sequences like @code{\n} and
 217 @code{\t} are also supported.  These produce argument constituents; the
 218 two-character combination @code{\n} doesn't act like a terminating
 219 newline.  The escape sequence @code{\@var{NNN}} for exactly three octal
 220 digits reads as the character whose ASCII code is @var{NNN}.  As above,
 221 characters produced this way are argument constituents.  Backslash
 222 followed by other characters is not allowed.
 223
 224 @end itemize