source: project/wiki/eggref/5/getopt-long @ 37298

Last change on this file since 37298 was 37298, checked in by Ivan Raikov, 21 months ago

C5 doc for getopt-long

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