Commit | Line | Data |
---|---|---|
3229f68b MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
b8b06598 | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011 |
3229f68b MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
7 | @node getopt-long | |
8 | @section The (ice-9 getopt-long) Module | |
9 | ||
10 | The @code{(ice-9 getopt-long)} module exports two procedures: | |
11 | @code{getopt-long} and @code{option-ref}. | |
12 | ||
13 | @itemize @bullet | |
14 | @item | |
15 | @code{getopt-long} takes a list of strings --- the command line | |
c382f589 NJ |
16 | arguments --- an @dfn{option specification}, and some optional keyword |
17 | parameters. It parses the command line arguments according to the | |
18 | option specification and keyword parameters, and returns a data | |
3229f68b MV |
19 | structure that encapsulates the results of the parsing. |
20 | ||
21 | @item | |
22 | @code{option-ref} then takes the parsed data structure and a specific | |
23 | option's name, and returns information about that option in particular. | |
24 | @end itemize | |
25 | ||
26 | To make these procedures available to your Guile script, include the | |
27 | expression @code{(use-modules (ice-9 getopt-long))} somewhere near the | |
28 | top, before the first usage of @code{getopt-long} or @code{option-ref}. | |
29 | ||
30 | @menu | |
31 | * getopt-long Example:: A short getopt-long example. | |
32 | * Option Specification:: How to write an option specification. | |
33 | * Command Line Format:: The expected command line format. | |
34 | * getopt-long Reference:: Full documentation for @code{getopt-long}. | |
35 | * option-ref Reference:: Full documentation for @code{option-ref}. | |
36 | @end menu | |
37 | ||
38 | ||
39 | @node getopt-long Example | |
40 | @subsection A Short getopt-long Example | |
41 | ||
42 | This section illustrates how @code{getopt-long} is used by presenting | |
43 | and dissecting a simple example. The first thing that we need is an | |
44 | @dfn{option specification} that tells @code{getopt-long} how to parse | |
45 | the command line. This specification is an association list with the | |
46 | long option name as the key. Here is how such a specification might | |
47 | look: | |
48 | ||
49 | @lisp | |
50 | (define option-spec | |
51 | '((version (single-char #\v) (value #f)) | |
52 | (help (single-char #\h) (value #f)))) | |
53 | @end lisp | |
54 | ||
55 | This alist tells @code{getopt-long} that it should accept two long | |
56 | options, called @emph{version} and @emph{help}, and that these options | |
57 | can also be selected by the single-letter abbreviations @emph{v} and | |
58 | @emph{h}, respectively. The @code{(value #f)} clauses indicate that | |
59 | neither of the options accepts a value. | |
60 | ||
61 | With this specification we can use @code{getopt-long} to parse a given | |
62 | command line: | |
63 | ||
64 | @lisp | |
65 | (define options (getopt-long (command-line) option-spec)) | |
66 | @end lisp | |
67 | ||
68 | After this call, @code{options} contains the parsed command line and is | |
69 | ready to be examined by @code{option-ref}. @code{option-ref} is called | |
70 | like this: | |
71 | ||
72 | @lisp | |
73 | (option-ref options 'help #f) | |
74 | @end lisp | |
75 | ||
76 | @noindent | |
77 | It expects the parsed command line, a symbol indicating the option to | |
78 | examine, and a default value. The default value is returned if the | |
79 | option was not present in the command line, or if the option was present | |
80 | but without a value; otherwise the value from the command line is | |
81 | returned. Usually @code{option-ref} is called once for each possible | |
82 | option that a script supports. | |
83 | ||
84 | The following example shows a main program which puts all this together | |
85 | to parse its command line and figure out what the user wanted. | |
86 | ||
87 | @lisp | |
88 | (define (main args) | |
89 | (let* ((option-spec '((version (single-char #\v) (value #f)) | |
90 | (help (single-char #\h) (value #f)))) | |
91 | (options (getopt-long args option-spec)) | |
92 | (help-wanted (option-ref options 'help #f)) | |
93 | (version-wanted (option-ref options 'version #f))) | |
94 | (if (or version-wanted help-wanted) | |
95 | (begin | |
96 | (if version-wanted | |
97 | (display "getopt-long-example version 0.3\n")) | |
98 | (if help-wanted | |
99 | (display "\ | |
100 | getopt-long-example [options] | |
101 | -v, --version Display version | |
102 | -h, --help Display this help | |
103 | "))) | |
104 | (begin | |
105 | (display "Hello, World!") (newline))))) | |
106 | @end lisp | |
107 | ||
108 | ||
109 | @node Option Specification | |
110 | @subsection How to Write an Option Specification | |
111 | ||
112 | An option specification is an association list (@pxref{Association | |
113 | Lists}) with one list element for each supported option. The key of each | |
114 | list element is a symbol that names the option, while the value is a | |
115 | list of option properties: | |
116 | ||
117 | @lisp | |
118 | OPTION-SPEC ::= '( (OPT-NAME1 (PROP-NAME PROP-VALUE) @dots{}) | |
119 | (OPT-NAME2 (PROP-NAME PROP-VALUE) @dots{}) | |
120 | (OPT-NAME3 (PROP-NAME PROP-VALUE) @dots{}) | |
121 | @dots{} | |
122 | ) | |
123 | @end lisp | |
124 | ||
125 | Each @var{opt-name} specifies the long option name for that option. For | |
126 | example, a list element with @var{opt-name} @code{background} specifies | |
127 | an option that can be specified on the command line using the long | |
128 | option @code{--background}. Further information about the option --- | |
129 | whether it takes a value, whether it is required to be present in the | |
130 | command line, and so on --- is specified by the option properties. | |
131 | ||
132 | In the example of the preceding section, we already saw that a long | |
133 | option name can have a equivalent @dfn{short option} character. The | |
134 | equivalent short option character can be set for an option by specifying | |
135 | a @code{single-char} property in that option's property list. For | |
136 | example, a list element like @code{'(output (single-char #\o) @dots{})} | |
137 | specifies an option with long name @code{--output} that can also be | |
138 | specified by the equivalent short name @code{-o}. | |
139 | ||
140 | The @code{value} property specifies whether an option requires or | |
141 | accepts a value. If the @code{value} property is set to @code{#t}, the | |
142 | option requires a value: @code{getopt-long} will signal an error if the | |
143 | option name is present without a corresponding value. If set to | |
144 | @code{#f}, the option does not take a value; in this case, a non-option | |
145 | word that follows the option name in the command line will be treated as | |
146 | a non-option argument. If set to the symbol @code{optional}, the option | |
147 | accepts a value but does not require one: a non-option word that follows | |
148 | the option name in the command line will be interpreted as that option's | |
149 | value. If the option name for an option with @code{'(value optional)} | |
150 | is immediately followed in the command line by @emph{another} option | |
151 | name, the value for the first option is implicitly @code{#t}. | |
152 | ||
153 | The @code{required?} property indicates whether an option is required to | |
154 | be present in the command line. If the @code{required?} property is | |
155 | set to @code{#t}, @code{getopt-long} will signal an error if the option | |
156 | is not specified. | |
157 | ||
158 | Finally, the @code{predicate} property can be used to constrain the | |
159 | possible values of an option. If used, the @code{predicate} property | |
160 | should be set to a procedure that takes one argument --- the proposed | |
161 | option value as a string --- and returns either @code{#t} or @code{#f} | |
162 | according as the proposed value is or is not acceptable. If the | |
163 | predicate procedure returns @code{#f}, @code{getopt-long} will signal an | |
164 | error. | |
165 | ||
166 | By default, options do not have single-character equivalents, are not | |
167 | required, and do not take values. Where the list element for an option | |
168 | includes a @code{value} property but no @code{predicate} property, the | |
169 | option values are unconstrained. | |
170 | ||
171 | ||
172 | @node Command Line Format | |
173 | @subsection Expected Command Line Format | |
174 | ||
175 | In order for @code{getopt-long} to correctly parse a command line, that | |
176 | command line must conform to a standard set of rules for how command | |
177 | line options are specified. This section explains what those rules | |
178 | are. | |
179 | ||
180 | @code{getopt-long} splits a given command line into several pieces. All | |
181 | elements of the argument list are classified to be either options or | |
182 | normal arguments. Options consist of two dashes and an option name | |
183 | (so-called @dfn{long} options), or of one dash followed by a single | |
184 | letter (@dfn{short} options). | |
185 | ||
186 | Options can behave as switches, when they are given without a value, or | |
187 | they can be used to pass a value to the program. The value for an | |
188 | option may be specified using an equals sign, or else is simply the next | |
189 | word in the command line, so the following two invocations are | |
190 | equivalent: | |
191 | ||
192 | @example | |
193 | $ ./foo.scm --output=bar.txt | |
194 | $ ./foo.scm --output bar.txt | |
195 | @end example | |
196 | ||
197 | Short options can be used instead of their long equivalents and can be | |
198 | grouped together after a single dash. For example, the following | |
199 | commands are equivalent. | |
200 | ||
201 | @example | |
202 | $ ./foo.scm --version --help | |
203 | $ ./foo.scm -v --help | |
204 | $ ./foo.scm -vh | |
205 | @end example | |
206 | ||
207 | If an option requires a value, it can only be grouped together with other | |
208 | short options if it is the last option in the group; the value is the | |
209 | next argument. So, for example, with the following option | |
210 | specification --- | |
211 | ||
212 | @lisp | |
213 | ((apples (single-char #\a)) | |
214 | (blimps (single-char #\b) (value #t)) | |
215 | (catalexis (single-char #\c) (value #t))) | |
216 | @end lisp | |
217 | ||
218 | @noindent | |
219 | --- the following command lines would all be acceptable: | |
220 | ||
221 | @example | |
222 | $ ./foo.scm -a -b bang -c couth | |
223 | $ ./foo.scm -ab bang -c couth | |
224 | $ ./foo.scm -ac couth -b bang | |
225 | @end example | |
226 | ||
227 | But the next command line is an error, because @code{-b} is not the last | |
228 | option in its combination, and because a group of short options cannot | |
229 | include two options that both require values: | |
230 | ||
231 | @example | |
232 | $ ./foo.scm -abc couth bang | |
233 | @end example | |
234 | ||
235 | If an option's value is optional, @code{getopt-long} decides whether the | |
236 | option has a value by looking at what follows it in the argument list. | |
237 | If the next element is a string, and it does not appear to be an option | |
238 | itself, then that string is the option's value. | |
239 | ||
240 | If the option @code{--} appears in the argument list, argument parsing | |
241 | stops there and subsequent arguments are returned as ordinary arguments, | |
242 | even if they resemble options. So, with the command line | |
243 | ||
244 | @example | |
245 | $ ./foo.scm --apples "Granny Smith" -- --blimp Goodyear | |
246 | @end example | |
247 | ||
248 | @noindent | |
249 | @code{getopt-long} will recognize the @code{--apples} option as having | |
250 | the value "Granny Smith", but will not treat @code{--blimp} as an | |
251 | option. The strings @code{--blimp} and @code{Goodyear} will be returned | |
252 | as ordinary argument strings. | |
253 | ||
254 | ||
255 | @node getopt-long Reference | |
256 | @subsection Reference Documentation for @code{getopt-long} | |
257 | ||
c382f589 | 258 | @deffn {Scheme Procedure} getopt-long args grammar [#:stop-at-first-non-option #t] |
3229f68b MV |
259 | Parse the command line given in @var{args} (which must be a list of |
260 | strings) according to the option specification @var{grammar}. | |
261 | ||
262 | The @var{grammar} argument is expected to be a list of this form: | |
263 | ||
264 | @code{((@var{option} (@var{property} @var{value}) @dots{}) @dots{})} | |
265 | ||
266 | where each @var{option} is a symbol denoting the long option, but | |
679cceed | 267 | without the two leading dashes (e.g.@: @code{version} if the option is |
3229f68b MV |
268 | called @code{--version}). |
269 | ||
270 | For each option, there may be list of arbitrarily many property/value | |
271 | pairs. The order of the pairs is not important, but every property may | |
272 | only appear once in the property list. The following table lists the | |
273 | possible properties: | |
274 | ||
275 | @table @asis | |
276 | @item @code{(single-char @var{char})} | |
277 | Accept @code{-@var{char}} as a single-character equivalent to | |
278 | @code{--@var{option}}. This is how to specify traditional Unix-style | |
279 | flags. | |
280 | @item @code{(required? @var{bool})} | |
281 | If @var{bool} is true, the option is required. @code{getopt-long} will | |
282 | raise an error if it is not found in @var{args}. | |
283 | @item @code{(value @var{bool})} | |
284 | If @var{bool} is @code{#t}, the option accepts a value; if it is | |
285 | @code{#f}, it does not; and if it is the symbol @code{optional}, the | |
286 | option may appear in @var{args} with or without a value. | |
287 | @item @code{(predicate @var{func})} | |
679cceed | 288 | If the option accepts a value (i.e.@: you specified @code{(value #t)} for |
3229f68b MV |
289 | this option), then @code{getopt-long} will apply @var{func} to the |
290 | value, and throw an exception if it returns @code{#f}. @var{func} | |
291 | should be a procedure which accepts a string and returns a boolean | |
292 | value; you may need to use quasiquotes to get it into @var{grammar}. | |
293 | @end table | |
c382f589 NJ |
294 | |
295 | The @code{#:stop-at-first-non-option} keyword, if specified with any | |
296 | true value, tells @code{getopt-long} to stop when it gets to the first | |
297 | non-option in the command line. That is, at the first word which is | |
298 | neither an option itself, nor the value of an option. Everything in the | |
299 | command line from that word onwards will be returned as non-option | |
300 | arguments. | |
3229f68b MV |
301 | @end deffn |
302 | ||
303 | @code{getopt-long}'s @var{args} parameter is expected to be a list of | |
304 | strings like the one returned by @code{command-line}, with the first | |
305 | element being the name of the command. Therefore @code{getopt-long} | |
306 | ignores the first element in @var{args} and starts argument | |
307 | interpretation with the second element. | |
308 | ||
309 | @code{getopt-long} signals an error if any of the following conditions | |
310 | hold. | |
311 | ||
312 | @itemize @bullet | |
313 | @item | |
314 | The option grammar has an invalid syntax. | |
315 | ||
316 | @item | |
317 | One of the options in the argument list was not specified by the | |
318 | grammar. | |
319 | ||
320 | @item | |
321 | A required option is omitted. | |
322 | ||
323 | @item | |
324 | An option which requires an argument did not get one. | |
325 | ||
326 | @item | |
327 | An option that doesn't accept an argument does get one (this can only | |
328 | happen using the long option @code{--opt=@var{value}} syntax). | |
329 | ||
330 | @item | |
331 | An option predicate fails. | |
332 | @end itemize | |
333 | ||
c382f589 | 334 | @code{#:stop-at-first-non-option} is useful for command line invocations |
b8b06598 | 335 | like @code{guild [--help | --version] [script [script-options]]} |
c382f589 NJ |
336 | and @code{cvs [general-options] command [command-options]}, where there |
337 | are options at two levels: some generic and understood by the outer | |
338 | command, and some that are specific to the particular script or command | |
339 | being invoked. To use @code{getopt-long} in such cases, you would call | |
340 | it twice: firstly with @code{#:stop-at-first-non-option #t}, so as to | |
341 | parse any generic options and identify the wanted script or sub-command; | |
342 | secondly, and after trimming off the initial generic command words, with | |
343 | a script- or sub-command-specific option grammar, so as to process those | |
344 | specific options. | |
345 | ||
3229f68b MV |
346 | |
347 | @node option-ref Reference | |
348 | @subsection Reference Documentation for @code{option-ref} | |
349 | ||
350 | @deffn {Scheme Procedure} option-ref options key default | |
351 | Search @var{options} for a command line option named @var{key} and | |
352 | return its value, if found. If the option has no value, but was given, | |
353 | return @code{#t}. If the option was not given, return @var{default}. | |
354 | @var{options} must be the result of a call to @code{getopt-long}. | |
355 | @end deffn | |
356 | ||
357 | @code{option-ref} always succeeds, either by returning the requested | |
358 | option value from the command line, or the default value. | |
359 | ||
360 | The special key @code{'()} can be used to get a list of all | |
361 | non-option arguments. |