Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
6f06e8d3 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2010, 2011 |
07d83abe MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
07d83abe MV |
7 | @node Guile Scripting |
8 | @section Guile Scripting | |
9 | ||
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. | |
14 | ||
15 | @menu | |
16 | * The Top of a Script File:: How to start a Guile script. | |
07d83abe MV |
17 | * The Meta Switch:: Passing complex argument lists to Guile |
18 | from shell scripts. | |
19 | * Command Line Handling:: Accessing the command line from a script. | |
20 | * Scripting Examples:: | |
21 | @end menu | |
22 | ||
23 | ||
24 | @node The Top of a Script File | |
25 | @subsection The Top of a Script File | |
26 | ||
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: | |
30 | ||
31 | @itemize @bullet | |
32 | ||
33 | @item | |
34 | The first two characters of the file must be @samp{#!}. | |
35 | ||
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 | |
41 | shell scripts.) | |
42 | ||
43 | @item | |
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}. | |
47 | ||
48 | @item | |
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 | |
53 | Switch}. | |
54 | ||
55 | @item | |
56 | Follow this with a newline. | |
57 | ||
58 | @item | |
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. | |
63 | ||
8748ffea MG |
64 | @item |
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}. | |
69 | ||
07d83abe MV |
70 | @item |
71 | The rest of the file should be a Scheme program. | |
72 | ||
73 | @end itemize | |
74 | ||
75 | Guile reads the program, evaluating expressions in the order that they | |
76 | appear. Upon reaching the end of the file, Guile exits. | |
77 | ||
07d83abe MV |
78 | @node The Meta Switch |
79 | @subsection The Meta Switch | |
80 | ||
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 | |
86 | starting like this: | |
87 | @example | |
88 | #!/usr/local/bin/guile -e main -s | |
89 | !# | |
90 | (define (main args) | |
91 | (map (lambda (arg) (display arg) (display " ")) | |
92 | (cdr args)) | |
93 | (newline)) | |
94 | @end example | |
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. | |
99 | ||
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. | |
106 | ||
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. | |
112 | ||
113 | Thus, consider a script named @file{/u/jimb/ekko} which starts like this: | |
114 | @example | |
115 | #!/usr/local/bin/guile \ | |
116 | -e main -s | |
117 | !# | |
118 | (define (main args) | |
119 | (map (lambda (arg) (display arg) (display " ")) | |
120 | (cdr args)) | |
121 | (newline)) | |
122 | @end example | |
123 | ||
124 | Suppose a user invokes this script as follows: | |
125 | @example | |
126 | $ /u/jimb/ekko a b c | |
127 | @end example | |
128 | ||
129 | Here's what happens: | |
130 | @itemize @bullet | |
131 | ||
132 | @item | |
133 | the operating system recognizes the @samp{#!} token at the top of the | |
134 | file, and rewrites the command line to: | |
135 | @example | |
136 | /usr/local/bin/guile \ /u/jimb/ekko a b c | |
137 | @end example | |
138 | This is the usual behavior, prescribed by POSIX. | |
139 | ||
140 | @item | |
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: | |
145 | @example | |
146 | /usr/local/bin/guile -e main -s /u/jimb/ekko a b c | |
147 | @end example | |
148 | ||
149 | @item | |
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")}. | |
153 | ||
154 | @end itemize | |
155 | ||
156 | ||
157 | When Guile sees the meta switch @code{\}, it parses command-line | |
158 | argument from the script file according to the following rules: | |
159 | @itemize @bullet | |
160 | ||
161 | @item | |
162 | Each space character terminates an argument. This means that two | |
163 | spaces in a row introduce an argument @code{""}. | |
164 | ||
165 | @item | |
166 | The tab character is not permitted (unless you quote it with the | |
167 | backslash character, as described below), to avoid confusion. | |
168 | ||
169 | @item | |
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.) | |
174 | ||
175 | @item | |
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. | |
184 | ||
185 | @end itemize | |
186 | ||
187 | ||
188 | @node Command Line Handling | |
189 | @subsection Command Line Handling | |
190 | ||
191 | @c This section was written and contributed by Martin Grabmueller. | |
192 | ||
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 | |
199 | arguments. | |
200 | ||
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. | |
204 | ||
205 | For example, if the script | |
206 | ||
207 | @example | |
208 | #! /usr/local/bin/guile -s | |
209 | !# | |
210 | (write (command-line)) | |
211 | (newline) | |
212 | @end example | |
213 | ||
214 | @noindent | |
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 | |
217 | is | |
218 | ||
219 | @example | |
220 | ("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob") | |
221 | @end example | |
222 | ||
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: | |
229 | ||
230 | @example | |
231 | #! /usr/local/bin/guile \ | |
232 | -e main -s | |
233 | !# | |
234 | (define (main args) | |
235 | (write args) | |
236 | (newline)) | |
237 | @end example | |
238 | ||
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}.) | |
241 | ||
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 | |
246 | full, as in: | |
247 | ||
248 | @example | |
249 | $ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob | |
250 | @end example | |
251 | ||
252 | @noindent | |
253 | or | |
254 | ||
255 | @example | |
256 | $ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob | |
257 | @end example | |
258 | ||
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. | |
264 | ||
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}. | |
271 | ||
272 | ||
273 | @node Scripting Examples | |
274 | @subsection Scripting Examples | |
275 | ||
276 | To start with, here are some examples of invoking Guile directly: | |
277 | ||
278 | @table @code | |
279 | ||
280 | @item guile -- a b c | |
281 | Run Guile interactively; @code{(command-line)} will return @* | |
282 | @code{("/usr/local/bin/guile" "a" "b" "c")}. | |
283 | ||
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")}. | |
287 | ||
288 | @item guile -c '(write %load-path) (newline)' | |
289 | Write the value of the variable @code{%load-path}, print a newline, | |
290 | and exit. | |
291 | ||
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")}. | |
295 | ||
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. | |
300 | ||
301 | @end table | |
302 | ||
303 | ||
304 | Here is a very simple Guile script: | |
305 | @example | |
306 | #!/usr/local/bin/guile -s | |
307 | !# | |
308 | (display "Hello, world!") | |
309 | (newline) | |
310 | @end example | |
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 | |
316 | produces the output: | |
317 | @example | |
318 | Hello, world! | |
319 | @end example | |
320 | ||
321 | Here is a script which prints the factorial of its argument: | |
322 | @example | |
323 | #!/usr/local/bin/guile -s | |
324 | !# | |
325 | (define (fact n) | |
326 | (if (zero? n) 1 | |
327 | (* n (fact (- n 1))))) | |
328 | ||
329 | (display (fact (string->number (cadr (command-line))))) | |
330 | (newline) | |
331 | @end example | |
332 | In action: | |
333 | @example | |
e03d9636 | 334 | $ ./fact 5 |
07d83abe MV |
335 | 120 |
336 | $ | |
337 | @end example | |
338 | ||
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: | |
344 | ||
345 | @example | |
346 | #!/usr/local/bin/guile \ | |
347 | -e main -s | |
348 | !# | |
349 | (define (fact n) | |
350 | (if (zero? n) 1 | |
351 | (* n (fact (- n 1))))) | |
352 | ||
353 | (define (main args) | |
354 | (display (fact (string->number (cadr args)))) | |
355 | (newline)) | |
356 | @end example | |
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. | |
362 | @example | |
e03d9636 | 363 | $ ./fact 50 |
07d83abe MV |
364 | 30414093201713378043612608166064768844377641568960512000000000000 |
365 | @end example | |
366 | ||
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: | |
372 | @example | |
373 | #!/usr/local/bin/guile \ | |
374 | -l fact -e main -s | |
375 | !# | |
376 | (define (choose n m) | |
377 | (/ (fact m) (* (fact (- m n)) (fact n)))) | |
378 | ||
379 | (define (main args) | |
380 | (let ((n (string->number (cadr args))) | |
381 | (m (string->number (caddr args)))) | |
382 | (display (choose n m)) | |
383 | (newline))) | |
384 | @end example | |
385 | ||
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: | |
390 | @example | |
e03d9636 | 391 | $ ./choose 0 4 |
07d83abe | 392 | 1 |
e03d9636 | 393 | $ ./choose 1 4 |
07d83abe | 394 | 4 |
e03d9636 | 395 | $ ./choose 2 4 |
07d83abe | 396 | 6 |
e03d9636 | 397 | $ ./choose 3 4 |
07d83abe | 398 | 4 |
e03d9636 | 399 | $ ./choose 4 4 |
07d83abe | 400 | 1 |
e03d9636 | 401 | $ ./choose 50 100 |
07d83abe MV |
402 | 100891344545564193334812497256 |
403 | @end example | |
404 | ||
44fd0a72 KR |
405 | |
406 | @c Local Variables: | |
407 | @c TeX-master: "guile.texi" | |
408 | @c End: |