2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @section The (ice-9 getopt-long) Module
10 The @code{(ice-9 getopt-long)} module exports two procedures:
11 @code{getopt-long} and @code{option-ref}.
15 @code{getopt-long} takes a list of strings --- the command line
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
19 structure that encapsulates the results of the parsing.
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.
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}.
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}.
39 @node getopt-long Example
40 @subsection A Short getopt-long Example
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
51 '((version (single-char #\v) (value #f))
52 (help (single-char #\h) (value #f))))
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.
61 With this specification we can use @code{getopt-long} to parse a given
65 (define options (getopt-long (command-line) option-spec))
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
73 (option-ref options 'help #f)
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.
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.
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)
97 (display "getopt-long-example version 0.3\n"))
100 getopt-long-example [options]
101 -v, --version Display version
102 -h, --help Display this help
105 (display "Hello, World!") (newline)))))
109 @node Option Specification
110 @subsection How to Write an Option Specification
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:
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{})
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.
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}.
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}.
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
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
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.
172 @node Command Line Format
173 @subsection Expected Command Line Format
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
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).
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
193 $ ./foo.scm --output=bar.txt
194 $ ./foo.scm --output bar.txt
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.
202 $ ./foo.scm --version --help
203 $ ./foo.scm -v --help
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
213 ((apples (single-char #\a))
214 (blimps (single-char #\b) (value #t))
215 (catalexis (single-char #\c) (value #t)))
219 --- the following command lines would all be acceptable:
222 $ ./foo.scm -a -b bang -c couth
223 $ ./foo.scm -ab bang -c couth
224 $ ./foo.scm -ac couth -b bang
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:
232 $ ./foo.scm -abc couth bang
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.
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
245 $ ./foo.scm --apples "Granny Smith" -- --blimp Goodyear
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.
255 @node getopt-long Reference
256 @subsection Reference Documentation for @code{getopt-long}
258 @deffn {Scheme Procedure} getopt-long args grammar [#:stop-at-first-non-option #t]
259 Parse the command line given in @var{args} (which must be a list of
260 strings) according to the option specification @var{grammar}.
262 The @var{grammar} argument is expected to be a list of this form:
264 @code{((@var{option} (@var{property} @var{value}) @dots{}) @dots{})}
266 where each @var{option} is a symbol denoting the long option, but
267 without the two leading dashes (e.g.@: @code{version} if the option is
268 called @code{--version}).
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
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
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})}
288 If the option accepts a value (i.e.@: you specified @code{(value #t)} for
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}.
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
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.
309 @code{getopt-long} signals an error if any of the following conditions
314 The option grammar has an invalid syntax.
317 One of the options in the argument list was not specified by the
321 A required option is omitted.
324 An option which requires an argument did not get one.
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).
331 An option predicate fails.
334 @code{#:stop-at-first-non-option} is useful for command line invocations
335 like @code{guild [--help | --version] [script [script-options]]}
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
347 @node option-ref Reference
348 @subsection Reference Documentation for @code{option-ref}
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}.
357 @code{option-ref} always succeeds, either by returning the requested
358 option value from the command line, or the default value.
360 The special key @code{'()} can be used to get a list of all
361 non-option arguments.