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 @node Command Line Handling
   8 @section Handling Command Line Options and Arguments
   9
  10 @c This chapter was written and contributed by Martin Grabmueller.
  11
  12 The ability to accept and handle command line arguments is very
  13 important when writing Guile scripts to solve particular problems, such
  14 as extracting information from text files or interfacing with existing
  15 command line applications.  This chapter describes how Guile makes
  16 command line arguments available to a Guile script, and the utilities
  17 that Guile provides to help with the processing of command line
  18 arguments.
  19
  20 When a Guile script is invoked, Guile makes the command line arguments
  21 accessible via the procedure @code{command-line}, which returns the
  22 arguments as a list of strings.
  23
  24 For example, if the script
  25
  26 @example
  27 #! /usr/local/bin/guile -s
  28 !#
  29 (write (command-line))
  30 (newline)
  31 @end example
  32
  33 @noindent
  34 is saved in a file @file{cmdline-test.scm} and invoked using the command
  35 line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}, the output
  36 is
  37
  38 @example
  39 ("./cmdline-test.scm" "bar.txt" "-o" "foo" "-frumple" "grob")
  40 @end example
  41
  42 If the script invocation includes a @code{-e} option, specifying a
  43 procedure to call after loading the script, Guile will call that
  44 procedure with @code{(command-line)} as its argument.  So a script that
  45 uses @code{-e} doesn't need to refer explicitly to @code{command-line}
  46 in its code.  For example, the script above would have identical
  47 behaviour if it was written instead like this:
  48
  49 @example
  50 #! /usr/local/bin/guile \
  51 -e main -s
  52 !#
  53 (define (main args)
  54   (write args)
  55   (newline))
  56 @end example
  57
  58 (Note the use of the meta switch @code{\} so that the script invocation
  59 can include more than one Guile option: @xref{The Meta Switch}.)
  60
  61 These scripts use the @code{#!} POSIX convention so that they can be
  62 executed using their own file names directly, as in the example command
  63 line @code{./cmdline-test.scm bar.txt -o foo -frumple grob}.  But they
  64 can also be executed by typing out the implied Guile command line in
  65 full, as in:
  66
  67 @example
  68 $ guile -s ./cmdline-test.scm bar.txt -o foo -frumple grob
  69 @end example
  70
  71 @noindent
  72 or
  73
  74 @example
  75 $ guile -e main -s ./cmdline-test2.scm bar.txt -o foo -frumple grob
  76 @end example
  77
  78 Even when a script is invoked using this longer form, the arguments that
  79 the script receives are the same as if it had been invoked using the
  80 short form.  Guile ensures that the @code{(command-line)} or @code{-e}
  81 arguments are independent of how the script is invoked, by stripping off
  82 the arguments that Guile itself processes.
  83
  84 A script is free to parse and handle its command line arguments in any
  85 way that it chooses.  Where the set of possible options and arguments is
  86 complex, however, it can get tricky to extract all the options, check
  87 the validity of given arguments, and so on.  This task can be greatly
  88 simplified by taking advantage of the module @code{(ice-9 getopt-long)},
  89 which is distributed with Guile, @xref{getopt-long}.
  90
  91 @c Local Variables:
  92 @c TeX-master: "guile.texi"
  93 @c End: