2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
9 @section Guile Scripting
11 Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
12 script is simply a file of Scheme code with some extra information at
13 the beginning which tells the operating system how to invoke Guile, and
14 then tells Guile how to handle the Scheme code.
17 * The Top of a Script File:: How to start a Guile script.
18 * Invoking Guile:: Command line options understood by Guile.
19 * The Meta Switch:: Passing complex argument lists to Guile
21 * Command Line Handling:: Accessing the command line from a script.
22 * Scripting Examples::
26 @node The Top of a Script File
27 @subsection The Top of a Script File
29 The first line of a Guile script must tell the operating system to use
30 Guile to evaluate the script, and then tell Guile how to go about doing
31 that. Here is the simplest case:
36 The first two characters of the file must be @samp{#!}.
38 The operating system interprets this to mean that the rest of the line
39 is the name of an executable that can interpret the script. Guile,
40 however, interprets these characters as the beginning of a multi-line
41 comment, terminated by the characters @samp{!#} on a line by themselves.
42 (This is an extension to the syntax described in R5RS, added to support
46 Immediately after those two characters must come the full pathname to
47 the Guile interpreter. On most systems, this would be
48 @samp{/usr/local/bin/guile}.
51 Then must come a space, followed by a command-line argument to pass to
52 Guile; this should be @samp{-s}. This switch tells Guile to run a
53 script, instead of soliciting the user for input from the terminal.
54 There are more elaborate things one can do here; see @ref{The Meta
58 Follow this with a newline.
61 The second line of the script should contain only the characters
62 @samp{!#} --- just like the top of the file, but reversed. The
63 operating system never reads this far, but Guile treats this as the end
64 of the comment begun on the first line by the @samp{#!} characters.
67 The rest of the file should be a Scheme program.
71 Guile reads the program, evaluating expressions in the order that they
72 appear. Upon reaching the end of the file, Guile exits.
76 @subsection Invoking Guile
79 Here we describe Guile's command-line processing in detail. Guile
80 processes its arguments from left to right, recognizing the switches
81 described below. For examples, see @ref{Scripting Examples}.
85 @item -s @var{script} @var{arg...}
86 Read and evaluate Scheme source code from the file @var{script}, as the
87 @code{load} function would. After loading @var{script}, exit. Any
88 command-line arguments @var{arg...} following @var{script} become the
89 script's arguments; the @code{command-line} function returns a list of
90 strings of the form @code{(@var{script} @var{arg...})}.
92 @item -c @var{expr} @var{arg...}
93 Evaluate @var{expr} as Scheme code, and then exit. Any command-line
94 arguments @var{arg...} following @var{expr} become command-line arguments; the
95 @code{command-line} function returns a list of strings of the form
96 @code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
100 Run interactively, prompting the user for expressions and evaluating
101 them. Any command-line arguments @var{arg...} following the @code{--}
102 become command-line arguments for the interactive session; the
103 @code{command-line} function returns a list of strings of the form
104 @code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
107 @item -L @var{directory}
108 Add @var{directory} to the front of Guile's module load path. The
109 given directories are searched in the order given on the command line
110 and before any directories in the GUILE_LOAD_PATH environment
111 variable. Paths added here are @emph{not} in effect during execution
112 of the user's @file{.guile} file.
115 Load Scheme source code from @var{file}, and continue processing the
118 @item -e @var{function}
119 Make @var{function} the @dfn{entry point} of the script. After loading
120 the script file (with @code{-s}) or evaluating the expression (with
121 @code{-c}), apply @var{function} to a list containing the program name
122 and the command-line arguments --- the list provided by the
123 @code{command-line} function.
125 A @code{-e} switch can appear anywhere in the argument list, but Guile
126 always invokes the @var{function} as the @emph{last} action it performs.
127 This is weird, but because of the way script invocation works under
128 POSIX, the @code{-s} option must always come last in the list.
130 The @var{function} is most often a simple symbol that names a function
131 that is defined in the script. It can also be of the form @code{(@@
132 @var{module-name} @var{symbol})} and in that case, the symbol is
133 looked up in the module named @var{module-name}.
135 For compatibility with some versions of Guile 1.4, you can also use the
136 form @code{(symbol ...)} (that is, a list of only symbols that doesn't
137 start with @code{@@}), which is equivalent to @code{(@@ (symbol ...)
138 main)}, or @code{(symbol ...) symbol} (that is, a list of only symbols
139 followed by a symbol), which is equivalent to @code{(@@ (symbol ...)
140 symbol)}. We recommend to use the equivalent forms directly since they
141 corresponf to the @code{(@@ ...)} read syntax that can be used in
142 normal code, @xref{Using Guile Modules}.
144 @xref{Scripting Examples}.
147 Treat a final @code{-s} option as if it occurred at this point in the
148 command line; load the script here.
150 This switch is necessary because, although the POSIX script invocation
151 mechanism effectively requires the @code{-s} option to appear last, the
152 programmer may well want to run the script before other actions
153 requested on the command line. For examples, see @ref{Scripting
157 Read more command-line arguments, starting from the second line of the
158 script file. @xref{The Meta Switch}.
161 Assume Guile is running as an inferior process of Emacs, and use a
162 special protocol to communicate with Emacs's Guile interaction mode.
163 This switch sets the global variable use-emacs-interface to @code{#t}.
165 This switch is still experimental.
167 @item --use-srfi=@var{list}
168 The option @code{--use-srfi} expects a comma-separated list of numbers,
169 each representing a SRFI number to be loaded into the interpreter
170 before starting evaluating a script file or the REPL. Additionally,
171 the feature identifier for the loaded SRFIs is recognized by
172 `cond-expand' when using this option.
175 guile --use-srfi=8,13
179 Start with the debugging evaluator and enable backtraces. Using the
180 debugging evaluator will give you better error messages but it will
181 slow down execution. By default, the debugging evaluator is only used
182 when entering an interactive session. When executing a script with
183 @code{-s} or @code{-c}, the normal, faster evaluator is used by default.
187 Do not use the debugging evaluator, even when entering an interactive
191 Display help on invoking Guile, and then exit.
193 @item -v@r{, }--version
194 Display the current version of Guile, and then exit.
199 @node The Meta Switch
200 @subsection The Meta Switch
202 Guile's command-line switches allow the programmer to describe
203 reasonably complicated actions in scripts. Unfortunately, the POSIX
204 script invocation mechanism only allows one argument to appear on the
205 @samp{#!} line after the path to the Guile executable, and imposes
206 arbitrary limits on that argument's length. Suppose you wrote a script
209 #!/usr/local/bin/guile -e main -s
212 (map (lambda (arg) (display arg) (display " "))
216 The intended meaning is clear: load the file, and then call @code{main}
217 on the command-line arguments. However, the system will treat
218 everything after the Guile path as a single argument --- the string
219 @code{"-e main -s"} --- which is not what we want.
221 As a workaround, the meta switch @code{\} allows the Guile programmer to
222 specify an arbitrary number of options without patching the kernel. If
223 the first argument to Guile is @code{\}, Guile will open the script file
224 whose name follows the @code{\}, parse arguments starting from the
225 file's second line (according to rules described below), and substitute
226 them for the @code{\} switch.
228 Working in concert with the meta switch, Guile treats the characters
229 @samp{#!} as the beginning of a comment which extends through the next
230 line containing only the characters @samp{!#}. This sort of comment may
231 appear anywhere in a Guile program, but it is most useful at the top of
232 a file, meshing magically with the POSIX script invocation mechanism.
234 Thus, consider a script named @file{/u/jimb/ekko} which starts like this:
236 #!/usr/local/bin/guile \
240 (map (lambda (arg) (display arg) (display " "))
245 Suppose a user invokes this script as follows:
254 the operating system recognizes the @samp{#!} token at the top of the
255 file, and rewrites the command line to:
257 /usr/local/bin/guile \ /u/jimb/ekko a b c
259 This is the usual behavior, prescribed by POSIX.
262 When Guile sees the first two arguments, @code{\ /u/jimb/ekko}, it opens
263 @file{/u/jimb/ekko}, parses the three arguments @code{-e}, @code{main},
264 and @code{-s} from it, and substitutes them for the @code{\} switch.
265 Thus, Guile's command line now reads:
267 /usr/local/bin/guile -e main -s /u/jimb/ekko a b c
271 Guile then processes these switches: it loads @file{/u/jimb/ekko} as a
272 file of Scheme code (treating the first three lines as a comment), and
273 then performs the application @code{(main "/u/jimb/ekko" "a" "b" "c")}.
278 When Guile sees the meta switch @code{\}, it parses command-line
279 argument from the script file according to the following rules:
283 Each space character terminates an argument. This means that two
284 spaces in a row introduce an argument @code{""}.
287 The tab character is not permitted (unless you quote it with the
288 backslash character, as described below), to avoid confusion.
291 The newline character terminates the sequence of arguments, and will
292 also terminate a final non-empty argument. (However, a newline
293 following a space will not introduce a final empty-string argument;
294 it only terminates the argument list.)
297 The backslash character is the escape character. It escapes backslash,
298 space, tab, and newline. The ANSI C escape sequences like @code{\n} and
299 @code{\t} are also supported. These produce argument constituents; the
300 two-character combination @code{\n} doesn't act like a terminating
301 newline. The escape sequence @code{\@var{NNN}} for exactly three octal
302 digits reads as the character whose ASCII code is @var{NNN}. As above,
303 characters produced this way are argument constituents. Backslash
304 followed by other characters is not allowed.
309 @node Command Line Handling
310 @subsection Command Line Handling
312 @c This section was written and contributed by Martin Grabmueller.
314 The ability to accept and handle command line arguments is very
315 important when writing Guile scripts to solve particular problems, such
316 as extracting information from text files or interfacing with existing
317 command line applications. This chapter describes how Guile makes
318 command line arguments available to a Guile script, and the utilities
319 that Guile provides to help with the processing of command line
322 When a Guile script is invoked, Guile makes the command line arguments
323 accessible via the procedure @code{command-line}, which returns the
324 arguments as a list of strings.
326 For example, if the script
329 #! /usr/local/bin/guile -s
331 (write (command-line))
336 is saved in a file @file{cmdline-test.scm} and invoked using the command
337 line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}, the output
341 ("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob")
344 If the script invocation includes a @code{-e} option, specifying a
345 procedure to call after loading the script, Guile will call that
346 procedure with @code{(command-line)} as its argument. So a script that
347 uses @code{-e} doesn't need to refer explicitly to @code{command-line}
348 in its code. For example, the script above would have identical
349 behaviour if it was written instead like this:
352 #! /usr/local/bin/guile \
360 (Note the use of the meta switch @code{\} so that the script invocation
361 can include more than one Guile option: @xref{The Meta Switch}.)
363 These scripts use the @code{#!} POSIX convention so that they can be
364 executed using their own file names directly, as in the example command
365 line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}. But they
366 can also be executed by typing out the implied Guile command line in
370 $ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob
377 $ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob
380 Even when a script is invoked using this longer form, the arguments that
381 the script receives are the same as if it had been invoked using the
382 short form. Guile ensures that the @code{(command-line)} or @code{-e}
383 arguments are independent of how the script is invoked, by stripping off
384 the arguments that Guile itself processes.
386 A script is free to parse and handle its command line arguments in any
387 way that it chooses. Where the set of possible options and arguments is
388 complex, however, it can get tricky to extract all the options, check
389 the validity of given arguments, and so on. This task can be greatly
390 simplified by taking advantage of the module @code{(ice-9 getopt-long)},
391 which is distributed with Guile, @xref{getopt-long}.
394 @node Scripting Examples
395 @subsection Scripting Examples
397 To start with, here are some examples of invoking Guile directly:
402 Run Guile interactively; @code{(command-line)} will return @*
403 @code{("/usr/local/bin/guile" "a" "b" "c")}.
405 @item guile -s /u/jimb/ex2 a b c
406 Load the file @file{/u/jimb/ex2}; @code{(command-line)} will return @*
407 @code{("/u/jimb/ex2" "a" "b" "c")}.
409 @item guile -c '(write %load-path) (newline)'
410 Write the value of the variable @code{%load-path}, print a newline,
413 @item guile -e main -s /u/jimb/ex4 foo
414 Load the file @file{/u/jimb/ex4}, and then call the function
415 @code{main}, passing it the list @code{("/u/jimb/ex4" "foo")}.
417 @item guile -l first -ds -l last -s script
418 Load the files @file{first}, @file{script}, and @file{last}, in that
419 order. The @code{-ds} switch says when to process the @code{-s}
420 switch. For a more motivated example, see the scripts below.
425 Here is a very simple Guile script:
427 #!/usr/local/bin/guile -s
429 (display "Hello, world!")
432 The first line marks the file as a Guile script. When the user invokes
433 it, the system runs @file{/usr/local/bin/guile} to interpret the script,
434 passing @code{-s}, the script's filename, and any arguments given to the
435 script as command-line arguments. When Guile sees @code{-s
436 @var{script}}, it loads @var{script}. Thus, running this program
442 Here is a script which prints the factorial of its argument:
444 #!/usr/local/bin/guile -s
448 (* n (fact (- n 1)))))
450 (display (fact (string->number (cadr (command-line)))))
460 However, suppose we want to use the definition of @code{fact} in this
461 file from another script. We can't simply @code{load} the script file,
462 and then use @code{fact}'s definition, because the script will try to
463 compute and display a factorial when we load it. To avoid this problem,
464 we might write the script this way:
467 #!/usr/local/bin/guile \
472 (* n (fact (- n 1)))))
475 (display (fact (string->number (cadr args))))
478 This version packages the actions the script should perform in a
479 function, @code{main}. This allows us to load the file purely for its
480 definitions, without any extraneous computation taking place. Then we
481 used the meta switch @code{\} and the entry point switch @code{-e} to
482 tell Guile to call @code{main} after loading the script.
485 30414093201713378043612608166064768844377641568960512000000000000
488 Suppose that we now want to write a script which computes the
489 @code{choose} function: given a set of @var{m} distinct objects,
490 @code{(choose @var{n} @var{m})} is the number of distinct subsets
491 containing @var{n} objects each. It's easy to write @code{choose} given
492 @code{fact}, so we might write the script this way:
494 #!/usr/local/bin/guile \
498 (/ (fact m) (* (fact (- m n)) (fact n))))
501 (let ((n (string->number (cadr args)))
502 (m (string->number (caddr args))))
503 (display (choose n m))
507 The command-line arguments here tell Guile to first load the file
508 @file{fact}, and then run the script, with @code{main} as the entry
509 point. In other words, the @code{choose} script can use definitions
510 made in the @code{fact} script. Here are some sample runs:
523 100891344545564193334812497256
528 @c TeX-master: "guile.texi"