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