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

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

getopt-long documentation fixes

File size: 7.0 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* it finds an unrecognized option in ARGS
124* a required option is omitted
125* an option that requires an argument doesn't get one
126* an option that doesn't accept an argument does get one (this can only happen using the long option {{--opt=value}} syntax)
127* an option predicate fails
128
129=== Examples
130
131 (define grammar
132  `((lockfile-dir (required? #t)
133                  (value #t)
134                  (single-char #\k)
135                  (value (required DIR)
136                         (predicate ,directory?)))
137 
138    (verbose (required? #f)
139             (single-char #\v)
140             (value #f))
141 
142    (x-includes (single-char #\x)
143                (value #t))
144 
145    (rnet-server (single-char #\y)
146                 (value (required SERVER)
147                        (predicate ,string?)))
148    ))
149 
150  (getopt-long '("my-prog" "-vk" "/tmp" "foo1" "--x-includes=/usr/include"
151                 "--rnet-server=lamprod" "--" "-fred" "foo2" "foo3")
152    grammar)
153
154=== Requires
155
156* [[matchable]]
157* [[defstruct]]
158
159=== Version History
160
161* 1.0 Initial Release
162
163=== License
164
165The {{getopt-long}} library was originally written by Russ McManus and
166rewritten by Thien-Thi Nguyen.
167
168{{getopt-long}} was ported to Chicken Scheme and extensively modified
169by Ivan Raikov.
170
171 Copyright 2009 Ivan Raikov.
172 
173 Portions copyright (C) 1998, 2001, 2006 Free Software Foundation,
174 Inc.
175 
176 This program is free software: you can redistribute it and/or
177 modify it under the terms of the GNU Lesser General Public License
178 as published by the Free Software Foundation, either version 3 of
179 the License, or (at your option) any later version.
180 
181 This program is distributed in the hope that it will be useful, but
182 WITHOUT ANY WARRANTY; without even the implied warranty of
183 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
184 General Public License for more details.
185 
186 A full copy of the Lesser GPL license can be found at
187 <http://www.gnu.org/licenses/>.
188
Note: See TracBrowser for help on using the repository browser.