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