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

Last change on this file since 27144 was 27144, checked in by Ivan Raikov, 9 years ago

nemo version history update

File size: 7.2 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 [(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.
41
42In addition, the following properties can be defined for a value:
43
44; {{(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.
45; {{(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.
46
47The {{(PROPERTY VALUE)}} pairs may occur in any order, but each
48property may occur only once.  By default, options do not have
49single-character equivalents, are not required, and do not take
50values.
51
52=== Library Procedures
53
54{{getopt-long}} is a procedure for parsing command-line arguments in
55a manner consistent with GNU programs.
56
57{{usage}} is a procedure that creates help strings given a grammar for
58the command-line arguments.
59
60<procedure>(getopt-long ARGS GRAMMAR [UNKNOWN-OPTION-HANDLER])</procedure>
61
62Parse the arguments {{ARGS}} according to the argument list grammar
63{{GRAMMAR}}.
64
65{{ARGS}} should be a list of strings.  Its first element should be the
66name of the program; subsequent elements should be the arguments that
67were passed to the program on the command line.  The
68{{program-arguments}} procedure returns a list of this form.
69
70In {{ARGS}}, single-character options may be combined, in the usual
71Unix fashion: {{("-x" "-y")}} is equivalent to {{("-xy")}}.  If an
72option accepts values, then it must be the last option in the
73combination; the value is the next argument.  So, for example, using
74the following grammar:
75
76     ((apples    (single-char #\a))
77      (blimps    (single-char #\b) (value #t))
78      (catalexis (single-char #\c) (value #t)))
79
80the following argument lists would be acceptable:
81
82   ("-a" "-b" "bang" "-c" "couth")     ("bang" and "couth" are the values
83                                        for "blimps" and "catalexis")
84   ("-ab" "bang" "-c" "couth")         (same)
85   ("-ac" "couth" "-b" "bang")         (same)
86   ("-abc" "couth" "bang")             (an error, since `-b' is not the
87                                        last option in its combination)
88
89If an option's value is optional, then {{getopt-long}} decides whether
90it has a value by looking at what follows it in {{ARGS}}.  If the next
91element is does not appear to be an option itself, then that element
92is the option's value.
93
94The value of a long option can can only follow the option name,
95separated by an `=' character.
96
97If the option "--" appears in {{ARGS}}, argument parsing stops there;
98subsequent arguments are returned as ordinary arguments, even if they
99resemble options.  So, in the argument list:
100
101        ("--apples" "Granny Smith" "--" "--blimp" "Goodyear")
102
103{{getopt-long}} will recognize the `apples' option as having the value
104"Granny Smith", but it will not recognize the `blimp' option; it will
105return the strings "--blimp" and "Goodyear" as ordinary argument
106strings.
107
108The {{getopt-long}} function returns an association list in which the
109key is an option name --- one of the symbols from {{GRAMMAR}} --- and
110each key is associated either with a single value (if the named option
111has been given once), or with a list of values (if the option was
112given multiple times). Options that were not given are not present.
113
114There is a special item in the returned alist with a key {{'@}}: this
115is the list of arguments that are not options or option values.
116
117Optional keyword argument {{UNKNOWN-OPTION-HANDLER}} is a procedure
118that receives as an argument a list of all options that were given as
119input but were unrecognized by the grammar. The default unknown option
120handler raises an error.
121
122
123By default, {{getopt-long}} throws an exception if:
124* it finds an unrecognized property in GRAMMAR
125* it finds an unrecognized option in ARGS
126* a required option is omitted
127* an option that requires an argument doesn't get one
128* an option that doesn't accept an argument does get one (this can only happen using the long option {{--opt=value}} syntax)
129* an option predicate fails
130
131
132
133=== Examples
134
135<enscript highlight=scheme>
136 (define grammar
137  `((lockfile-dir (required #t)
138                  (value #t)
139                  (single-char #\k)
140                  (value (required DIR)
141                         (predicate ,directory?)))
142 
143    (verbose (required #f)
144             (single-char #\v)
145             (value #f))
146 
147    (x-includes (single-char #\x)
148             (value #t))
149 
150    (rnet-server (single-char #\y)
151                 (value (required SERVER)
152                 (predicate ,string?)))
153    ))
154 
155  (getopt-long '("my-prog" "-vk" "/tmp" "foo1" "--x-includes=/usr/include"
156                 "--rnet-server=lamprod" "--" "-fred" "foo2" "foo3")
157    grammar)
158</enscript>
159
160
161=== Version History
162
163* 1.0 Initial Release
164
165=== License
166
167The {{gap-buffer}} library was written by Thien-Thi Nguyen for Guile Scheme.
168
169{{gap-buffer}} was ported to Chicken Scheme by Ivan Raikov.
170
171 Copyright (C) 1998, 2001, 2006 Free Software Foundation,
172 Inc.
173 
174 This program is free software: you can redistribute it and/or
175 modify it under the terms of the GNU Lesser General Public License
176 as published by the Free Software Foundation, either version 3 of
177 the License, or (at your option) any later version.
178 
179 This program is distributed in the hope that it will be useful, but
180 WITHOUT ANY WARRANTY; without even the implied warranty of
181 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
182 General Public License for more details.
183 
184 A full copy of the Lesser GPL license can be found at
185 <http://www.gnu.org/licenses/>.
186
Note: See TracBrowser for help on using the repository browser.