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