Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 | |
4 | @c Free Software Foundation, Inc. | |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
a0e07ba4 NJ |
7 | @page |
8 | @node Command Line Handling | |
9 | @chapter Handling Command Line Options and Arguments | |
10 | ||
11 | @c This chapter was written and contributed by Martin Grabmueller. | |
12 | ||
13 | The ability to accept and handle command line arguments is very | |
14 | important when writing Guile scripts to solve particular problems, such | |
15 | as extracting information from text files or interfacing with existing | |
16 | command line applications. This chapter describes how Guile makes | |
17 | command line arguments available to a Guile script, and the utilities | |
18 | that Guile provides to help with the processing of command line | |
19 | arguments. | |
20 | ||
21 | @menu | |
22 | * Command Line Args:: Using command line arguments. | |
23 | * getopt-long:: The (ice-9 getopt-long) module. | |
24 | @end menu | |
25 | ||
26 | ||
27 | @node Command Line Args | |
28 | @section Using Command Line Arguments | |
29 | ||
30 | When a Guile script is invoked, Guile makes the command line arguments | |
31 | accessible via the procedure @code{command-line}, which returns the | |
32 | arguments as a list of strings. | |
33 | ||
34 | For example, if the script | |
35 | ||
36 | @example | |
37 | #! /usr/local/bin/guile -s | |
38 | !# | |
39 | (write (command-line)) | |
40 | (newline) | |
41 | @end example | |
42 | ||
43 | @noindent | |
44 | is saved in a file @file{cmdline-test.scm} and invoked using the command | |
45 | line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}, the output | |
46 | is | |
47 | ||
48 | @example | |
49 | ("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob") | |
50 | @end example | |
51 | ||
52 | If the script invocation includes a @code{-e} option, specifying a | |
53 | procedure to call after loading the script, Guile will call that | |
54 | procedure with @code{(command-line)} as its argument. So a script that | |
55 | uses @code{-e} doesn't need to refer explicitly to @code{command-line} | |
56 | in its code. For example, the script above would have identical | |
57 | behaviour if it was written instead like this: | |
58 | ||
59 | @example | |
60 | #! /usr/local/bin/guile \ | |
61 | -e main -s | |
62 | !# | |
63 | (define (main args) | |
64 | (write args) | |
65 | (newline)) | |
66 | @end example | |
67 | ||
68 | (Note the use of the meta switch @code{\} so that the script invocation | |
69 | can include more than one Guile option: @xref{The Meta Switch}.) | |
70 | ||
71 | These scripts use the @code{#!} POSIX convention so that they can be | |
72 | executed using their own file names directly, as in the example command | |
73 | line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}. But they | |
74 | can also be executed by typing out the implied Guile command line in | |
75 | full, as in: | |
76 | ||
77 | @example | |
78 | $ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob | |
79 | @end example | |
80 | ||
81 | @noindent | |
82 | or | |
83 | ||
84 | @example | |
85 | $ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob | |
86 | @end example | |
87 | ||
88 | Even when a script is invoked using this longer form, the arguments that | |
89 | the script receives are the same as if it had been invoked using the | |
90 | short form. Guile ensures that the @code{(command-line)} or @code{-e} | |
91 | arguments are independent of how the script is invoked, by stripping off | |
92 | the arguments that Guile itself processes. | |
93 | ||
94 | ||
95 | @node getopt-long | |
96 | @section The (ice-9 getopt-long) Module | |
97 | ||
98 | A script is free to parse and handle its command line arguments in any | |
99 | way that it chooses. Where the set of possible options and arguments is | |
100 | complex, however, it can get tricky to extract all the options, check | |
101 | the validity of given arguments, and so on. This task can be greatly | |
102 | simplified by taking advantage of the module @code{(ice-9 getopt-long)}, | |
103 | which is distributed with Guile. | |
104 | ||
105 | The @code{(ice-9 getopt-long)} module exports two procedures: | |
106 | @code{getopt-long} and @code{option-ref}. | |
107 | ||
108 | @itemize @bullet | |
109 | @item | |
110 | @code{getopt-long} takes a list of strings --- the command line | |
111 | arguments --- and an @dfn{option specification}. It parses the command | |
112 | line arguments according to the option specification and returns a data | |
113 | structure that encapsulates the results of the parsing. | |
114 | ||
115 | @item | |
116 | @code{option-ref} then takes the parsed data structure and a specific | |
117 | option's name, and returns information about that option in particular. | |
118 | @end itemize | |
119 | ||
120 | To make these procedures available to your Guile script, include the | |
121 | expression @code{(use-modules (ice-9 getopt-long))} somewhere near the | |
122 | top, before the first usage of @code{getopt-long} or @code{option-ref}. | |
123 | ||
124 | @menu | |
125 | * getopt-long Example:: A short getopt-long example. | |
126 | * Option Specification:: How to write an option specification. | |
127 | * Command Line Format:: The expected command line format. | |
128 | * getopt-long Reference:: Full documentation for @code{getopt-long}. | |
129 | * option-ref Reference:: Full documentation for @code{option-ref}. | |
130 | @end menu | |
131 | ||
132 | ||
133 | @node getopt-long Example | |
134 | @subsection A Short getopt-long Example | |
135 | ||
136 | This subsection illustrates how @code{getopt-long} is used by presenting | |
137 | and dissecting a simple example. The first thing that we need is an | |
138 | @dfn{option specification} that tells @code{getopt-long} how to parse | |
139 | the command line. This specification is an association list with the | |
140 | long option name as the key. Here is how such a specification might | |
141 | look: | |
142 | ||
143 | @lisp | |
144 | (define option-spec | |
145 | '((version (single-char #\v) (value #f)) | |
146 | (help (single-char #\h) (value #f)))) | |
147 | @end lisp | |
148 | ||
149 | This alist tells @code{getopt-long} that it should accept two long | |
150 | options, called @emph{version} and @emph{help}, and that these options | |
151 | can also be selected by the single-letter abbreviations @emph{v} and | |
152 | @emph{h}, respectively. The @code{(value #f)} clauses indicate that | |
153 | neither of the options accepts a value. | |
154 | ||
155 | With this specification we can use @code{getopt-long} to parse a given | |
156 | command line: | |
157 | ||
158 | @lisp | |
159 | (define options (getopt-long (command-line) option-spec)) | |
160 | @end lisp | |
161 | ||
162 | After this call, @code{options} contains the parsed command line and is | |
163 | ready to be examined by @code{option-ref}. @code{option-ref} is called | |
164 | like this: | |
165 | ||
166 | @lisp | |
167 | (option-ref options 'help #f) | |
168 | @end lisp | |
169 | ||
170 | @noindent | |
171 | It expects the parsed command line, a symbol indicating the option to | |
172 | examine, and a default value. The default value is returned if the | |
173 | option was not present in the command line, or if the option was present | |
174 | but without a value; otherwise the value from the command line is | |
175 | returned. Usually @code{option-ref} is called once for each possible | |
176 | option that a script supports. | |
177 | ||
178 | The following example shows a main program which puts all this together | |
179 | to parse its command line and figure out what the user wanted. | |
180 | ||
181 | @lisp | |
182 | (define (main args) | |
183 | (let* ((option-spec '((version (single-char #\v) (value #f)) | |
184 | (help (single-char #\h) (value #f)))) | |
185 | (options (getopt-long args option-spec)) | |
186 | (help-wanted (option-ref options 'help #f)) | |
187 | (version-wanted (option-ref options 'version #f))) | |
188 | (if (or version-wanted help-wanted) | |
189 | (begin | |
190 | (if version-wanted | |
191 | (display "getopt-long-example version 0.3\n")) | |
192 | (if help-wanted | |
193 | (display "\ | |
194 | getopt-long-example [options] | |
195 | -v, --version Display version | |
196 | -h, --help Display this help | |
197 | "))) | |
198 | (begin | |
199 | (display "Hello, World!") (newline))))) | |
200 | @end lisp | |
201 | ||
202 | ||
203 | @node Option Specification | |
204 | @subsection How to Write an Option Specification | |
205 | ||
206 | An option specification is an association list (@pxref{Association | |
207 | Lists}) with one list element for each supported option. The key of each | |
208 | list element is a symbol that names the option, while the value is a | |
209 | list of option properties: | |
210 | ||
211 | @lisp | |
212 | OPTION-SPEC ::= '( (OPT-NAME1 (PROP-NAME PROP-VALUE) @dots{}) | |
213 | (OPT-NAME2 (PROP-NAME PROP-VALUE) @dots{}) | |
214 | (OPT-NAME3 (PROP-NAME PROP-VALUE) @dots{}) | |
215 | @dots{} | |
216 | ) | |
217 | @end lisp | |
218 | ||
219 | Each @var{opt-name} specifies the long option name for that option. For | |
220 | example, a list element with @var{opt-name} @code{background} specifies | |
221 | an option that can be specified on the command line using the long | |
222 | option @code{--background}. Further information about the option --- | |
223 | whether it takes a value, whether it is required to be present in the | |
224 | command line, and so on --- is specified by the option properties. | |
225 | ||
226 | In the example of the preceding subsection, we already saw that a long | |
227 | option name can have a equivalent @dfn{short option} character. The | |
228 | equivalent short option character can be set for an option by specifying | |
229 | a @code{single-char} property in that option's property list. For | |
230 | example, a list element like @code{'(output (single-char #\o) @dots{})} | |
231 | specifies an option with long name @code{--output} that can also be | |
232 | specified by the equivalent short name @code{-o}. | |
233 | ||
234 | The @code{value} property specifies whether an option requires or | |
235 | accepts a value. If the @code{value} property is set to @code{#t}, the | |
236 | option requires a value: @code{getopt-long} will signal an error if the | |
237 | option name is present without a corresponding value. If set to | |
238 | @code{#f}, the option does not take a value; in this case, a non-option | |
239 | word that follows the option name in the command line will be treated as | |
240 | a non-option argument. If set to the symbol @code{optional}, the option | |
241 | accepts a value but does not require one: a non-option word that follows | |
242 | the option name in the command line will be interpreted as that option's | |
243 | value. If the option name for an option with @code{'(value optional)} | |
244 | is immediately followed in the command line by @emph{another} option | |
245 | name, the value for the first option is implicitly @code{#t}. | |
246 | ||
247 | The @code{required?} property indicates whether an option is required to | |
248 | be present in the command line. If the @code{required?} property is | |
249 | set to @code{#t}, @code{getopt-long} will signal an error if the option | |
250 | is not specified. | |
251 | ||
252 | Finally, the @code{predicate} property can be used to constrain the | |
253 | possible values of an option. If used, the @code{predicate} property | |
254 | should be set to a procedure that takes one argument --- the proposed | |
255 | option value as a string --- and returns either @code{#t} or @code{#f} | |
256 | according as the proposed value is or is not acceptable. If the | |
257 | predicate procedure returns @code{#f}, @code{getopt-long} will signal an | |
258 | error. | |
259 | ||
260 | By default, options do not have single-character equivalents, are not | |
261 | required, and do not take values. Where the list element for an option | |
262 | includes a @code{value} property but no @code{predicate} property, the | |
263 | option values are unconstrained. | |
264 | ||
265 | ||
266 | @node Command Line Format | |
267 | @subsection Expected Command Line Format | |
268 | ||
269 | In order for @code{getopt-long} to correctly parse a command line, that | |
270 | command line must conform to a standard set of rules for how command | |
271 | line options are specified. This subsection explains what those rules | |
272 | are. | |
273 | ||
274 | @code{getopt-long} splits a given command line into several pieces. All | |
275 | elements of the argument list are classified to be either options or | |
276 | normal arguments. Options consist of two dashes and an option name | |
277 | (so-called @dfn{long} options), or of one dash followed by a single | |
278 | letter (@dfn{short} options). | |
279 | ||
280 | Options can behave as switches, when they are given without a value, or | |
281 | they can be used to pass a value to the program. The value for an | |
282 | option may be specified using an equals sign, or else is simply the next | |
283 | word in the command line, so the following two invocations are | |
284 | equivalent: | |
285 | ||
286 | @example | |
287 | $ ./foo.scm --output=bar.txt | |
288 | $ ./foo.scm --output bar.txt | |
289 | @end example | |
290 | ||
291 | Short options can be used instead of their long equivalents and can be | |
292 | grouped together after a single dash. For example, the following | |
293 | commands are equivalent. | |
294 | ||
295 | @example | |
296 | $ ./foo.scm --version --help | |
297 | $ ./foo.scm -v --help | |
298 | $ ./foo.scm -vh | |
299 | @end example | |
300 | ||
301 | If an option requires a value, it can only be grouped together with other | |
302 | short options if it is the last option in the group; the value is the | |
303 | next argument. So, for example, with the following option | |
304 | specification --- | |
305 | ||
306 | @lisp | |
307 | ((apples (single-char #\a)) | |
308 | (blimps (single-char #\b) (value #t)) | |
309 | (catalexis (single-char #\c) (value #t))) | |
310 | @end lisp | |
311 | ||
312 | @noindent | |
313 | --- the following command lines would all be acceptable: | |
314 | ||
315 | @example | |
316 | $ ./foo.scm -a -b bang -c couth | |
317 | $ ./foo.scm -ab bang -c couth | |
318 | $ ./foo.scm -ac couth -b bang | |
319 | @end example | |
320 | ||
321 | But the next command line is an error, because @code{-b} is not the last | |
322 | option in its combination, and because a group of short options cannot | |
323 | include two options that both require values: | |
324 | ||
325 | @example | |
326 | $ ./foo.scm -abc couth bang | |
327 | @end example | |
328 | ||
329 | If an option's value is optional, @code{getopt-long} decides whether the | |
330 | option has a value by looking at what follows it in the argument list. | |
331 | If the next element is a string, and it does not appear to be an option | |
332 | itself, then that string is the option's value. | |
333 | ||
334 | If the option @code{--} appears in the argument list, argument parsing | |
335 | stops there and subsequent arguments are returned as ordinary arguments, | |
336 | even if they resemble options. So, with the command line | |
337 | ||
338 | @example | |
339 | $ ./foo.scm --apples "Granny Smith" -- --blimp Goodyear | |
340 | @end example | |
341 | ||
342 | @noindent | |
343 | @code{getopt-long} will recognize the @code{--apples} option as having | |
344 | the value "Granny Smith", but will not treat @code{--blimp} as an | |
345 | option. The strings @code{--blimp} and @code{Goodyear} will be returned | |
346 | as ordinary argument strings. | |
347 | ||
348 | ||
349 | @node getopt-long Reference | |
350 | @subsection Reference Documentation for @code{getopt-long} | |
351 | ||
8f85c0c6 | 352 | @deffn {Scheme Procedure} getopt-long args grammar |
a0e07ba4 NJ |
353 | Parse the command line given in @var{args} (which must be a list of |
354 | strings) according to the option specification @var{grammar}. | |
355 | ||
356 | The @var{grammar} argument is expected to be a list of this form: | |
357 | ||
358 | @code{((@var{option} (@var{property} @var{value}) @dots{}) @dots{})} | |
359 | ||
360 | where each @var{option} is a symbol denoting the long option, but | |
361 | without the two leading dashes (e.g. @code{version} if the option is | |
362 | called @code{--version}). | |
363 | ||
364 | For each option, there may be list of arbitrarily many property/value | |
365 | pairs. The order of the pairs is not important, but every property may | |
366 | only appear once in the property list. The following table lists the | |
367 | possible properties: | |
368 | ||
369 | @table @asis | |
370 | @item @code{(single-char @var{char})} | |
371 | Accept @code{-@var{char}} as a single-character equivalent to | |
372 | @code{--@var{option}}. This is how to specify traditional Unix-style | |
373 | flags. | |
374 | @item @code{(required? @var{bool})} | |
375 | If @var{bool} is true, the option is required. @code{getopt-long} will | |
376 | raise an error if it is not found in @var{args}. | |
377 | @item @code{(value @var{bool})} | |
378 | If @var{bool} is @code{#t}, the option accepts a value; if it is | |
379 | @code{#f}, it does not; and if it is the symbol @code{optional}, the | |
380 | option may appear in @var{args} with or without a value. | |
381 | @item @code{(predicate @var{func})} | |
382 | If the option accepts a value (i.e. you specified @code{(value #t)} for | |
383 | this option), then @code{getopt-long} will apply @var{func} to the | |
384 | value, and throw an exception if it returns @code{#f}. @var{func} | |
385 | should be a procedure which accepts a string and returns a boolean | |
386 | value; you may need to use quasiquotes to get it into @var{grammar}. | |
387 | @end table | |
388 | @end deffn | |
389 | ||
390 | @code{getopt-long}'s @var{args} parameter is expected to be a list of | |
391 | strings like the one returned by @code{command-line}, with the first | |
392 | element being the name of the command. Therefore @code{getopt-long} | |
393 | ignores the first element in @var{args} and starts argument | |
394 | interpretation with the second element. | |
395 | ||
396 | @code{getopt-long} signals an error if any of the following conditions | |
397 | hold. | |
398 | ||
399 | @itemize @bullet | |
400 | @item | |
401 | The option grammar has an invalid syntax. | |
402 | ||
403 | @item | |
404 | One of the options in the argument list was not specified by the | |
405 | grammar. | |
406 | ||
407 | @item | |
408 | A required option is omitted. | |
409 | ||
410 | @item | |
411 | An option which requires an argument did not get one. | |
412 | ||
413 | @item | |
414 | An option that doesn't accept an argument does get one (this can only | |
415 | happen using the long option @code{--opt=@var{value}} syntax). | |
416 | ||
417 | @item | |
418 | An option predicate fails. | |
419 | @end itemize | |
420 | ||
421 | ||
422 | @node option-ref Reference | |
423 | @subsection Reference Documentation for @code{option-ref} | |
424 | ||
8f85c0c6 | 425 | @deffn {Scheme Procedure} option-ref options key default |
a0e07ba4 NJ |
426 | Search @var{options} for a command line option named @var{key} and |
427 | return its value, if found. If the option has no value, but was given, | |
428 | return @code{#t}. If the option was not given, return @var{default}. | |
429 | @var{options} must be the result of a call to @code{getopt-long}. | |
430 | @end deffn | |
431 | ||
432 | @code{option-ref} always succeeds, either by returning the requested | |
433 | option value from the command line, or the default value. | |
434 | ||
435 | The special key @code{'()} can be used to get a list of all | |
436 | non-option arguments. | |
437 | ||
438 | ||
439 | @c Local Variables: | |
440 | @c TeX-master: "guile.texi" | |
441 | @c End: |