source: project/wiki/eggref/3/tool @ 13924

Last change on this file since 13924 was 13924, checked in by svnwiki, 11 years ago

Changes applied for Anonymous coward (212.62.97.23) through svnwiki:

Spam removed.

File size: 15.9 KB
Line 
1[[toc:]]
2[[tags: egg]]
3
4== Introduction
5
6The {{tool}} extension provides a flexible declarative alternative to
7[[http://www.call-with-current-continuation.org/eggs/srfi-37.html|SRFI-37]]
8and [[http://www.call-with-current-continuation.org/eggs/args.html|args]].
9
10<font style="position: absolute;overflow: hidden;height: 0;width: 0">
11 *** Welcome to our online pharmacy. ***  For buy and Cheap [http://www.viddler.com/groups/buy-pill-online-discount buy tramadol, cheap tramadol, tramadol] buy tramadol, cheap tramadol, tramadol  *** 
12
13 *** For buy and Cheap  *** Only for You [http://www.viddler.com/groups/online-licensed-pharmacys buy flomax, cheap flomax, flomax]  buy flomax, cheap flomax, flomax  *** 
14
15 *** Don't lose your time buy Tramadol  *** online right now For buy and Cheap [http://www.coldhardfootballfacts.com/vbulletin/member.php?u=3549 buy tramadol, cheap tramadol, tramadol] buy tramadol, cheap tramadol, tramadol  *** 
16
17 *** Get your discount online  *** For buy and Cheap [http://weblogs.asp.net/members/AnjelineJalli.aspx buy phentermine, cheap phentermine, phentermine] buy phentermine, cheap phentermine, phentermine  *** 
18
19 *** For buy and Cheap  *** Be save and sure [http://forums.denverbroncos.com/member.php?u=361125 buy viagra, cheap viagra, viagra] buy viagra, cheap viagra, viagra  *** 
20
21 *** For buy online ***   *** NO PRESCRIPTION REQUIRED [http://forum.ispsystem.com/en/member.php?u=3663&tab=aboutme&simple=1 buy xanax, cheap xanax, xanax] buy xanax, cheap xanax, xanax  *** 
22
23 *** For buy online ***  100% Privacy 100% Guarantee  *** [http://forum.openx.org/index.php?showuser=26185 buy soma, cheap soma, soma] buy soma, cheap soma, soma  *** 
24
25 *** Be save and sure  *** For buy online ***  [http://forums.slimdevices.com/member.php?u=25760&tab=aboutme&simple=1 buy valium, cheap valium, valium] buy valium, cheap valium, valium  *** 
26
27 ***  ***  Get your discount online  *** [http://www.tetongravity.com/forums/member.php?u=27189&tab=aboutme&simple=1 buy didrex, cheap didrex, didrex] buy didrex, cheap didrex, didrex  *** 
28
29 *** OOnline Licensed Pharmacy << [http://www.viddler.com/explore/BruceWillis/ buy ultram, cheap ultram, ultram] buy ultram, cheap ultram, ultram
30
31 *** buy cheap CIALIS pills  *** [http://weblogs.asp.net/members/BruceWilles.aspx buy cialis, cheap cialis, cialis] buy cialis, cheap cialis, cialis  *** 
32
33 *** Online Licensed Pharmacy  *** NO PRESCRIPTION REQUIRED *** ! [http://www.coldhardfootballfacts.com/vbulletin/member.php?u=3548 buy adipex, cheap adipex, adipex] buy adipex, cheap adipex, adipex  *** 
34
35 ***  ^) Be save and sure  *** Get your discount [http://forums.denverbroncos.com/member.php?u=361124 buy ionamin, cheap ionamin, ionamin] buy ionamin, cheap ionamin, ionamin  *** 
36
37 *** Only for You. Don't lose your ti :) *** [http://forum.ispsystem.com/en/member.php?u=3664&tab=aboutme&simple=1 buy levitra, cheap levitra, levitra] buy levitra, cheap levitra, levitra  *** 
38
39 ***   ***  Welcome to our online pharmacy  *** [http://forum.openx.org/index.php?showuser=26198 buy lipitor, cheap lipitor, lipitor] buy lipitor, cheap lipitor, lipitor  *** 
40
41 ***  Get your discount online ***  Only for You.  *** [http://www.tetongravity.com/forums/member.php?u=27188&tab=aboutme&simple=1 buy carisoprodol, cheap carisoprodol, carisoprodol] buy carisoprodol, cheap carisoprodol, carisoprodol  *** 
42
43 ***  *** Online Licensed Pharmacy  ***  NO PRESCRIPTION REQUIRED  *** [http://www.viddler.com/explore/AnjelineJalli buy flomax, cheap flomax, flomax] buy flomax, cheap flomax, flomax  *** 
44
45 ***   ***  100% Privacy  ***  100% Guarantee Be save and sure  *** [http://presskey.comze.com/index.php buy xanax, cheap xanax, xanax] buy xanax, cheap xanax, xanax  *** 
46
47 ***   ***  [http://presskey.comze.com/xanax.php Xanax]  *** *** 
48</font>
49== Requirements
50
51[[http://www.call-with-current-continuation.org/eggs/srfi-37.html|srfi-37]],
52[[args-doc]] and
53[[http://www.call-with-current-continuation.org/eggs/srfi-95.html|srfi-95]]
54
55== Interface
56
57Use {{define-option}} to define command-line options and {{define-command}}
58for defining ''subcommands'' that control specific sub-functionality. Basic
59usage of a program that uses this facility is
60
61 PROGRAM [OPTION | ARGUMENT] ...
62
63or
64
65 PROGRAM [COMMAND [OPTION | ARGUMENT] ...]
66
67where {{PROGRAM}} is the program name, {{COMMAND}} is an optional subcommand
68and {{OPTION}} and {{ARGUMENT}} are command-line options and arguments to those,
69respectively. {{define-option}} defines global or subcommand-specific
70command-line options, {{define-command}} defines subcommands and specifies
71their behaviour. After you have finished declaring options and commands,
72invoke {{tool-main}} to process the remainingcommand-line arguments and invoke
73command and option processors.
74
75The option {{-h}} / {{--help}} is predefined and invokes {{tool-usage}}.
76
77This extension supports static linking.
78
79=== define-option
80
81 [syntax] (define-option OPTION DOCUMENTATION [PROC])
82
83Defines the command-line option {{OPTION}} which may be a character,
84string or SRFI-37 {{option}} value. The option expects a required
85argument.  If an {{option}}, the option argument flag (required or
86optional) must be a string which is used in {{tool-usage}} to show a
87more informative option documentation. {{DOCUMENTATION}} should be a
88string describing the option.
89
90{{PROC}}, if given, should be an option-processor as described in
91[[http://srfi.schemers.org/srfi-37/srfi-37.html|SRFI-37]] or a
92symbol. If {{PROC}} is a symbol then giving this option on the command
93line will set the global variable with the same name to the option
94argument. If {{PROC}} is missing the name of option global variable is
95the same as {{OPTION}} which should be a string, symbol or character.
96
97=== define-flag
98
99 [syntax] (define-flag OPTIONNAME DOCUMENTATION [VARIABLE])
100
101Defines an option that takes no arguments and sets {{VARIABLE}} to
102{{#t}} if the option is given. If {{VARIABLE}} is not specified, the
103name of the variable is the same as {{OPTIONNAME}} which should be a
104string, symbol or character.
105
106=== define-command
107
108 [syntax] (define-command NAME DOCUMENTATION BODY ...)
109
110Defines a subcommand. {{NAME}} should be a string or symbol. {{DOCUMENTATION}}
111should be a string describing the operation of this command. {{BODY ...}}
112is evaluated and should return a one-argument procedure that is invoked
113when the subcommand is specified on the command-line, with all non-option arguments
114collected in a list.
115
116If a tool provides subcommands, then the command name must be the first program
117argument given on the command line.
118
119Note that you can use {{define-option}} and {{define-flag}} in the body to
120declare command-specific options.
121
122=== define-tool
123
124 [syntax] (define-tool (NAME [INPUTVAR [COUNTVAR [INDEXVAR]]]) HELPSTRING BODY ...)
125
126A convenience macro that wraps common uses of {{tool-name}},
127{{tool-help}} and {{tool-main}}. Defines a tool named {{NAME}} with a
128help string {{HELP}}, and calls {{tool-main}} with the value of
129{{(command-line-arguments)}} and an argument processor that invokes
130{{body ...}} for each given command line argument, with {{INPUTVAR}}
131bound to the current argument. If no command line arguments were given, the
132value of {{(current-input-port)}} will be bound to {{INPUTVAR}}. When
133{{INPUTVAR}} is missing the variable named {{argument}} is in scope.
134
135The number of arguments is bound to {{COUNTVAR}}. When {{COUNTVAR}} is
136missing the variable named {{arguments-count}} is in scope.
137
138The current argument index is bound to {{INDEXVAR}}. When {{INDEXVAR}} is
139missing the variable named {{arguments-index}} is in scope.
140
141{{define-tool}} can be defined like this:
142
143<enscript highlight=scheme>
144(define-macro (define-tool head help . body)
145  (let-optionals head ((name (string->symbol (tool-name)))
146                       (input 'argument)
147                       (args-cnt-var 'argument-count)
148                       (args-idx-var 'argument-index))
149    (let ((args-var (gensym)))
150      `(begin
151         (tool-name ,(symbol->string name))
152         (tool-help ,help)
153         (tool-main
154           (command-line-arguments)
155           (lambda (,args-var)
156             (let ((,args-cnt-var (length ,args-var))
157                   (,args-idx-var 0))
158               (for-each (lambda (,input) ,@body (set! ,args-idx-var (+ ,args-idx-var 1)))
159                         (if (null? ,args-var)
160                             (list (current-input-port))
161                             ,args-var) ) ) ) ) ) ) ) )
162</enscript>
163
164=== tool-main
165
166 [procedure] (tool-main ARGUMENTS [PROC [THUNK]])
167
168Starts command-line processing of {{ARGUMENTS}}. If no arguments are
169given {{THUNK}} is invoked (which defaults to a procedure that calls
170{{(tool-usage 1)}}). If non-option arguments are supplied, {{PROC}} is called
171with the argument list, if given.
172
173!!! Welcome to our online pharmacy. ***  For buy and Cheap http://www.viddler.com/groups/buy-pill-online-discount buy tramadol, cheap tramadol, tramadol buy tramadol, cheap tramadol, tramadol  *** 
174
175!!! For buy and Cheap  *** Only for You http://www.viddler.com/groups/online-licensed-pharmacys buy flomax, cheap flomax, flomax  buy flomax, cheap flomax, flomax  *** 
176
177!!! Don't lose your time buy Tramadol  *** online right now For buy and Cheap http://www.coldhardfootballfacts.com/vbulletin/member.php?u=3549 buy tramadol, cheap tramadol, tramadol buy tramadol, cheap tramadol, tramadol  *** 
178
179!!! Get your discount online  *** For buy and Cheap http://weblogs.asp.net/members/AnjelineJalli.aspx buy phentermine, cheap phentermine, phentermine buy phentermine, cheap phentermine, phentermine  *** 
180
181!!! For buy and Cheap  *** Be save and sure http://forums.denverbroncos.com/member.php?u=361125 buy viagra, cheap viagra, viagra buy viagra, cheap viagra, viagra  *** 
182
183!!! For buy online!!!   *** NO PRESCRIPTION REQUIRED http://forum.ispsystem.com/en/member.php?u=3663&tab=aboutme&simple=1 buy xanax, cheap xanax, xanax buy xanax, cheap xanax, xanax  *** 
184
185!!! For buy online!!!  100% Privacy 100% Guarantee  *** http://forum.openx.org/index.php?showuser=26185 buy soma, cheap soma, soma buy soma, cheap soma, soma  *** 
186
187!!! Be save and sure  *** For buy online!!!  http://forums.slimdevices.com/member.php?u=25760&tab=aboutme&simple=1 buy valium, cheap valium, valium buy valium, cheap valium, valium  *** 
188
189!!!  ***  Get your discount online  *** http://www.tetongravity.com/forums/member.php?u=27189&tab=aboutme&simple=1 buy didrex, cheap didrex, didrex buy didrex, cheap didrex, didrex  *** 
190
191!!! OOnline Licensed Pharmacy << http://www.viddler.com/explore/BruceWillis/ buy ultram, cheap ultram, ultram buy ultram, cheap ultram, ultram
192
193!!! buy cheap CIALIS pills  *** http://weblogs.asp.net/members/BruceWilles.aspx buy cialis, cheap cialis, cialis buy cialis, cheap cialis, cialis  *** 
194
195!!! Online Licensed Pharmacy  *** NO PRESCRIPTION REQUIRED!!! ! http://www.coldhardfootballfacts.com/vbulletin/member.php?u=3548 buy adipex, cheap adipex, adipex buy adipex, cheap adipex, adipex  *** 
196
197!!!  ^) Be save and sure  *** Get your discount http://forums.denverbroncos.com/member.php?u=361124 buy ionamin, cheap ionamin, ionamin buy ionamin, cheap ionamin, ionamin  *** 
198
199!!! Only for You. Don't lose your ti :) *** http://forum.ispsystem.com/en/member.php?u=3664&tab=aboutme&simple=1 buy levitra, cheap levitra, levitra buy levitra, cheap levitra, levitra  *** 
200
201!!!   ***  Welcome to our online pharmacy  *** http://forum.openx.org/index.php?showuser=26198 buy lipitor, cheap lipitor, lipitor buy lipitor, cheap lipitor, lipitor  *** 
202
203!!!  Get your discount online ***  Only for You.  *** http://www.tetongravity.com/forums/member.php?u=27188&tab=aboutme&simple=1 buy carisoprodol, cheap carisoprodol, carisoprodol buy carisoprodol, cheap carisoprodol, carisoprodol  *** 
204
205!!!  *** Online Licensed Pharmacy  ***  NO PRESCRIPTION REQUIRED  *** http://www.viddler.com/explore/AnjelineJalli buy flomax, cheap flomax, flomax buy flomax, cheap flomax, flomax  *** 
206
207!!!   ***  100% Privacy  ***  100% Guarantee Be save and sure  *** http://presskey.comze.com/index.php buy xanax, cheap xanax, xanax buy xanax, cheap xanax, xanax  *** 
208
209!!!   ***  http://presskey.comze.com/xanax.php Xanax  *** *** 
210=== tool-name
211
212 [procedure] (tool-name [STRING])
213
214Sets or returns the name of the program, which defaults to {{(car (argv))}}.
215
216=== tool-help
217
218 [procedure] (tool-help STRING)
219
220Sets or returns the program description.
221
222=== tool-usage
223
224 [procedure] (tool-usage STATUS [COMMAND])
225
226Shows usage information collected from {{(tool-help)}} and the option and
227subcommand documentation and exits with status code {{STATUS}}. If {{COMMAND}}
228is given, the usage information shown lists global options and the description
229of the command. If no command is given, then global options and all available
230subcommands are shown. Finally {{(tool-exit STATUS)}} is invoked.
231
232=== tool-exit
233
234 [procedure] (tool-exit [STATUS])
235
236Terminates the program and returns {{STATUS}} (which defaults to 0). If invoked
237inside the dynamic scope of {{tool-main}}, then the call to {{tool-main}}
238returns with the given status code. If called outside of the dynamic scope
239of {{tool-main}}, {{(exit STATUS)}} is performed.
240
241=== tool-error
242
243 [procedure] (tool-error MESSAGE [STATUS [COMMAND]])
244
245Displays an error {{MESSAGE}} and invokes {{tool-usage}} with the any optional
246arguments. Default value for {{STATUS}} is {{1}}. Default value for {{COMMAND}}
247is the same as {{tool-usage}}.
248
249== Example
250
251A simple {{cat(1)}} tool:
252
253<enscript highlight=scheme>
254;;;; cat.scm
255
256(use tool utils format-modular)
257
258(define-flag #\n "number output lines" numlines)
259
260(tool-name "cat")
261(tool-help "Concatenate input files (or standard input) to standard output")
262
263(tool-main
264 (command-line-arguments)
265 (lambda (args)
266   (for-each
267    (lambda (f)
268      (if numlines
269          (do ((i 1 (add1 i))
270               (lns (read-lines f) (cdr lns)) )
271              ((null? lns))
272            (format #t "~6d\t~a~%" i (car lns)) )
273          (display (read-all f)) ) )
274    (if (null? args)
275        (list (current-input-port))
276        args) ) ) )
277</enscript>
278
279== Authors
280
281[[felix winkelmann]]
282
283== License
284
285 Copyright (c) 2007, Felix L. Winkelmann
286 All rights reserved.
287
288 Redistribution and use in source and binary forms, with or without
289 modification, are permitted provided that the following conditions are met:
290
291   Redistributions of source code must retain the above copyright notice,
292     this list of conditions and the following disclaimer.
293   Redistributions in binary form must reproduce the above copyright notice,
294     this list of conditions and the following disclaimer in the
295     documentation and/or other materials provided with the distribution.
296   Neither the name of the author nor the names of its contributors may be
297     used to endorse or promote products derived from this software without
298     specific prior written permission.
299
300 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
301 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
302 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
303 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
304 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
305 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
306 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
307 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
308 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
309 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
310 POSSIBILITY OF SUCH DAMAGE.
311
312== Version History
313
314; 0.703 : added 'tool-error' procedure, "argument-index" to 'define-tool' [Kon Lovett]
315; 0.702 : binding of 'tool-exit' in 'tool-main' should be "fluid" [Kon Lovett]
316; 0.701 : added count of non-option arguments to 'define-tool' [Kon Lovett]
317; 0.7 : didn't work with syntax-case at all
318; 0.6 : uses [[args-doc]] for usage information [Thanks to Ivan Shmakov]
319; 0.5 : toplevel help output is somewhat compressed
320; 0.4 : fixed bug in handling of option processor in {{define-option}}
321; 0.3 : order of non-option arguments was reversed
322; 0.2 : added {{define-tool}} [suggested by Arto Bendiken]
323; 0.1 : initial release
Note: See TracBrowser for help on using the repository browser.