source: project/args/args.html @ 3174

Last change on this file since 3174 was 3174, checked in by Kon Lovett, 13 years ago

Put back what was rmvd.

File size: 14.7 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2<!-- Generated by eggdoc Revision: 1.20  -->
3<html>
4<head>
5<title>Eggs Unlimited - args</title><style type="text/css"> <!--
6      CODE {
7            color: #666666;
8          }
9/*   DT.definition EM { font-weight: bold; font-style: normal; } */
10
11     DT.definition { 
12                   background: #eee;
13                   color: black;
14                   padding: 0.2em 1em 0.2em 0.7em;
15                   margin-left: 0.2em;
16border: 1px solid #bbc;
17                   font-family: "Andale Mono", monospace;
18                   /* font-size: 1.2em; */
19                   
20                 }
21     DD {
22                   margin-top: 0.8em;
23                   margin-bottom: 0.8em;
24     }
25     DIV.subsection {
26                    border-top: 1px solid #448;
27                    padding-left: 1em;
28                    margin-bottom: 1.2em;
29     }
30     DIV.subsubsection {
31                    border-top: 1px dotted #99c;
32                    /* border-left: 1px solid #99c; */
33                    padding-left: 1em;
34                    margin-bottom: 1.2em;
35     }
36     DIV.subsubsubsection {
37                    border-top: 1px solid #ddf;
38                    padding-left: 1em;
39                    margin-bottom: 1.2em;
40     }
41
42         DIV.section {
43                 margin-bottom: 1.5em;
44         }
45         a:link {
46                 color: #336;
47         }
48         a:visited { color: #666; }
49         a:active  { color: #966; }
50         a:hover   { color: #669; }
51         body { margin: 0; padding: 0; background: #fff; color: #000; font: 9pt "Lucida Grande", "Verdana", sans-serif; }
52         H2 {
53                 background: #336;
54                 color: #fff;
55                 padding-top: 0.5em;
56                 padding-bottom: 0.5em;
57                 padding-left: 16px;
58                 margin: 0 0 1em 0;
59        }
60        UL LI {
61                list-style: none;
62        }
63        TT {
64                font-family: "Andale Mono", monospace;
65                /* font-size: 1.2em; */
66        }
67        H3 {
68                color: #113;
69                margin-bottom: 0.5em;
70        }
71        H4, H5, H6 {
72                color: #113;
73                margin-bottom: 1.0em;
74        }
75        H5 {
76                font-weight: normal;
77                font-style: italic;
78                font-size: 100%;
79                margin-top: 1.2em;
80        }
81        H6 {
82                font-weight: bold;
83                font-size: 85%;
84                margin-top: 1.2em;
85        }
86     DIV#eggheader {
87         text-align: center;
88                 float: right;
89                 margin-right: 2em;
90     }
91     DIV#header IMG {
92            /* display: block; margin-left: auto; margin-right: auto;  */
93            /* float: right; */
94            border: none;  /* firefox */
95     }
96     DIV#footer {
97                background: #bbd;
98                padding: 0.7em ;
99                border-top: 1px solid #cce;
100     }
101     DIV#footer hr {
102                display: none;
103     }
104     DIV#footer a {
105                float: left;
106     }
107     DIV#revision-history {
108         float: right;
109     }
110     
111     DIV#body {
112                 margin: 1em 1em 1em 16px;
113         }
114
115     DIV#examples PRE {
116       background: #eef;
117       padding: 0.1em;
118       border: 1px solid #aac;
119     }
120     PRE#license, DIV#examples PRE {
121       padding: 0.5em;
122     }
123     DIV#examples PRE {
124       /* font-size: 85%; */
125     }
126     PRE { font-family: "Andale Mono", monospace; }
127     TABLE {
128       background: #eef;
129       padding: 0.2em;
130       border: 1px solid #aac;
131       border-collapse: collapse;
132       width: 100%;
133     }
134     TABLE.symbol-table TD.symbol {
135          width: 15em;
136          font-family: "Andale Mono", monospace;
137          /* font-size: 1.2em; */
138     }
139     TH {
140       text-align: left;
141       border-bottom: 1px solid #aac;
142       padding: 0.25em 0.5em 0.25em 0.5em;
143     } 
144     TD { padding: 0.25em 0.5em 0.25em 0.5em; }
145     --></style></head>
146<body>
147<div id="header">
148<h2>args</h2>
149<div id="eggheader"><a href="index.html">
150<img src="egg.jpg" alt="[Picture of an egg]" /></a></div></div>
151<div id="body">
152<div class="section">
153<h3>Description</h3>Command-line argument handling facilities, layered on SRFI 37 (args-fold).</div>
154<div class="section">
155<h3>Author</h3><a href="http://3e8.org/zb">Zbigniew</a></div>
156<div class="section">
157<h3>Version</h3>
158<ul>
159<li>1.1 Added missing html [Thanks to Benedikt Rosenau]</li>
160<li>1.0 Initial release</li></ul></div>
161<div class="section">
162<h3>Requires</h3>
163<ul>
164<li>srfi-37 [args-fold]</li>
165<li>srfi-13 [string-lib]</li>
166<li>srfi-1 [list-lib]</li></ul></div>
167<div class="section">
168<h3>Usage</h3><tt>(require-extension args)</tt></div>
169<div class="section">
170<h3>Download</h3><a href="args.egg">args.egg</a></div>
171<div class="section">
172<h3>Documentation</h3>
173<p>This extension provides a wrapper around SRFI 37 (args-fold).  The main goal is to let the user parse command-line arguments without having to write a lot of similar support code every time.</p>
174<p>By default, options and operands (non-options) are collected into two lists and returned by the parser, and unrecognized options complain and display help.  Therefore, it is very possible not to write any option-procs, operand-procs, or unrecognized-procs as required by SRFI 37.  However, the capability to customize is there should you need it.</p>
175<p>Additionally, the help text for your options can be generated for you, so your options and usage information don't get out of sync.</p>
176<div class="subsection">
177<h4>Creating options</h4>
178<dl>
179<dt class="definition"><strong>macro:</strong> (args:make-option (OPTION-NAME ...) ARG-DATA DOC-STRING [BODY])</dt>
180<dd>
181<p>Make an args:option record, suitable for passing to args:parse.</p>
182<p>OPTION-NAME ... is a sequence of short or long option names. They must be literal symbols; single-character symbols become short options, and longer symbols become long options. So <tt>(args:make-option (c cookie) ...)</tt> specifies a short option -c and long option --cookie.  Under the hood, (c cookie) becomes '(#\c &quot;cookie&quot;), as expected by SRFI 37's OPTION.</p>
183<p>ARG-DATA is either a pair (ARG-TYPE ARG-NAME) or a plain keyword ARG-TYPE.
184ARG-TYPE is a keyword that specifies whether the option takes an argument:</p><table class="symbol-table">
185<tr>
186<td class="symbol">#:required</td>
187<td>Argument is required</td></tr>
188<tr>
189<td class="symbol">#:optional</td>
190<td>Argument is optional</td></tr>
191<tr>
192<td class="symbol">#:none</td>
193<td>No argument (actually, any other value than #:required or #:optional is interpreted as #:none)</td></tr></table>
194<p>ARG-NAME, if provided, is a string specifying the name of the argument.
195This name is used in the help text produced by args:usage.</p>
196<p>DOC-STRING is a documentation string for the argument.
197This string is used in the help text produced by args:usage.</p>
198<p>BODY is an optional sequence of statements executed when this option is encountered.
199Behind the scenes, BODY is wrapped in code which adds the current option and its
200argument to the final options alist.  So, simply leave BODY blank and options
201will be collected for you.  BODY is an option-processor as defined in SRFI 37,
202and has access to the variables OPT (the current #&lt;option&gt;), NAME (the option name)
203and ARG (argument value or #f).</p></dd></dl></div>
204<div class="subsection">
205<h4>Parsing the command line</h4>
206<dl>
207<dt class="definition"><strong>procedure:</strong> (args:parse ARGS OPTIONS-LIST [OPTIONALS])</dt>
208<dd>
209<p>Parse ARGS, a list of command-line arguments given as strings,
210and return two values: an alist of option names (symbols) and their values,
211and a list of operands (non-option arguments).</p>
212<p>Operands are returned in order, but options
213are returned in reverse order.  Duplicate options are retained in
214the options alist, so this lets ASSQ find the <i>last</i>
215occurrence of any duplicate option on the command line.  A (name
216. value) pair is added for each alias of every option found, so
217any alias is a valid lookup key.</p>
218<p>OPTIONS-LIST is a list of accepted options, each created by
219args:make-option.</p>
220<p>OPTIONALS is an optional sequence of keywords and values:</p><table class="symbol-table">
221<tr>
222<td class="symbol">#:operand-proc PROC</td>
223<td>calls PROC for each operand, with
224                                   arguments OPERAND OPTIONS OPERANDS</td></tr>
225<tr>
226<td class="symbol">#:unrecognized-proc PROC</td>
227<td>calls PROC for each unrecognized
228                                   option, with arguments OPTION NAME ARG OPTIONS OPERANDS</td></tr></table>
229<p>The default operand-proc is a no-op, and the default unrecognized-proc
230issues an error message and calls the help option's processor.
231See the args-fold documentation for usage information and an explanation
232of the procedure arguments; OPTIONS and OPERANDS are seed values.</p></dd>
233<dt class="definition"><strong>parameter:</strong> args:help-options</dt>
234<dd>
235<p>List of option names (strings or single characters, as in SRFI 37)
236to be considered 'help' options, in order of preference.  args:parse
237uses this to select a help option from the option list it is passed.
238This is currently used only for unrecognized options, for which the
239help option is automatically invoked.</p>
240<p>By default, --help, -h and -? are considered help options.</p></dd></dl></div>
241<div class="subsection">
242<h4>Usage information</h4>
243<p>Well-behaved programs display help or usage text when invoked with an option such as --help.  args:usage will generate a formatted list of options in the GNU style, from a list of args:options.  Around this you might place a descriptive header and footer.</p>
244<dl>
245<dt class="definition"><strong>procedure:</strong> (args:usage OPTION-LIST)</dt>
246<dd>
247<p>Generate a formatted list of options from OPTION-LIST,
248and return a string suitable for embedding into help text.
249The single string consists of multiple lines, with a newline
250at the end of each line.  Thus, a typical use would be <tt>(print (args:usage opts)).</tt></p></dd>
251<dt class="definition"><strong>parameter:</strong> args:width</dt>
252<dd>
253<p>We don't auto-format the left column (the option keys) based on the length of the longest option, but you can override it manually.  Example:</p>
254<p><tt>(parameterize ((args:width 40)) (args:usage opts))</tt></p></dd></dl></div>
255<div class="subsection">
256<h4>Operands and unrecognized options (advanced)</h4>
257<p>These are suitable for use with #:operand-proc or #:unrecognized-proc in args:parse.  Most users will probably not customize these procedures themselves, but a couple useful prefabricated ones are provided.</p>
258<dl>
259<dt class="definition"><strong>procedure:</strong> args:ignore-unrecognized-options</dt>
260<dd>
261<p>Silently ignore unrecognized options, and omit from the options alist.</p></dd>
262<dt class="definition"><strong>procedure:</strong> args:accept-unrecognized-options</dt>
263<dd>
264<p>Silently add unrecognized options to the options alist.</p></dd>
265<dt class="definition"><strong>macro:</strong> (args:make-operand-proc [BODY])</dt>
266<dd>
267<p>Return a procedure suitable for using as an operand procedure
268in args:parse.  Provides the arguments OPERAND, OPTIONS, and OPERANDS
269to the BODY; where OPERAND is the current operand (as in args-fold)
270and OPTIONS and OPERANDS are SEEDS (as in args-fold) and should not be modified.
271Also wraps BODY in code that adds the operand to the final operand list (seed).</p></dd></dl></div></div>
272<div class="section">
273<h3>Bugs</h3>
274<p>The name <tt>args:make-option</tt> is verbose.</p></div>
275<div class="section">
276<h3>Examples</h3>
277<div id="examples">
278<pre>(use args)
279
280(define opts
281 (list (args:make-option (c cookie)    #:none     &quot;give me cookie&quot;
282         (print &quot;cookie was tasty&quot;))
283       (args:make-option (d)           (optional: &quot;LEVEL&quot;&quot;debug level [default: 1]&quot;)
284       (args:make-option (e elephant)  #:required &quot;flatten the argument&quot;
285         (print &quot;elephant: arg is &quot; arg))
286       (args:make-option (f file)      (required: &quot;NAME&quot;)   &quot;parse file NAME&quot;)
287       (args:make-option (v V version) #:none     &quot;Display version&quot;
288         (print &quot;args-example $Revision: 1.3 $&quot;)
289         (exit))
290       (args:make-option (abc)         #:none     &quot;Recite the alphabet&quot;)
291       (args:make-option (h help)      #:none     &quot;Display this text&quot;
292         (usage))))
293
294(define (usage)
295 (with-output-to-port (current-error-port)
296   (lambda ()
297     (print &quot;Usage: &quot; (car (argv)) &quot; [options...] [files...]&quot;)
298     (newline)
299     (print (args:usage opts))
300     (print &quot;Report bugs to zbigniewsz at gmail.&quot;)))
301 (exit 1))
302
303(receive (options operands)
304    (args:parse (command-line-arguments) opts)
305  (print &quot;-e -&gt; &quot; (alist-ref 'elephant options))) ;; 'e or 'elephant both work
306
307;; If command line is --cookie -e test -e hello:
308;;  cookie was tasty
309;;  elephant: arg is test
310;;  elephant: arg is hello
311;;  -e -&gt; hello
312
313;; If command line is --cookie -e test --foo:
314#|
315cookie was tasty
316elephant: arg is test
317./args-example: unrecognized option: foo
318Usage: ./args-example [options...] [files...]
319
320 -c, --cookie             give me cookie
321 -d [LEVEL]               debug level [default: 1]
322 -e, --elephant=ARG       flatten the argument
323 -f, --file=NAME          parse file NAME
324 -v, -V, --version        Display version
325     --abc                Recite the alphabet
326 -h, --help               Display this text
327
328Report bugs to zbigniewsz at gmail.
329|#
330</pre>
331<p>Additional examples can be found in <a href="args-examples.scm">args-examples.scm</a>.</p></div></div>
332<div class="section">
333<h3>License</h3>
334<pre id="license">Copyright (c) 2005, 2006 Jim &quot;Zb&quot; Ursetto.  All rights reserved.
335
336Redistribution and use in source and binary forms, with or without
337modification, are permitted provided that the following conditions are met:
338
339  Redistributions of source code must retain the above copyright notice,
340  this list of conditions and the following disclaimer. Redistributions in
341  binary form must reproduce the above copyright notice, this list of
342  conditions and the following disclaimer in the documentation and/or
343  other materials provided with the distribution. Neither the name of the
344  author nor the names of its contributors may be used to endorse or
345  promote products derived from this software without specific prior
346  written permission.
347
348THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS &quot;AS
349IS&quot; AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
350THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
351PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
352CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
353EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
354PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
355PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
356LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
357NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
358SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</pre></div></div>
359<div id="footer">
360<hr /><a href="index.html">&lt; Egg index</a>
361<div id="revision-history">$Revision$ $Date$</div>&nbsp;</div></body></html>
Note: See TracBrowser for help on using the repository browser.