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 @xref{Scripting Examples}.
138 Treat a final @code{-s} option as if it occurred at this point in the
139 command line; load the script here.
141 This switch is necessary because, although the POSIX script invocation
142 mechanism effectively requires the @code{-s} option to appear last, the
143 programmer may well want to run the script before other actions
144 requested on the command line. For examples, see @ref{Scripting
148 Read more command-line arguments, starting from the second line of the
149 script file. @xref{The Meta Switch}.
152 Assume Guile is running as an inferior process of Emacs, and use a
153 special protocol to communicate with Emacs's Guile interaction mode.
154 This switch sets the global variable use-emacs-interface to @code{#t}.
156 This switch is still experimental.
158 @item --use-srfi=@var{list}
159 The option @code{--use-srfi} expects a comma-separated list of numbers,
160 each representing a SRFI number to be loaded into the interpreter
161 before starting evaluating a script file or the REPL. Additionally,
162 the feature identifier for the loaded SRFIs is recognized by
163 `cond-expand' when using this option.
166 guile --use-srfi=8,13
170 Start with the debugging evaluator and enable backtraces. Using the
171 debugging evaluator will give you better error messages but it will
172 slow down execution. By default, the debugging evaluator is only used
173 when entering an interactive session. When executing a script with
174 @code{-s} or @code{-c}, the normal, faster evaluator is used by default.
178 Do not use the debugging evaluator, even when entering an interactive
182 Display help on invoking Guile, and then exit.
184 @item -v@r{, }--version
185 Display the current version of Guile, and then exit.
190 @node The Meta Switch
191 @subsection The Meta Switch
193 Guile's command-line switches allow the programmer to describe
194 reasonably complicated actions in scripts. Unfortunately, the POSIX
195 script invocation mechanism only allows one argument to appear on the
196 @samp{#!} line after the path to the Guile executable, and imposes
197 arbitrary limits on that argument's length. Suppose you wrote a script
200 #!/usr/local/bin/guile -e main -s
203 (map (lambda (arg) (display arg) (display " "))
207 The intended meaning is clear: load the file, and then call @code{main}
208 on the command-line arguments. However, the system will treat
209 everything after the Guile path as a single argument --- the string
210 @code{"-e main -s"} --- which is not what we want.
212 As a workaround, the meta switch @code{\} allows the Guile programmer to
213 specify an arbitrary number of options without patching the kernel. If
214 the first argument to Guile is @code{\}, Guile will open the script file
215 whose name follows the @code{\}, parse arguments starting from the
216 file's second line (according to rules described below), and substitute
217 them for the @code{\} switch.
219 Working in concert with the meta switch, Guile treats the characters
220 @samp{#!} as the beginning of a comment which extends through the next
221 line containing only the characters @samp{!#}. This sort of comment may
222 appear anywhere in a Guile program, but it is most useful at the top of
223 a file, meshing magically with the POSIX script invocation mechanism.
225 Thus, consider a script named @file{/u/jimb/ekko} which starts like this:
227 #!/usr/local/bin/guile \
231 (map (lambda (arg) (display arg) (display " "))
236 Suppose a user invokes this script as follows:
245 the operating system recognizes the @samp{#!} token at the top of the
246 file, and rewrites the command line to:
248 /usr/local/bin/guile \ /u/jimb/ekko a b c
250 This is the usual behavior, prescribed by POSIX.
253 When Guile sees the first two arguments, @code{\ /u/jimb/ekko}, it opens
254 @file{/u/jimb/ekko}, parses the three arguments @code{-e}, @code{main},
255 and @code{-s} from it, and substitutes them for the @code{\} switch.
256 Thus, Guile's command line now reads:
258 /usr/local/bin/guile -e main -s /u/jimb/ekko a b c
262 Guile then processes these switches: it loads @file{/u/jimb/ekko} as a
263 file of Scheme code (treating the first three lines as a comment), and
264 then performs the application @code{(main "/u/jimb/ekko" "a" "b" "c")}.
269 When Guile sees the meta switch @code{\}, it parses command-line
270 argument from the script file according to the following rules:
274 Each space character terminates an argument. This means that two
275 spaces in a row introduce an argument @code{""}.
278 The tab character is not permitted (unless you quote it with the
279 backslash character, as described below), to avoid confusion.
282 The newline character terminates the sequence of arguments, and will
283 also terminate a final non-empty argument. (However, a newline
284 following a space will not introduce a final empty-string argument;
285 it only terminates the argument list.)
288 The backslash character is the escape character. It escapes backslash,
289 space, tab, and newline. The ANSI C escape sequences like @code{\n} and
290 @code{\t} are also supported. These produce argument constituents; the
291 two-character combination @code{\n} doesn't act like a terminating
292 newline. The escape sequence @code{\@var{NNN}} for exactly three octal
293 digits reads as the character whose ASCII code is @var{NNN}. As above,
294 characters produced this way are argument constituents. Backslash
295 followed by other characters is not allowed.
300 @node Command Line Handling
301 @subsection Command Line Handling
303 @c This section was written and contributed by Martin Grabmueller.
305 The ability to accept and handle command line arguments is very
306 important when writing Guile scripts to solve particular problems, such
307 as extracting information from text files or interfacing with existing
308 command line applications. This chapter describes how Guile makes
309 command line arguments available to a Guile script, and the utilities
310 that Guile provides to help with the processing of command line
313 When a Guile script is invoked, Guile makes the command line arguments
314 accessible via the procedure @code{command-line}, which returns the
315 arguments as a list of strings.
317 For example, if the script
320 #! /usr/local/bin/guile -s
322 (write (command-line))
327 is saved in a file @file{cmdline-test.scm} and invoked using the command
328 line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}, the output
332 ("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob")
335 If the script invocation includes a @code{-e} option, specifying a
336 procedure to call after loading the script, Guile will call that
337 procedure with @code{(command-line)} as its argument. So a script that
338 uses @code{-e} doesn't need to refer explicitly to @code{command-line}
339 in its code. For example, the script above would have identical
340 behaviour if it was written instead like this:
343 #! /usr/local/bin/guile \
351 (Note the use of the meta switch @code{\} so that the script invocation
352 can include more than one Guile option: @xref{The Meta Switch}.)
354 These scripts use the @code{#!} POSIX convention so that they can be
355 executed using their own file names directly, as in the example command
356 line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}. But they
357 can also be executed by typing out the implied Guile command line in
361 $ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob
368 $ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob
371 Even when a script is invoked using this longer form, the arguments that
372 the script receives are the same as if it had been invoked using the
373 short form. Guile ensures that the @code{(command-line)} or @code{-e}
374 arguments are independent of how the script is invoked, by stripping off
375 the arguments that Guile itself processes.
377 A script is free to parse and handle its command line arguments in any
378 way that it chooses. Where the set of possible options and arguments is
379 complex, however, it can get tricky to extract all the options, check
380 the validity of given arguments, and so on. This task can be greatly
381 simplified by taking advantage of the module @code{(ice-9 getopt-long)},
382 which is distributed with Guile, @xref{getopt-long}.
385 @node Scripting Examples
386 @subsection Scripting Examples
388 To start with, here are some examples of invoking Guile directly:
393 Run Guile interactively; @code{(command-line)} will return @*
394 @code{("/usr/local/bin/guile" "a" "b" "c")}.
396 @item guile -s /u/jimb/ex2 a b c
397 Load the file @file{/u/jimb/ex2}; @code{(command-line)} will return @*
398 @code{("/u/jimb/ex2" "a" "b" "c")}.
400 @item guile -c '(write %load-path) (newline)'
401 Write the value of the variable @code{%load-path}, print a newline,
404 @item guile -e main -s /u/jimb/ex4 foo
405 Load the file @file{/u/jimb/ex4}, and then call the function
406 @code{main}, passing it the list @code{("/u/jimb/ex4" "foo")}.
408 @item guile -l first -ds -l last -s script
409 Load the files @file{first}, @file{script}, and @file{last}, in that
410 order. The @code{-ds} switch says when to process the @code{-s}
411 switch. For a more motivated example, see the scripts below.
416 Here is a very simple Guile script:
418 #!/usr/local/bin/guile -s
420 (display "Hello, world!")
423 The first line marks the file as a Guile script. When the user invokes
424 it, the system runs @file{/usr/local/bin/guile} to interpret the script,
425 passing @code{-s}, the script's filename, and any arguments given to the
426 script as command-line arguments. When Guile sees @code{-s
427 @var{script}}, it loads @var{script}. Thus, running this program
433 Here is a script which prints the factorial of its argument:
435 #!/usr/local/bin/guile -s
439 (* n (fact (- n 1)))))
441 (display (fact (string->number (cadr (command-line)))))
451 However, suppose we want to use the definition of @code{fact} in this
452 file from another script. We can't simply @code{load} the script file,
453 and then use @code{fact}'s definition, because the script will try to
454 compute and display a factorial when we load it. To avoid this problem,
455 we might write the script this way:
458 #!/usr/local/bin/guile \
463 (* n (fact (- n 1)))))
466 (display (fact (string->number (cadr args))))
469 This version packages the actions the script should perform in a
470 function, @code{main}. This allows us to load the file purely for its
471 definitions, without any extraneous computation taking place. Then we
472 used the meta switch @code{\} and the entry point switch @code{-e} to
473 tell Guile to call @code{main} after loading the script.
476 30414093201713378043612608166064768844377641568960512000000000000
479 Suppose that we now want to write a script which computes the
480 @code{choose} function: given a set of @var{m} distinct objects,
481 @code{(choose @var{n} @var{m})} is the number of distinct subsets
482 containing @var{n} objects each. It's easy to write @code{choose} given
483 @code{fact}, so we might write the script this way:
485 #!/usr/local/bin/guile \
489 (/ (fact m) (* (fact (- m n)) (fact n))))
492 (let ((n (string->number (cadr args)))
493 (m (string->number (caddr args))))
494 (display (choose n m))
498 The command-line arguments here tell Guile to first load the file
499 @file{fact}, and then run the script, with @code{main} as the entry
500 point. In other words, the @code{choose} script can use definitions
501 made in the @code{fact} script. Here are some sample runs:
514 100891344545564193334812497256
519 @c TeX-master: "guile.texi"