Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
44fd0a72 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005 |
07d83abe MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
7 | @page | |
8 | @node Guile Scripting | |
9 | @section Guile Scripting | |
10 | ||
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. | |
15 | ||
16 | @menu | |
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 | |
20 | from shell scripts. | |
21 | * Command Line Handling:: Accessing the command line from a script. | |
22 | * Scripting Examples:: | |
23 | @end menu | |
24 | ||
25 | ||
26 | @node The Top of a Script File | |
27 | @subsection The Top of a Script File | |
28 | ||
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: | |
32 | ||
33 | @itemize @bullet | |
34 | ||
35 | @item | |
36 | The first two characters of the file must be @samp{#!}. | |
37 | ||
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 | |
43 | shell scripts.) | |
44 | ||
45 | @item | |
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}. | |
49 | ||
50 | @item | |
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 | |
55 | Switch}. | |
56 | ||
57 | @item | |
58 | Follow this with a newline. | |
59 | ||
60 | @item | |
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. | |
65 | ||
8748ffea MG |
66 | @item |
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}. | |
71 | ||
07d83abe MV |
72 | @item |
73 | The rest of the file should be a Scheme program. | |
74 | ||
75 | @end itemize | |
76 | ||
77 | Guile reads the program, evaluating expressions in the order that they | |
78 | appear. Upon reaching the end of the file, Guile exits. | |
79 | ||
80 | ||
81 | @node Invoking Guile | |
82 | @subsection Invoking Guile | |
44fd0a72 | 83 | @cindex invocation |
07d83abe MV |
84 | |
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}. | |
88 | ||
89 | @table @code | |
90 | ||
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...})}. | |
97 | ||
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 | |
103 | Guile executable. | |
104 | ||
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 | |
111 | Guile executable. | |
112 | ||
fcb8ba8c MV |
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. | |
119 | ||
07d83abe MV |
120 | @item -l @var{file} |
121 | Load Scheme source code from @var{file}, and continue processing the | |
122 | command line. | |
123 | ||
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. | |
130 | ||
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. | |
135 | ||
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}. | |
140 | ||
e70c841f MV |
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 | corresponf to the @code{(@@ ...)} read syntax that can be used in | |
148 | normal code, @xref{Using Guile Modules}. | |
149 | ||
07d83abe MV |
150 | @xref{Scripting Examples}. |
151 | ||
152 | @item -ds | |
153 | Treat a final @code{-s} option as if it occurred at this point in the | |
154 | command line; load the script here. | |
155 | ||
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 | |
160 | Examples}. | |
161 | ||
162 | @item \ | |
163 | Read more command-line arguments, starting from the second line of the | |
164 | script file. @xref{The Meta Switch}. | |
165 | ||
166 | @item --emacs | |
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}. | |
170 | ||
171 | This switch is still experimental. | |
172 | ||
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. | |
179 | ||
180 | @example | |
181 | guile --use-srfi=8,13 | |
182 | @end example | |
183 | ||
184 | @item --debug | |
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. | |
190 | ||
191 | @vnew{1.8} | |
192 | @item --no-debug | |
193 | Do not use the debugging evaluator, even when entering an interactive | |
194 | session. | |
195 | ||
196 | @item -h@r{, }--help | |
197 | Display help on invoking Guile, and then exit. | |
198 | ||
199 | @item -v@r{, }--version | |
200 | Display the current version of Guile, and then exit. | |
201 | ||
202 | @end table | |
203 | ||
204 | ||
205 | @node The Meta Switch | |
206 | @subsection The Meta Switch | |
207 | ||
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 | |
213 | starting like this: | |
214 | @example | |
215 | #!/usr/local/bin/guile -e main -s | |
216 | !# | |
217 | (define (main args) | |
218 | (map (lambda (arg) (display arg) (display " ")) | |
219 | (cdr args)) | |
220 | (newline)) | |
221 | @end example | |
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. | |
226 | ||
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. | |
233 | ||
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. | |
239 | ||
240 | Thus, consider a script named @file{/u/jimb/ekko} which starts like this: | |
241 | @example | |
242 | #!/usr/local/bin/guile \ | |
243 | -e main -s | |
244 | !# | |
245 | (define (main args) | |
246 | (map (lambda (arg) (display arg) (display " ")) | |
247 | (cdr args)) | |
248 | (newline)) | |
249 | @end example | |
250 | ||
251 | Suppose a user invokes this script as follows: | |
252 | @example | |
253 | $ /u/jimb/ekko a b c | |
254 | @end example | |
255 | ||
256 | Here's what happens: | |
257 | @itemize @bullet | |
258 | ||
259 | @item | |
260 | the operating system recognizes the @samp{#!} token at the top of the | |
261 | file, and rewrites the command line to: | |
262 | @example | |
263 | /usr/local/bin/guile \ /u/jimb/ekko a b c | |
264 | @end example | |
265 | This is the usual behavior, prescribed by POSIX. | |
266 | ||
267 | @item | |
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: | |
272 | @example | |
273 | /usr/local/bin/guile -e main -s /u/jimb/ekko a b c | |
274 | @end example | |
275 | ||
276 | @item | |
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")}. | |
280 | ||
281 | @end itemize | |
282 | ||
283 | ||
284 | When Guile sees the meta switch @code{\}, it parses command-line | |
285 | argument from the script file according to the following rules: | |
286 | @itemize @bullet | |
287 | ||
288 | @item | |
289 | Each space character terminates an argument. This means that two | |
290 | spaces in a row introduce an argument @code{""}. | |
291 | ||
292 | @item | |
293 | The tab character is not permitted (unless you quote it with the | |
294 | backslash character, as described below), to avoid confusion. | |
295 | ||
296 | @item | |
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.) | |
301 | ||
302 | @item | |
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. | |
311 | ||
312 | @end itemize | |
313 | ||
314 | ||
315 | @node Command Line Handling | |
316 | @subsection Command Line Handling | |
317 | ||
318 | @c This section was written and contributed by Martin Grabmueller. | |
319 | ||
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 | |
326 | arguments. | |
327 | ||
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. | |
331 | ||
332 | For example, if the script | |
333 | ||
334 | @example | |
335 | #! /usr/local/bin/guile -s | |
336 | !# | |
337 | (write (command-line)) | |
338 | (newline) | |
339 | @end example | |
340 | ||
341 | @noindent | |
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 | |
344 | is | |
345 | ||
346 | @example | |
347 | ("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob") | |
348 | @end example | |
349 | ||
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: | |
356 | ||
357 | @example | |
358 | #! /usr/local/bin/guile \ | |
359 | -e main -s | |
360 | !# | |
361 | (define (main args) | |
362 | (write args) | |
363 | (newline)) | |
364 | @end example | |
365 | ||
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}.) | |
368 | ||
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 | |
373 | full, as in: | |
374 | ||
375 | @example | |
376 | $ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob | |
377 | @end example | |
378 | ||
379 | @noindent | |
380 | or | |
381 | ||
382 | @example | |
383 | $ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob | |
384 | @end example | |
385 | ||
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. | |
391 | ||
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}. | |
398 | ||
399 | ||
400 | @node Scripting Examples | |
401 | @subsection Scripting Examples | |
402 | ||
403 | To start with, here are some examples of invoking Guile directly: | |
404 | ||
405 | @table @code | |
406 | ||
407 | @item guile -- a b c | |
408 | Run Guile interactively; @code{(command-line)} will return @* | |
409 | @code{("/usr/local/bin/guile" "a" "b" "c")}. | |
410 | ||
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")}. | |
414 | ||
415 | @item guile -c '(write %load-path) (newline)' | |
416 | Write the value of the variable @code{%load-path}, print a newline, | |
417 | and exit. | |
418 | ||
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")}. | |
422 | ||
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. | |
427 | ||
428 | @end table | |
429 | ||
430 | ||
431 | Here is a very simple Guile script: | |
432 | @example | |
433 | #!/usr/local/bin/guile -s | |
434 | !# | |
435 | (display "Hello, world!") | |
436 | (newline) | |
437 | @end example | |
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 | |
443 | produces the output: | |
444 | @example | |
445 | Hello, world! | |
446 | @end example | |
447 | ||
448 | Here is a script which prints the factorial of its argument: | |
449 | @example | |
450 | #!/usr/local/bin/guile -s | |
451 | !# | |
452 | (define (fact n) | |
453 | (if (zero? n) 1 | |
454 | (* n (fact (- n 1))))) | |
455 | ||
456 | (display (fact (string->number (cadr (command-line))))) | |
457 | (newline) | |
458 | @end example | |
459 | In action: | |
460 | @example | |
461 | $ fact 5 | |
462 | 120 | |
463 | $ | |
464 | @end example | |
465 | ||
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: | |
471 | ||
472 | @example | |
473 | #!/usr/local/bin/guile \ | |
474 | -e main -s | |
475 | !# | |
476 | (define (fact n) | |
477 | (if (zero? n) 1 | |
478 | (* n (fact (- n 1))))) | |
479 | ||
480 | (define (main args) | |
481 | (display (fact (string->number (cadr args)))) | |
482 | (newline)) | |
483 | @end example | |
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. | |
489 | @example | |
490 | $ fact 50 | |
491 | 30414093201713378043612608166064768844377641568960512000000000000 | |
492 | @end example | |
493 | ||
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: | |
499 | @example | |
500 | #!/usr/local/bin/guile \ | |
501 | -l fact -e main -s | |
502 | !# | |
503 | (define (choose n m) | |
504 | (/ (fact m) (* (fact (- m n)) (fact n)))) | |
505 | ||
506 | (define (main args) | |
507 | (let ((n (string->number (cadr args))) | |
508 | (m (string->number (caddr args)))) | |
509 | (display (choose n m)) | |
510 | (newline))) | |
511 | @end example | |
512 | ||
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: | |
517 | @example | |
518 | $ choose 0 4 | |
519 | 1 | |
520 | $ choose 1 4 | |
521 | 4 | |
522 | $ choose 2 4 | |
523 | 6 | |
524 | $ choose 3 4 | |
525 | 4 | |
526 | $ choose 4 4 | |
527 | 1 | |
528 | $ choose 50 100 | |
529 | 100891344545564193334812497256 | |
530 | @end example | |
531 | ||
44fd0a72 KR |
532 | |
533 | @c Local Variables: | |
534 | @c TeX-master: "guile.texi" | |
535 | @c End: |