source: project/wiki/eggref/5/optimism @ 36452

Last change on this file since 36452 was 36452, checked in by evhan, 12 months ago

release/5/egg-locations: Add optimism and schematic

File size: 4.3 KB
Line 
1[[tags: egg]]
2
3== optimism
4
5Command line option handling.
6
7[[toc:]]
8
9== Description
10
11This extension provides a way to collect command line options into an association list according to a simple S-expressive grammar.
12
13== Usage
14
15One procedure is provided, {{parse-command-line}}, which takes as arguments an options grammar and an optional list of command line option strings and returns an association list. If no list of options is given, the program's command line arguments are used.
16
17<enscript highlight=scheme>
18(import (optimism))
19
20(parse-command-line
21 '("-a" "-b" "one" "-c" "two" "three" "-d" "four" "5" "six")
22 `((-a)
23   (-b . foo)
24   (-c bar baz)
25   (-d ,string->symbol ,string->number)))
26
27; => ((-a)
28;     (-b . "one")
29;     (-c "two" "three")
30;     (-d four 5)
31;     (-- "six"))
32</enscript>
33
34As a special case, an item in the grammar whose first element is a list will be split into separate entries, allowing an abbreviated syntax for multiple option specifications of the same form:
35
36<enscript highlight=scheme>
37(parse-command-line '(((--foo --bar --baz) . qux)))
38
39; => (parse-command-line
40;     '((--foo . qux)
41;       (--bar . qux)
42;       (--baz . qux)))
43</enscript>
44
45Parsers for {{getopt(3)}} and {{getopt_long(3)}}-style command lines are provided by the {{getopt}} and {{getopt-long}} sublibraries, respectively.
46
47<enscript highlight=scheme>
48(import (optimism getopt))
49
50(parse-command-line               ; => ((-a)
51 '("-abcone" "-d" "two")          ;     (-b)
52 '((-a)                           ;     (-c . "one")
53   (-b)                           ;     (-d . "two")
54   (-c . one)                     ;     (--))
55   (-d . two)))
56
57(import (optimism getopt-long))
58
59(parse-command-line               ; => ((-a . "one")
60 '("-aone" "--foo" "--bar=two")   ;     (--foo)
61 '((-a . one)                     ;     (--bar . "two")
62   (--foo)                        ;     (--))
63   (--bar . two)))
64</enscript>
65
66=== API
67
68<procedure>(parse-command-line grammar)</procedure>
69<procedure>(parse-command-line arguments grammar)</procedure>
70<procedure>(parse-command-line matcher arguments grammar)</procedure>
71
72{{parse-command-line}} parses a program's command line arguments into an association list according to an S-expressive options grammar.
73
74It takes one required and two optional arguments: an option matching procedure, an S-expressive options {{grammar}}, and a list of command line argument strings. If {{matcher}} is not given a basic string comparison is used, while {{arguments}} defaults to the value of {{(cdr (command-line))}}.
75
76{{grammar}} is a finite list of pairs whose {{car}}s are symbols and whose {{cdr}}s are pairs or atoms. All other {{car}}s in the grammar must be atoms; grammars may not be nested.
77
78The given {{arguments}} are matched as symbols against the {{car}}s of the options grammar. When a match is found, an association from the matched symbol to the arguments immediately following the matched item in the arguments list is added, following the form of the matched pair.
79
80<enscript=scheme>
81(parse-command-line               ; => ((foo . "bar")
82 '("foo" "bar")                   ;     (--))
83 '((foo . bar)))
84
85(parse-command-line               ; => ((foo)
86 '("foo" "bar" "baz" "qux")       ;     (bar "baz" "qux")
87 '((foo)                          ;     (--))
88   (bar baz qux)))
89</enscript>
90
91Unmatched arguments are added to the resulting association list under the key {{--}}. Similarly, any arguments following a {{"--"}} in the arguments list are treated as unmatched.
92
93<enscript=scheme>
94(parse-command-line               ; => ((foo . "bar")
95 '("foo" "bar" "baz")             ;     (-- "baz"))
96 '((foo . bar)))
97
98(parse-command-line               ; => ((foo . "bar")
99 '("foo" "bar" "--" "baz" "qux")  ;     (-- "baz" "qux"))
100 '((foo . bar)
101   (baz . qux)))
102</enscript>
103
104In a matched options form, procedures are replaced by the result of invoking that procedure on the corresponding item in the arguments list. All other objects are replaced by the corresponding argument string directly.
105
106<enscript=scheme>
107(parse-command-line               ; => ((foo ("bar") 42 qux)
108 '("foo" "bar" "42" "qux")        ;     (--))
109 `((foo ,list
110        ,string->number
111        ,string->symbol)))
112</enscript>
113
114== Author
115
116[[/users/evan-hanson|Evan Hanson]]
117
118== License
119
120This software is written by Evan Hanson and placed in the Public Domain. All warranties are disclaimed.
Note: See TracBrowser for help on using the repository browser.