source: project/wiki/eggref/4/getopt-long @ 15624

Last change on this file since 15624 was 15624, checked in by Ivan Raikov, 11 years ago

formatting fixes to getopt-long documenation

File size: 7.1 KB
Line 
1[[tags: eggs]]
2[[toc:]]
3
4== getopt-long
5
6=== Description
7
8The {{getopt-long}} library implements command line option parsing, in
9the spirit of the GNU C library function {{getopt_long}}.  Both long
10and short options are supported.
11
12The theory is that people should be able to constrain the set of
13options they want to process using a grammar, rather than some
14arbitrary structure.  The grammar makes the option descriptions easy
15to read.
16
17
18=== Command-line option grammar
19
20The option grammar is an s-expression of the form:
21
22 ((OPTION-NAME [DOCSTRING]
23               (PROPERTY VALUE) ...)
24   ...)
25
26Each {{OPTION-NAME}} should be a symbol.  Given this grammar,
27{{getopt-long}} will then accept a command-line option named
28{{--OPTION-NAME}}.
29
30If {{DOCSTRING}} is provided, it must be a string containing a brief
31description of the option.
32
33Each option can have the following (PROPERTY VALUE) pairs:
34
35; {{(single-char CHAR)}} : Accept {{-CHAR}} as a single-character
36equivalent to {{--OPTION}}.  This is how to specify traditional
37Unix-style flags.
38; {{(required? BOOL)}} : If {{BOOL}} is true, the option is required. {{getopt-long}} will raise an error if it is not found in the list of arguments.
39; {{(value FLAG [(PROPERTY VALUE) ...])}} : If {{FLAG}} is {{#t}}, the option requires a value; if it is {{#f}}, it does not; if it is of the form {{(REQUIRED name)}} then the option requires and the name is used by the usage procedure if it is of the form {{(OPTIONAL name)}} the option may appear with or without a (named) value.
40
41In addition, the following properties can be defined for a value:
42
43; {{(predicate FUNC)}} : If the option accepts a value (i.e. you specified {{(value #t)}} for this option), then {{getopt-long}} will apply {{FUNC}} to the value, and throw an exception if it returns {{#f}}.  {{FUNC}} should be a procedure which accepts a string and returns a boolean value; you may need to use quasiquotes to get it into the grammar.
44; {{(transformer FUNC)}} : If the option accepts a value, then getopt will apply FUNC to the string provided on the command line, and put the resulting value in the list of parsed options returned by getopt-long.
45
46The {{(PROPERTY VALUE)}} pairs may occur in any order, but each
47property may occur only once.  By default, options do not have
48single-character equivalents, are not required, and do not take
49values.
50
51=== Library Procedures
52
53{{getopt-long}} is a procedure for parsing command-line arguments in
54a manner consistent with GNU programs.
55
56{{usage}} is a procedure that creates help strings given a grammar for
57the command-line arguments.
58
59<procedure>(getopt-long ARGS GRAMMAR)</procedure>
60
61Parse the arguments {{ARGS}} according to the argument list grammar
62{{GRAMMAR}}.
63
64{{ARGS}} should be a list of strings.  Its first element should be the
65name of the program; subsequent elements should be the arguments that
66were passed to the program on the command line.  The
67{{program-arguments}} procedure returns a list of this form.
68
69In {{ARGS}}, single-character options may be combined, in the usual
70Unix fashion: {{("-x" "-y")}} is equivalent to {{("-xy")}}.  If an
71option accepts values, then it must be the last option in the
72combination; the value is the next argument.  So, for example, using
73the following grammar:
74
75     ((apples    (single-char #\a))
76      (blimps    (single-char #\b) (value #t))
77      (catalexis (single-char #\c) (value #t)))
78
79the following argument lists would be acceptable:
80
81   ("-a" "-b" "bang" "-c" "couth")     ("bang" and "couth" are the values
82                                        for "blimps" and "catalexis")
83   ("-ab" "bang" "-c" "couth")         (same)
84   ("-ac" "couth" "-b" "bang")         (same)
85   ("-abc" "couth" "bang")             (an error, since `-b' is not the
86                                        last option in its combination)
87
88If an option's value is optional, then {{getopt-long}} decides whether
89it has a value by looking at what follows it in {{ARGS}}.  If the next
90element is does not appear to be an option itself, then that element
91is the option's value.
92
93The value of a long option can appear as the next element in {{ARGS}},
94or it can follow the option name, separated by an `=' character.
95Thus, using the same grammar as above, the following argument lists
96are equivalent:
97
98  ("--apples" "Braeburn" "--blimps" "Goodyear")
99  ("--apples=Braeburn" "--blimps" "Goodyear")
100  ("--blimps" "Goodyear" "--apples=Braeburn")
101
102If the option "--" appears in {{ARGS}}, argument parsing stops there;
103subsequent arguments are returned as ordinary arguments, even if they
104resemble options.  So, in the argument list:
105
106        ("--apples" "Granny Smith" "--" "--blimp" "Goodyear")
107
108{{getopt-long}} will recognize the `apples' option as having the value
109"Granny Smith", but it will not recognize the `blimp' option; it will
110return the strings "--blimp" and "Goodyear" as ordinary argument
111strings.
112
113The {[getopt-long}} function returns the parsed argument list as an
114assocation list, mapping option names --- the symbols from {{GRAMMAR}}
115--- onto their values, or #t if the option does not accept a value.
116Unused options do not appear in the alist.
117
118All arguments that are not the value of any option are returned
119as a list, associated with the empty list.
120
121{{getopt-long}} throws an exception if:
122* it finds an unrecognized property in GRAMMAR
123* the value of the `single-char' property is not a character
124* it finds an unrecognized option in ARGS
125* a required option is omitted
126* an option that requires an argument doesn't get one
127* an option that doesn't accept an argument does get one (this can only happen using the long option {{--opt=value}} syntax)
128* an option predicate fails
129
130=== Examples
131
132 (define grammar
133  `((lockfile-dir (required? #t)
134                  (value #t)
135                  (single-char #\k)
136                  (value (required DIR)
137                         (predicate ,directory?)))
138 
139    (verbose (required? #f)
140             (single-char #\v)
141             (value #f))
142 
143    (x-includes (single-char #\x)
144                (value #t))
145 
146    (rnet-server (single-char #\y)
147                 (value (required SERVER)
148                        (predicate ,string?)))
149    ))
150 
151  (getopt-long '("my-prog" "-vk" "/tmp" "foo1" "--x-includes=/usr/include"
152                 "--rnet-server=lamprod" "--" "-fred" "foo2" "foo3")
153    grammar)
154
155=== Requires
156
157* [[matchable]]
158* [[defstruct]]
159
160=== Version History
161
162* 1.0 Initial Release
163
164=== License
165
166The {{getopt-long}} library was originally written by Russ McManus and
167rewritten by Thien-Thi Nguyen.
168
169{{getopt-long}} was ported to Chicken Scheme and extensively modified
170by Ivan Raikov.
171
172 Copyright 2009 Ivan Raikov.
173 
174 Portions copyright (C) 1998, 2001, 2006 Free Software Foundation,
175 Inc.
176 
177 This program is free software: you can redistribute it and/or
178 modify it under the terms of the GNU Lesser General Public License
179 as published by the Free Software Foundation, either version 3 of
180 the License, or (at your option) any later version.
181 
182 This program is distributed in the hope that it will be useful, but
183 WITHOUT ANY WARRANTY; without even the implied warranty of
184 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
185 General Public License for more details.
186 
187 A full copy of the Lesser GPL license can be found at
188 <http://www.gnu.org/licenses/>.
189
Note: See TracBrowser for help on using the repository browser.