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