2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @section Guile Scripting
10 Like AWK, Perl, or any shell, Guile can interpret script files. A Guile
11 script is simply a file of Scheme code with some extra information at
12 the beginning which tells the operating system how to invoke Guile, and
13 then tells Guile how to handle the Scheme code.
16 * The Top of a Script File:: How to start a Guile script.
17 * The Meta Switch:: Passing complex argument lists to Guile
19 * Command Line Handling:: Accessing the command line from a script.
20 * Scripting Examples::
24 @node The Top of a Script File
25 @subsection The Top of a Script File
27 The first line of a Guile script must tell the operating system to use
28 Guile to evaluate the script, and then tell Guile how to go about doing
29 that. Here is the simplest case:
34 The first two characters of the file must be @samp{#!}.
36 The operating system interprets this to mean that the rest of the line
37 is the name of an executable that can interpret the script. Guile,
38 however, interprets these characters as the beginning of a multi-line
39 comment, terminated by the characters @samp{!#} on a line by themselves.
40 (This is an extension to the syntax described in R5RS, added to support
44 Immediately after those two characters must come the full pathname to
45 the Guile interpreter. On most systems, this would be
46 @samp{/usr/local/bin/guile}.
49 Then must come a space, followed by a command-line argument to pass to
50 Guile; this should be @samp{-s}. This switch tells Guile to run a
51 script, instead of soliciting the user for input from the terminal.
52 There are more elaborate things one can do here; see @ref{The Meta
56 Follow this with a newline.
59 The second line of the script should contain only the characters
60 @samp{!#} --- just like the top of the file, but reversed. The
61 operating system never reads this far, but Guile treats this as the end
62 of the comment begun on the first line by the @samp{#!} characters.
65 If this source code file is not ASCII or ISO-8859-1 encoded, a coding
66 declaration such as @code{coding: utf-8} should appear in a comment
67 somewhere in the first five lines of the file: see @ref{Character
68 Encoding of Source Files}.
71 The rest of the file should be a Scheme program.
75 Guile reads the program, evaluating expressions in the order that they
76 appear. Upon reaching the end of the file, Guile exits.
79 @subsection The Meta Switch
81 Guile's command-line switches allow the programmer to describe
82 reasonably complicated actions in scripts. Unfortunately, the POSIX
83 script invocation mechanism only allows one argument to appear on the
84 @samp{#!} line after the path to the Guile executable, and imposes
85 arbitrary limits on that argument's length. Suppose you wrote a script
88 #!/usr/local/bin/guile -e main -s
91 (map (lambda (arg) (display arg) (display " "))
95 The intended meaning is clear: load the file, and then call @code{main}
96 on the command-line arguments. However, the system will treat
97 everything after the Guile path as a single argument --- the string
98 @code{"-e main -s"} --- which is not what we want.
100 As a workaround, the meta switch @code{\} allows the Guile programmer to
101 specify an arbitrary number of options without patching the kernel. If
102 the first argument to Guile is @code{\}, Guile will open the script file
103 whose name follows the @code{\}, parse arguments starting from the
104 file's second line (according to rules described below), and substitute
105 them for the @code{\} switch.
107 Working in concert with the meta switch, Guile treats the characters
108 @samp{#!} as the beginning of a comment which extends through the next
109 line containing only the characters @samp{!#}. This sort of comment may
110 appear anywhere in a Guile program, but it is most useful at the top of
111 a file, meshing magically with the POSIX script invocation mechanism.
113 Thus, consider a script named @file{/u/jimb/ekko} which starts like this:
115 #!/usr/local/bin/guile \
119 (map (lambda (arg) (display arg) (display " "))
124 Suppose a user invokes this script as follows:
133 the operating system recognizes the @samp{#!} token at the top of the
134 file, and rewrites the command line to:
136 /usr/local/bin/guile \ /u/jimb/ekko a b c
138 This is the usual behavior, prescribed by POSIX.
141 When Guile sees the first two arguments, @code{\ /u/jimb/ekko}, it opens
142 @file{/u/jimb/ekko}, parses the three arguments @code{-e}, @code{main},
143 and @code{-s} from it, and substitutes them for the @code{\} switch.
144 Thus, Guile's command line now reads:
146 /usr/local/bin/guile -e main -s /u/jimb/ekko a b c
150 Guile then processes these switches: it loads @file{/u/jimb/ekko} as a
151 file of Scheme code (treating the first three lines as a comment), and
152 then performs the application @code{(main "/u/jimb/ekko" "a" "b" "c")}.
157 When Guile sees the meta switch @code{\}, it parses command-line
158 argument from the script file according to the following rules:
162 Each space character terminates an argument. This means that two
163 spaces in a row introduce an argument @code{""}.
166 The tab character is not permitted (unless you quote it with the
167 backslash character, as described below), to avoid confusion.
170 The newline character terminates the sequence of arguments, and will
171 also terminate a final non-empty argument. (However, a newline
172 following a space will not introduce a final empty-string argument;
173 it only terminates the argument list.)
176 The backslash character is the escape character. It escapes backslash,
177 space, tab, and newline. The ANSI C escape sequences like @code{\n} and
178 @code{\t} are also supported. These produce argument constituents; the
179 two-character combination @code{\n} doesn't act like a terminating
180 newline. The escape sequence @code{\@var{NNN}} for exactly three octal
181 digits reads as the character whose ASCII code is @var{NNN}. As above,
182 characters produced this way are argument constituents. Backslash
183 followed by other characters is not allowed.
188 @node Command Line Handling
189 @subsection Command Line Handling
191 @c This section was written and contributed by Martin Grabmueller.
193 The ability to accept and handle command line arguments is very
194 important when writing Guile scripts to solve particular problems, such
195 as extracting information from text files or interfacing with existing
196 command line applications. This chapter describes how Guile makes
197 command line arguments available to a Guile script, and the utilities
198 that Guile provides to help with the processing of command line
201 When a Guile script is invoked, Guile makes the command line arguments
202 accessible via the procedure @code{command-line}, which returns the
203 arguments as a list of strings.
205 For example, if the script
208 #! /usr/local/bin/guile -s
210 (write (command-line))
215 is saved in a file @file{cmdline-test.scm} and invoked using the command
216 line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}, the output
220 ("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob")
223 If the script invocation includes a @code{-e} option, specifying a
224 procedure to call after loading the script, Guile will call that
225 procedure with @code{(command-line)} as its argument. So a script that
226 uses @code{-e} doesn't need to refer explicitly to @code{command-line}
227 in its code. For example, the script above would have identical
228 behaviour if it was written instead like this:
231 #! /usr/local/bin/guile \
239 (Note the use of the meta switch @code{\} so that the script invocation
240 can include more than one Guile option: @xref{The Meta Switch}.)
242 These scripts use the @code{#!} POSIX convention so that they can be
243 executed using their own file names directly, as in the example command
244 line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}. But they
245 can also be executed by typing out the implied Guile command line in
249 $ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob
256 $ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob
259 Even when a script is invoked using this longer form, the arguments that
260 the script receives are the same as if it had been invoked using the
261 short form. Guile ensures that the @code{(command-line)} or @code{-e}
262 arguments are independent of how the script is invoked, by stripping off
263 the arguments that Guile itself processes.
265 A script is free to parse and handle its command line arguments in any
266 way that it chooses. Where the set of possible options and arguments is
267 complex, however, it can get tricky to extract all the options, check
268 the validity of given arguments, and so on. This task can be greatly
269 simplified by taking advantage of the module @code{(ice-9 getopt-long)},
270 which is distributed with Guile, @xref{getopt-long}.
273 @node Scripting Examples
274 @subsection Scripting Examples
276 To start with, here are some examples of invoking Guile directly:
281 Run Guile interactively; @code{(command-line)} will return @*
282 @code{("/usr/local/bin/guile" "a" "b" "c")}.
284 @item guile -s /u/jimb/ex2 a b c
285 Load the file @file{/u/jimb/ex2}; @code{(command-line)} will return @*
286 @code{("/u/jimb/ex2" "a" "b" "c")}.
288 @item guile -c '(write %load-path) (newline)'
289 Write the value of the variable @code{%load-path}, print a newline,
292 @item guile -e main -s /u/jimb/ex4 foo
293 Load the file @file{/u/jimb/ex4}, and then call the function
294 @code{main}, passing it the list @code{("/u/jimb/ex4" "foo")}.
296 @item guile -l first -ds -l last -s script
297 Load the files @file{first}, @file{script}, and @file{last}, in that
298 order. The @code{-ds} switch says when to process the @code{-s}
299 switch. For a more motivated example, see the scripts below.
304 Here is a very simple Guile script:
306 #!/usr/local/bin/guile -s
308 (display "Hello, world!")
311 The first line marks the file as a Guile script. When the user invokes
312 it, the system runs @file{/usr/local/bin/guile} to interpret the script,
313 passing @code{-s}, the script's filename, and any arguments given to the
314 script as command-line arguments. When Guile sees @code{-s
315 @var{script}}, it loads @var{script}. Thus, running this program
321 Here is a script which prints the factorial of its argument:
323 #!/usr/local/bin/guile -s
327 (* n (fact (- n 1)))))
329 (display (fact (string->number (cadr (command-line)))))
339 However, suppose we want to use the definition of @code{fact} in this
340 file from another script. We can't simply @code{load} the script file,
341 and then use @code{fact}'s definition, because the script will try to
342 compute and display a factorial when we load it. To avoid this problem,
343 we might write the script this way:
346 #!/usr/local/bin/guile \
351 (* n (fact (- n 1)))))
354 (display (fact (string->number (cadr args))))
357 This version packages the actions the script should perform in a
358 function, @code{main}. This allows us to load the file purely for its
359 definitions, without any extraneous computation taking place. Then we
360 used the meta switch @code{\} and the entry point switch @code{-e} to
361 tell Guile to call @code{main} after loading the script.
364 30414093201713378043612608166064768844377641568960512000000000000
367 Suppose that we now want to write a script which computes the
368 @code{choose} function: given a set of @var{m} distinct objects,
369 @code{(choose @var{n} @var{m})} is the number of distinct subsets
370 containing @var{n} objects each. It's easy to write @code{choose} given
371 @code{fact}, so we might write the script this way:
373 #!/usr/local/bin/guile \
377 (/ (fact m) (* (fact (- m n)) (fact n))))
380 (let ((n (string->number (cadr args)))
381 (m (string->number (caddr args))))
382 (display (choose n m))
386 The command-line arguments here tell Guile to first load the file
387 @file{fact}, and then run the script, with @code{main} as the entry
388 point. In other words, the @code{choose} script can use definitions
389 made in the @code{fact} script. Here are some sample runs:
402 100891344545564193334812497256
407 @c TeX-master: "guile.texi"