guile18/doc/ref/mod-getopt-long.texi

   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.