source: project/wiki/eggref/4/easy-args @ 36801

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

wiki/eggref: update docs/formatting/urls and eggref/5/{r7rs,fancypants,chicken-belt}

File size: 3.3 KB
Line 
1[[tags: egg]]
2
3== easy-args
4
5[[toc:]]
6
7== Description
8
9Handle command-line arguments as parameter objects.
10
11'''This egg is no longer maintained.''' Please refer to
12[[/eggref/4/srfi-37|srfi-37]], [[/eggref/4/args|args]] or
13[[/eggref/4/getopt-long|getopt-long]] for other command-line argument
14handling libraries for CHICKEN 4.
15
16== Requirements
17
18[[/eggref/4/srfi-37|srfi-37]]
19
20== API
21
22=== define-arguments
23
24<syntax>(define-arguments (name [value [guard]]) ...)</syntax>
25
26{{define-arguments}} defines parameter objects for the given command line
27option names and sets them according to the program's
28{{command-line-arguments}} parameter.
29
30For each specified argument, {{name}} should be an identifier or list of
31identifiers. The first of these will be bound to the newly-created parameter
32object. {{value}}, if given, must be a boolean, string, number or symbol, and
33will be the default value of the parameter object. If no {{value}} is given,
34{{#f}} is used. If a procedure {{guard}} is given, it is used as the parameter
35object's conversion procedure.
36
37Each {{name}}, when prefixed by one dash (in the case of a single-character
38identifier) or two (for all others), will be used as a command-line flag to set
39the corresponding parameter object's value. If {{name}} contains asterisks,
40they are stripped from the flag.
41
42{{define-arguments}} reads and modifies Chicken's {{command-line-arguments}}
43parameter, setting matched parameter objects to the specified values and
44removing their options from the list. Unmatched arguments are accumulated into
45an alist accessible by the {{unmatched-arguments}} procedure. Upon completion,
46{{command-line-arguments}} will contain any non-option arguments to the
47program. The return value is unspecified.
48
49=== invalid-argument-handler
50
51<parameter>invalid-argument-handler</parameter>
52
53{{invalid-argument-handler}} is called when {{define-arguments}} encounters an
54invalid command-line value. It is a procedure of three arguments: an error
55message (string), option name (string or character) and value (a string or
56{{#t}}). By default, this procedure simply prints an error message and exits
57the program.
58
59=== unmatched-arguments
60
61<procedure>(unmatched-arguments)</procedure>
62
63Returns an alist of the command-line arguments unmatched by
64{{define-arguments}}. If called before {{define-arguments}}, it will return an
65empty list.
66
67== Examples
68
69<enscript highlight="scheme">
70(use easy-args extras)
71
72(define-arguments
73  (all-caps)
74  (prompt "Your name? ")
75  ((exclamations e) 1))
76
77(display (prompt))
78
79(let ((message (string-join `("Hello," ,(read-line)))))
80  (if (all-caps)
81    (display (string-upcase message))
82    (display message)))
83
84(print (make-string (exclamations) #\!))
85
86(if (not (null? (unmatched-arguments)))
87  (print (unmatched-arguments)))
88</enscript>
89
90With the file above as {{greeter.scm}}:
91
92  $ csc greeter.scm
93 
94  $ ./greeter
95  Your name? [Henrietta]
96  Hello, Henrietta!
97 
98  $ ./greeter --all-caps
99  Your name? [Henrietta]
100  HELLO, HENRIETTA!
101 
102  $ ./greeter --prompt 'Name: ' -e3
103  Name: [Henrietta]
104  Hello, Henrietta!!!
105 
106  $ ./greeter -w --unmatched=args
107  Your name? Henrietta
108  Hello, Henrietta!
109  ((w . #t) (unmatched . args))
110
111== History
112
113* 0.6 Deprecated
114* 0.5 Use srfi-37, getopt-style flags
115* 0.4 Allow symbols
116* 0.1 Initial release
117
118== Author
119
120[[/users/evan-hanson|Evan Hanson]]
121
122== License
123
124Public Domain
Note: See TracBrowser for help on using the repository browser.