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