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 If this source code file is not ASCII or ISO-8859-1 encoded, a coding
68 declaration such as @code{coding: utf-8} should appear in a comment
69 somewhere in the first five lines of the file: see @ref{Character
70 Encoding of Source Files}.
73 The rest of the file should be a Scheme program.
77 Guile reads the program, evaluating expressions in the order that they
78 appear. Upon reaching the end of the file, Guile exits.
82 @subsection Invoking Guile
85 Here we describe Guile's command-line processing in detail. Guile
86 processes its arguments from left to right, recognizing the switches
87 described below. For examples, see @ref{Scripting Examples}.
91 @item -s @var{script} @var{arg...}
92 Read and evaluate Scheme source code from the file @var{script}, as the
93 @code{load} function would. After loading @var{script}, exit. Any
94 command-line arguments @var{arg...} following @var{script} become the
95 script's arguments; the @code{command-line} function returns a list of
96 strings of the form @code{(@var{script} @var{arg...})}.
98 @item -c @var{expr} @var{arg...}
99 Evaluate @var{expr} as Scheme code, and then exit. Any command-line
100 arguments @var{arg...} following @var{expr} become command-line arguments; the
101 @code{command-line} function returns a list of strings of the form
102 @code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
105 @item -- @var{arg...}
106 Run interactively, prompting the user for expressions and evaluating
107 them. Any command-line arguments @var{arg...} following the @code{--}
108 become command-line arguments for the interactive session; the
109 @code{command-line} function returns a list of strings of the form
110 @code{(@var{guile} @var{arg...})}, where @var{guile} is the path of the
113 @item -L @var{directory}
114 Add @var{directory} to the front of Guile's module load path. The
115 given directories are searched in the order given on the command line
116 and before any directories in the GUILE_LOAD_PATH environment
117 variable. Paths added here are @emph{not} in effect during execution
118 of the user's @file{.guile} file.
121 Load Scheme source code from @var{file}, and continue processing the
124 @item -e @var{function}
125 Make @var{function} the @dfn{entry point} of the script. After loading
126 the script file (with @code{-s}) or evaluating the expression (with
127 @code{-c}), apply @var{function} to a list containing the program name
128 and the command-line arguments --- the list provided by the
129 @code{command-line} function.
131 A @code{-e} switch can appear anywhere in the argument list, but Guile
132 always invokes the @var{function} as the @emph{last} action it performs.
133 This is weird, but because of the way script invocation works under
134 POSIX, the @code{-s} option must always come last in the list.
136 The @var{function} is most often a simple symbol that names a function
137 that is defined in the script. It can also be of the form @code{(@@
138 @var{module-name} @var{symbol})} and in that case, the symbol is
139 looked up in the module named @var{module-name}.
141 For compatibility with some versions of Guile 1.4, you can also use the
142 form @code{(symbol ...)} (that is, a list of only symbols that doesn't
143 start with @code{@@}), which is equivalent to @code{(@@ (symbol ...)
144 main)}, or @code{(symbol ...) symbol} (that is, a list of only symbols
145 followed by a symbol), which is equivalent to @code{(@@ (symbol ...)
146 symbol)}. We recommend to use the equivalent forms directly since they
147 correspond to the @code{(@@ ...)} read syntax that can be used in
148 normal code, @xref{Using Guile Modules}.
150 @xref{Scripting Examples}.
153 Treat a final @code{-s} option as if it occurred at this point in the
154 command line; load the script here.
156 This switch is necessary because, although the POSIX script invocation
157 mechanism effectively requires the @code{-s} option to appear last, the
158 programmer may well want to run the script before other actions
159 requested on the command line. For examples, see @ref{Scripting
163 Read more command-line arguments, starting from the second line of the
164 script file. @xref{The Meta Switch}.
167 Assume Guile is running as an inferior process of Emacs, and use a
168 special protocol to communicate with Emacs's Guile interaction mode.
169 This switch sets the global variable use-emacs-interface to @code{#t}.
171 This switch is still experimental.
173 @item --use-srfi=@var{list}
174 The option @code{--use-srfi} expects a comma-separated list of numbers,
175 each representing a SRFI number to be loaded into the interpreter
176 before starting evaluating a script file or the REPL. Additionally,
177 the feature identifier for the loaded SRFIs is recognized by
178 `cond-expand' when using this option.
181 guile --use-srfi=8,13
185 Start with the debugging evaluator and enable backtraces. Using the
186 debugging evaluator will give you better error messages but it will
187 slow down execution. By default, the debugging evaluator is only used
188 when entering an interactive session. When executing a script with
189 @code{-s} or @code{-c}, the normal, faster evaluator is used by default.
193 Do not use the debugging evaluator, even when entering an interactive
197 Display help on invoking Guile, and then exit.
199 @item -v@r{, }--version
200 Display the current version of Guile, and then exit.
205 @node The Meta Switch
206 @subsection The Meta Switch
208 Guile's command-line switches allow the programmer to describe
209 reasonably complicated actions in scripts. Unfortunately, the POSIX
210 script invocation mechanism only allows one argument to appear on the
211 @samp{#!} line after the path to the Guile executable, and imposes
212 arbitrary limits on that argument's length. Suppose you wrote a script
215 #!/usr/local/bin/guile -e main -s
218 (map (lambda (arg) (display arg) (display " "))
222 The intended meaning is clear: load the file, and then call @code{main}
223 on the command-line arguments. However, the system will treat
224 everything after the Guile path as a single argument --- the string
225 @code{"-e main -s"} --- which is not what we want.
227 As a workaround, the meta switch @code{\} allows the Guile programmer to
228 specify an arbitrary number of options without patching the kernel. If
229 the first argument to Guile is @code{\}, Guile will open the script file
230 whose name follows the @code{\}, parse arguments starting from the
231 file's second line (according to rules described below), and substitute
232 them for the @code{\} switch.
234 Working in concert with the meta switch, Guile treats the characters
235 @samp{#!} as the beginning of a comment which extends through the next
236 line containing only the characters @samp{!#}. This sort of comment may
237 appear anywhere in a Guile program, but it is most useful at the top of
238 a file, meshing magically with the POSIX script invocation mechanism.
240 Thus, consider a script named @file{/u/jimb/ekko} which starts like this:
242 #!/usr/local/bin/guile \
246 (map (lambda (arg) (display arg) (display " "))
251 Suppose a user invokes this script as follows:
260 the operating system recognizes the @samp{#!} token at the top of the
261 file, and rewrites the command line to:
263 /usr/local/bin/guile \ /u/jimb/ekko a b c
265 This is the usual behavior, prescribed by POSIX.
268 When Guile sees the first two arguments, @code{\ /u/jimb/ekko}, it opens
269 @file{/u/jimb/ekko}, parses the three arguments @code{-e}, @code{main},
270 and @code{-s} from it, and substitutes them for the @code{\} switch.
271 Thus, Guile's command line now reads:
273 /usr/local/bin/guile -e main -s /u/jimb/ekko a b c
277 Guile then processes these switches: it loads @file{/u/jimb/ekko} as a
278 file of Scheme code (treating the first three lines as a comment), and
279 then performs the application @code{(main "/u/jimb/ekko" "a" "b" "c")}.
284 When Guile sees the meta switch @code{\}, it parses command-line
285 argument from the script file according to the following rules:
289 Each space character terminates an argument. This means that two
290 spaces in a row introduce an argument @code{""}.
293 The tab character is not permitted (unless you quote it with the
294 backslash character, as described below), to avoid confusion.
297 The newline character terminates the sequence of arguments, and will
298 also terminate a final non-empty argument. (However, a newline
299 following a space will not introduce a final empty-string argument;
300 it only terminates the argument list.)
303 The backslash character is the escape character. It escapes backslash,
304 space, tab, and newline. The ANSI C escape sequences like @code{\n} and
305 @code{\t} are also supported. These produce argument constituents; the
306 two-character combination @code{\n} doesn't act like a terminating
307 newline. The escape sequence @code{\@var{NNN}} for exactly three octal
308 digits reads as the character whose ASCII code is @var{NNN}. As above,
309 characters produced this way are argument constituents. Backslash
310 followed by other characters is not allowed.
315 @node Command Line Handling
316 @subsection Command Line Handling
318 @c This section was written and contributed by Martin Grabmueller.
320 The ability to accept and handle command line arguments is very
321 important when writing Guile scripts to solve particular problems, such
322 as extracting information from text files or interfacing with existing
323 command line applications. This chapter describes how Guile makes
324 command line arguments available to a Guile script, and the utilities
325 that Guile provides to help with the processing of command line
328 When a Guile script is invoked, Guile makes the command line arguments
329 accessible via the procedure @code{command-line}, which returns the
330 arguments as a list of strings.
332 For example, if the script
335 #! /usr/local/bin/guile -s
337 (write (command-line))
342 is saved in a file @file{cmdline-test.scm} and invoked using the command
343 line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}, the output
347 ("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob")
350 If the script invocation includes a @code{-e} option, specifying a
351 procedure to call after loading the script, Guile will call that
352 procedure with @code{(command-line)} as its argument. So a script that
353 uses @code{-e} doesn't need to refer explicitly to @code{command-line}
354 in its code. For example, the script above would have identical
355 behaviour if it was written instead like this:
358 #! /usr/local/bin/guile \
366 (Note the use of the meta switch @code{\} so that the script invocation
367 can include more than one Guile option: @xref{The Meta Switch}.)
369 These scripts use the @code{#!} POSIX convention so that they can be
370 executed using their own file names directly, as in the example command
371 line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}. But they
372 can also be executed by typing out the implied Guile command line in
376 $ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob
383 $ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob
386 Even when a script is invoked using this longer form, the arguments that
387 the script receives are the same as if it had been invoked using the
388 short form. Guile ensures that the @code{(command-line)} or @code{-e}
389 arguments are independent of how the script is invoked, by stripping off
390 the arguments that Guile itself processes.
392 A script is free to parse and handle its command line arguments in any
393 way that it chooses. Where the set of possible options and arguments is
394 complex, however, it can get tricky to extract all the options, check
395 the validity of given arguments, and so on. This task can be greatly
396 simplified by taking advantage of the module @code{(ice-9 getopt-long)},
397 which is distributed with Guile, @xref{getopt-long}.
400 @node Scripting Examples
401 @subsection Scripting Examples
403 To start with, here are some examples of invoking Guile directly:
408 Run Guile interactively; @code{(command-line)} will return @*
409 @code{("/usr/local/bin/guile" "a" "b" "c")}.
411 @item guile -s /u/jimb/ex2 a b c
412 Load the file @file{/u/jimb/ex2}; @code{(command-line)} will return @*
413 @code{("/u/jimb/ex2" "a" "b" "c")}.
415 @item guile -c '(write %load-path) (newline)'
416 Write the value of the variable @code{%load-path}, print a newline,
419 @item guile -e main -s /u/jimb/ex4 foo
420 Load the file @file{/u/jimb/ex4}, and then call the function
421 @code{main}, passing it the list @code{("/u/jimb/ex4" "foo")}.
423 @item guile -l first -ds -l last -s script
424 Load the files @file{first}, @file{script}, and @file{last}, in that
425 order. The @code{-ds} switch says when to process the @code{-s}
426 switch. For a more motivated example, see the scripts below.
431 Here is a very simple Guile script:
433 #!/usr/local/bin/guile -s
435 (display "Hello, world!")
438 The first line marks the file as a Guile script. When the user invokes
439 it, the system runs @file{/usr/local/bin/guile} to interpret the script,
440 passing @code{-s}, the script's filename, and any arguments given to the
441 script as command-line arguments. When Guile sees @code{-s
442 @var{script}}, it loads @var{script}. Thus, running this program
448 Here is a script which prints the factorial of its argument:
450 #!/usr/local/bin/guile -s
454 (* n (fact (- n 1)))))
456 (display (fact (string->number (cadr (command-line)))))
466 However, suppose we want to use the definition of @code{fact} in this
467 file from another script. We can't simply @code{load} the script file,
468 and then use @code{fact}'s definition, because the script will try to
469 compute and display a factorial when we load it. To avoid this problem,
470 we might write the script this way:
473 #!/usr/local/bin/guile \
478 (* n (fact (- n 1)))))
481 (display (fact (string->number (cadr args))))
484 This version packages the actions the script should perform in a
485 function, @code{main}. This allows us to load the file purely for its
486 definitions, without any extraneous computation taking place. Then we
487 used the meta switch @code{\} and the entry point switch @code{-e} to
488 tell Guile to call @code{main} after loading the script.
491 30414093201713378043612608166064768844377641568960512000000000000
494 Suppose that we now want to write a script which computes the
495 @code{choose} function: given a set of @var{m} distinct objects,
496 @code{(choose @var{n} @var{m})} is the number of distinct subsets
497 containing @var{n} objects each. It's easy to write @code{choose} given
498 @code{fact}, so we might write the script this way:
500 #!/usr/local/bin/guile \
504 (/ (fact m) (* (fact (- m n)) (fact n))))
507 (let ((n (string->number (cadr args)))
508 (m (string->number (caddr args))))
509 (display (choose n m))
513 The command-line arguments here tell Guile to first load the file
514 @file{fact}, and then run the script, with @code{main} as the entry
515 point. In other words, the @code{choose} script can use definitions
516 made in the @code{fact} script. Here are some sample runs:
529 100891344545564193334812497256
534 @c TeX-master: "guile.texi"