getopt-declare 1.09.7 → 1.12
Sign up to get free protection for your applications and to get access to all the features.
- data/Declare.rdoc +1861 -0
- data/HISTORY.txt +10 -0
- data/getoptdeclare.gemspec +22 -0
- data/lib/Getopt/Declare.rb +53 -39
- data/lib/Getopt/DelimScanner.rb +3 -3
- data/samples/cmdline_array.rb +26 -25
- data/samples/cmdline_basic.rb +31 -31
- data/samples/cmdline_code.rb +31 -31
- data/samples/cmdline_defer.rb +23 -23
- data/samples/cmdline_file.rb +38 -38
- data/samples/cmdline_finish.rb +14 -0
- data/samples/cmdline_inlines.rb +27 -24
- data/samples/cmdline_mid.rb +39 -39
- data/samples/cmdline_noargv.rb +29 -29
- data/samples/cmdline_parameters.rb +23 -23
- data/samples/cmdline_pvtype.rb +20 -20
- data/samples/cmdline_pvtype2.rb +20 -20
- data/samples/cmdline_regex.rb +27 -27
- data/samples/cmdline_singles.rb +28 -28
- data/samples/demo_cmdline.rb +70 -70
- data/samples/demo_csv.rb +49 -49
- data/samples/demo_interp.rb +44 -44
- data/samples/demo_shell.rb +37 -37
- metadata +31 -24
data/Declare.rdoc
ADDED
@@ -0,0 +1,1861 @@
|
|
1
|
+
#
|
2
|
+
# = NAME
|
3
|
+
#
|
4
|
+
# Getopt::Declare - Declaratively Expressed Command-Line Arguments via Regular Expressions
|
5
|
+
#
|
6
|
+
# = VERSION
|
7
|
+
#
|
8
|
+
# This document describes version 1.09 of Getopt::Declare,
|
9
|
+
# released May 21, 1999 for Perl.
|
10
|
+
# Released Jan 15, 2003 for Ruby.
|
11
|
+
#
|
12
|
+
# = SYNOPSIS
|
13
|
+
#
|
14
|
+
# require "Getopt/Declare"
|
15
|
+
# args = Getopt::Declare.new(specification_string, optional_source);
|
16
|
+
#
|
17
|
+
#
|
18
|
+
# = DESCRIPTION
|
19
|
+
#
|
20
|
+
# == Overview
|
21
|
+
#
|
22
|
+
# Getopt::Declare is <em>yet another</em> command-line argument parser,
|
23
|
+
# one which is specifically designed to be powerful but exceptionally
|
24
|
+
# easy to use.
|
25
|
+
#
|
26
|
+
# To parse the command-line in +ARGV+, one simply creates a
|
27
|
+
# Getopt::Declare object, by passing Getopt::Declare::new() a
|
28
|
+
# specification of the various parameters that may be encountered:
|
29
|
+
#
|
30
|
+
# args = Getopt::Declare.new(specification)
|
31
|
+
#
|
32
|
+
# The specification is a single string such as this:
|
33
|
+
#
|
34
|
+
# specification = %q(
|
35
|
+
#
|
36
|
+
# -a Process all data
|
37
|
+
#
|
38
|
+
# -b <t:n> Set mean byte length threshold to <t>
|
39
|
+
# { bytelen = t }
|
40
|
+
#
|
41
|
+
# +c <FILE> Create new file <FILE>
|
42
|
+
#
|
43
|
+
# --del Delete old file
|
44
|
+
# { delold() }
|
45
|
+
#
|
46
|
+
# delete [ditto]
|
47
|
+
#
|
48
|
+
# e <h:i>x<w:i> Expand image to height <h> and width <w>
|
49
|
+
# { expand(h,w) }
|
50
|
+
#
|
51
|
+
# -F <file>... Process named file(s)
|
52
|
+
# { defer { file.each {|i|
|
53
|
+
# process(i) } } }
|
54
|
+
#
|
55
|
+
# =getrand [<n:i>] Get a random number
|
56
|
+
# (or, optionally, <n> of them)
|
57
|
+
# { n = 1 unless !n.empty? }
|
58
|
+
#
|
59
|
+
# -- Traditionally indicates end of arguments
|
60
|
+
# { finish(1) }
|
61
|
+
# )
|
62
|
+
#
|
63
|
+
# in which the syntax of each parameter is declared, along with a
|
64
|
+
# description and (optionally) one or more actions to be performed when
|
65
|
+
# the parameter is encountered. The specification string may also
|
66
|
+
# include other usage formatting information (such as group headings or
|
67
|
+
# separators) as well as standard Ruby comments (which are ignored).
|
68
|
+
#
|
69
|
+
# Calling Getopt::Delare::new() parses the contents of the array +ARGV+,
|
70
|
+
# extracting any arguments which match the parameters defined in the
|
71
|
+
# specification string, and storing the parsed values as hash elements
|
72
|
+
# within the new Getopt::Declare object being created.
|
73
|
+
#
|
74
|
+
# Other features of the Getopt::Declare package include:
|
75
|
+
#
|
76
|
+
# * The use of full Ruby regular expressions to constrain matching
|
77
|
+
# of parameter components.
|
78
|
+
#
|
79
|
+
# * Automatic generation of error, usage and version information.
|
80
|
+
#
|
81
|
+
# * Optional conditional execution of embedded actions (i.e. only on
|
82
|
+
# successful parsing of the entire command-line)
|
83
|
+
#
|
84
|
+
# * Strict or non-strict parsing (unrecognized command-line elements may either
|
85
|
+
# trigger an error or may simply be left in +ARGV+
|
86
|
+
#
|
87
|
+
# * Declarative specification of various inter-parameter relationships (for
|
88
|
+
# example, two parameters may be declared mutually exclusive and this
|
89
|
+
# relationship will then be automatically enforced).
|
90
|
+
#
|
91
|
+
# * Intelligent clustering of adjacent flags (for example: the
|
92
|
+
# command-line sequence "-a -b -c" may be abbreviated to "-abc", unless
|
93
|
+
# there is also a <tt>-abc</tt> flag declared).
|
94
|
+
#
|
95
|
+
# * Selective or global case-insensitivity of parameters.
|
96
|
+
#
|
97
|
+
# * The ability to parse files (especially configuration files) instead of
|
98
|
+
# the command-line.
|
99
|
+
#
|
100
|
+
# == Terminology
|
101
|
+
#
|
102
|
+
# The terminology of command-line processing is often confusing, with various
|
103
|
+
# terms (such as "argument", "parameter", "option", "flag", etc.)
|
104
|
+
# frequently being used interchangeably and inconsistently in the various
|
105
|
+
# Getopt packages available. In this documentation, the following
|
106
|
+
# terms are used consistently:
|
107
|
+
#
|
108
|
+
# * <b>"command-line"</b>
|
109
|
+
#
|
110
|
+
# The space-separated concatenation of the elements of the array +ARGV+
|
111
|
+
# at the time a Getopt::Declare object is created.
|
112
|
+
#
|
113
|
+
# * <b>"parameter specification" (or just "parameter")</b>
|
114
|
+
#
|
115
|
+
# A specification of a single entity which may appear in the
|
116
|
+
# command-line. Always includes at least one syntax for the entity.
|
117
|
+
# Optionally may include other _variant>_ syntaxes, one or more
|
118
|
+
# _descriptions_ of the entity, and/or _actions_ to be performed when
|
119
|
+
# the entity is encountered. For example, the following is a single
|
120
|
+
# parameter specification (with two variants):
|
121
|
+
#
|
122
|
+
# --window <height> x <width> Set window to <height> by <width>
|
123
|
+
# { setwin(width,height) }
|
124
|
+
#
|
125
|
+
# --window <h>x<w>@<x>,<y> Set window size and centroid
|
126
|
+
# { setwin(w,h,x,y) }
|
127
|
+
#
|
128
|
+
#
|
129
|
+
# * <b>"argument"</b>
|
130
|
+
#
|
131
|
+
# A substring of the command-line which matches a single parameter variant.
|
132
|
+
# Unlike some other Getopt packages, in Getopt::Declare an argument
|
133
|
+
# may be a single element of +ARGV+, or part of a single +ARGV+ element,
|
134
|
+
# or the concatenation of several adjacent +ARGV+ elements.
|
135
|
+
#
|
136
|
+
#
|
137
|
+
# * <b>"parameter definition"</b>
|
138
|
+
#
|
139
|
+
# A specification of one actual syntax variant matched by a parameter. Always
|
140
|
+
# consists of a leading _parameter_ _flag_ or _parameter_ _variable_,
|
141
|
+
# optionally followed by one or more _parameter_ _components_ (that is,
|
142
|
+
# other parameter variables or _punctuators_. In the above example,
|
143
|
+
# <tt>--window <height> x <width></tt> is a parameter definition.
|
144
|
+
#
|
145
|
+
#
|
146
|
+
# * <b>"parameter flag" (or just "flag")</b>
|
147
|
+
#
|
148
|
+
# A sequence of non-space characters which introduces a parameter. Traditionally
|
149
|
+
# a parameter flag begins with "-" or "--", but Getopt::Declare allows
|
150
|
+
# almost any sequence of characters to be used as a flag. In the above example,
|
151
|
+
# <tt>--window</tt> is the parameter flag.
|
152
|
+
#
|
153
|
+
#
|
154
|
+
# * <b>"parameter variable"</b>
|
155
|
+
#
|
156
|
+
# A place-holder (within a parameter specification) for a value that
|
157
|
+
# will appear in any argument matching that parameter. In the above example,
|
158
|
+
# <tt>-height</tt>, <tt>-width</tt>, <tt>-h</tt>, <tt>-w</tt>, <tt>-x</tt>, and <tt>-y</tt> are
|
159
|
+
# all parameter variables.
|
160
|
+
#
|
161
|
+
#
|
162
|
+
# * <b>"parameter punctuator" (or just "punctuator")</b>
|
163
|
+
#
|
164
|
+
# A literal sequence of characters (within a parameter specification)
|
165
|
+
# which will appear in any argument matching that parameter. In the above
|
166
|
+
# example, the literals +x+ and <tt>@</tt> are punctuators.
|
167
|
+
#
|
168
|
+
#
|
169
|
+
# * <b>"parameter description"</b>
|
170
|
+
#
|
171
|
+
# A textual description of the purpose and/or use of a particular variant of
|
172
|
+
# parameter. In the above examples, the string:
|
173
|
+
#
|
174
|
+
# Set window to <height> by <width>
|
175
|
+
#
|
176
|
+
# is a parameter description.
|
177
|
+
#
|
178
|
+
#
|
179
|
+
# * <b>"parameter action" (or just "action")</b>
|
180
|
+
#
|
181
|
+
# A block of Ruby code to be executed in response to encountering a specific
|
182
|
+
# parameter. In the above example:
|
183
|
+
#
|
184
|
+
# { setwin(width,height) }
|
185
|
+
#
|
186
|
+
# is a parameter action.
|
187
|
+
#
|
188
|
+
# * <b>"parameter variants"</b>
|
189
|
+
#
|
190
|
+
# One or more different syntaxes for a single parameter, all sharing
|
191
|
+
# the same leading flag, but having different trailing parameter
|
192
|
+
# variables and/or punctuators. Getopt::Declare considers all parameter
|
193
|
+
# definitions with the same leading flag to be merely variant forms of
|
194
|
+
# a single "underlying" parameter. The above example shows two parameter
|
195
|
+
# variants for the <tt>--window</tt> parameter.
|
196
|
+
#
|
197
|
+
#
|
198
|
+
# == Parameter definitions
|
199
|
+
#
|
200
|
+
# As indicated above, a parameter specification consists of three
|
201
|
+
# parts: the parameter definition, a textual description, and any
|
202
|
+
# actions to be performed when the parameter is matched.
|
203
|
+
#
|
204
|
+
# The parameter definition consists of a leading flag or parameter
|
205
|
+
# variable, followed by any number of parameter variables or
|
206
|
+
# punctuators, optionally separated by spaces. The parameter definition
|
207
|
+
# is terminated by one or more tabs (at least one trailing tab _must_
|
208
|
+
# be present).
|
209
|
+
#
|
210
|
+
# For example, all of the following are valid Getopt::Declare parameter
|
211
|
+
# definitions:
|
212
|
+
#
|
213
|
+
# -v
|
214
|
+
# in=<infile>
|
215
|
+
# +range <from>..<to>
|
216
|
+
# --lines <start> - <stop>
|
217
|
+
# ignore bad lines
|
218
|
+
# <outfile>
|
219
|
+
#
|
220
|
+
# Note that each of the above examples has at least one trailing tab
|
221
|
+
# (even if you can't see them). Note too that this hodge-podge of
|
222
|
+
# parameter styles is certainly not recommended within a single program,
|
223
|
+
# but is shown so as to illustrate some of the range of parameter syntax
|
224
|
+
# conventions Getopt::Declare supports.
|
225
|
+
#
|
226
|
+
# The spaces between components of the parameter definition are optional but
|
227
|
+
# significant, both in the definition itself and in the arguments that
|
228
|
+
# the definition may match. If there is no space between components in the
|
229
|
+
# specification, then no space is allowed between corresponding arguments
|
230
|
+
# on the command-line. If there _is_ space between components of the
|
231
|
+
# specification, then space between those components is optional on the
|
232
|
+
# command-line.
|
233
|
+
#
|
234
|
+
# For example, the <tt>--lines</tt> parameter above matches:
|
235
|
+
#
|
236
|
+
# --lines1-10
|
237
|
+
# --lines 1-10
|
238
|
+
# --lines 1 -10
|
239
|
+
# --lines 1 - 10
|
240
|
+
# --lines1- 10
|
241
|
+
#
|
242
|
+
# If it were instead specified as:
|
243
|
+
#
|
244
|
+
# --lines <start>-<stop>
|
245
|
+
#
|
246
|
+
# then it would match only:
|
247
|
+
#
|
248
|
+
# --lines1-10
|
249
|
+
# --lines 1-10
|
250
|
+
#
|
251
|
+
# Note that the optional nature of spaces in parameter specification implies that
|
252
|
+
# flags and punctuators cannot contain the character '<' (which is taken as the
|
253
|
+
# delimiter for a parameter variable) nor the character '[' (which
|
254
|
+
# introduces an optional parameter component - see
|
255
|
+
# "Optional parameter components".
|
256
|
+
#
|
257
|
+
#
|
258
|
+
# == Types of parameter variables
|
259
|
+
#
|
260
|
+
# By default, a parameter variable will match a single blank-terminated
|
261
|
+
# or comma-delimited string. For example, the parameter:
|
262
|
+
#
|
263
|
+
# -val <value>
|
264
|
+
#
|
265
|
+
# would match any of the following the arguments:
|
266
|
+
#
|
267
|
+
# -value # <value> <- "ue"
|
268
|
+
# -val abcd # <value> <- "abcd"
|
269
|
+
# -val 1234 # <value> <- "1234"
|
270
|
+
# -val "a value" # <value> <- "a value"
|
271
|
+
#
|
272
|
+
#
|
273
|
+
# It is also possible to restrict the types of values which may be
|
274
|
+
# matched by a given parameter variable. For example:
|
275
|
+
#
|
276
|
+
# -limit <threshold:n> Set threshold to some (real) value
|
277
|
+
# -count <N:i> Set count to <N> (must be an integer)
|
278
|
+
#
|
279
|
+
# If a parameter variable is suffixed with ":n", it will match any
|
280
|
+
# reasonable numeric value, whilst the ":i" suffix restricts a
|
281
|
+
# parameter variable to only matching integer values.
|
282
|
+
# These two "type specifiers" are the simplest examples of a much more
|
283
|
+
# powerful mechanism, which allows parameter variables to be restricted
|
284
|
+
# to matching any specific regular expression. See "Defining new
|
285
|
+
# parameter variable types".
|
286
|
+
#
|
287
|
+
# Parameter variables are treated as scalars by default, but this too
|
288
|
+
# can be altered. Any parameter variable immediately followed by
|
289
|
+
# an ellipsis (<tt>...</tt>) is treated as a list variable, and matches its
|
290
|
+
# specified type sequentially as many times as possible. For example,
|
291
|
+
# the parameter specification:
|
292
|
+
#
|
293
|
+
# -pages <page:i>...
|
294
|
+
#
|
295
|
+
# would match either of the following arguments:
|
296
|
+
#
|
297
|
+
# -pages 1
|
298
|
+
# -pages 1 2 7 20
|
299
|
+
#
|
300
|
+
# Note that both scalar and list parameter variables are "respectful" of the
|
301
|
+
# flags of other parameters as well as their own trailing punctuators.
|
302
|
+
# For example, given the specifications:
|
303
|
+
#
|
304
|
+
# -a
|
305
|
+
# -b <b_list>...
|
306
|
+
# -c <c_list>... ;
|
307
|
+
#
|
308
|
+
# The following arguments will be parsed as indicated:
|
309
|
+
#
|
310
|
+
# -b -d -e -a # <b_list> <- ("-d", "-e")
|
311
|
+
# -b -d ; # <b_list> <- ("-d", ";")
|
312
|
+
# -c -d ; # <c_list> <- ("-d")
|
313
|
+
#
|
314
|
+
# List parameter variables are also "repectful" of the needs of
|
315
|
+
# subsequent parameter variables. That is, a parameter specification
|
316
|
+
# like:
|
317
|
+
#
|
318
|
+
# -copy <files>... <dir>
|
319
|
+
#
|
320
|
+
# will behave as expected, putting all but the last string after the
|
321
|
+
# <tt>-copy</tt> flag into the parameter variable <tt>files</tt>, while
|
322
|
+
# the very last string is assigned to <tt>dir</tt>.
|
323
|
+
#
|
324
|
+
#
|
325
|
+
# == Optional parameter components
|
326
|
+
#
|
327
|
+
# Except for the leading flag, any part of a parameter definition
|
328
|
+
# may be made optional by placing it in square brackets.
|
329
|
+
# For example:
|
330
|
+
#
|
331
|
+
# +range <from> [..] [<to>]
|
332
|
+
#
|
333
|
+
# which matches any of:
|
334
|
+
#
|
335
|
+
# +range 1..10
|
336
|
+
# +range 1..
|
337
|
+
# +range 1 10
|
338
|
+
# +range 1
|
339
|
+
#
|
340
|
+
# List parameter variables may also be made optional (the ellipsis must
|
341
|
+
# follow the parameter variable name immediately, so it goes _inside_
|
342
|
+
# the square brackets):
|
343
|
+
#
|
344
|
+
# -list [<page>...]
|
345
|
+
#
|
346
|
+
# Two or more parameter components may be made jointly optional, by specifying
|
347
|
+
# them in the same pair of brackets. Optional components may also be nested. For
|
348
|
+
# example:
|
349
|
+
#
|
350
|
+
# -range <from> [.. [<to>] ]
|
351
|
+
#
|
352
|
+
# Scalar optional parameter variables (such as [<tt>to</tt>]>)
|
353
|
+
# are given undefined values if they are skipped during a successful
|
354
|
+
# parameter match. List optional parameter variables (such as
|
355
|
+
# [<tt>page</tt>...]) are assigned an empty list if unmatched.
|
356
|
+
#
|
357
|
+
# One important use for optional punctuators is to provide abbreviated
|
358
|
+
# versions of specific flags. For example:
|
359
|
+
#
|
360
|
+
# -num[eric] # Match "-num" or "-numeric"
|
361
|
+
# -lexic[ographic]al # Match "-lexical" or "-lexicographical"
|
362
|
+
# -b[ells+]w[histles] # Match "-bw" or "-bells+whistles"
|
363
|
+
#
|
364
|
+
# Note that the actual flags for these three parameters are <tt>-num</tt>,
|
365
|
+
# <tt>-lexic</tt> and <tt>-b</tt>, respectively.
|
366
|
+
#
|
367
|
+
# == Parameter descriptions
|
368
|
+
#
|
369
|
+
# Providing a textual description for each parameter (or parameter
|
370
|
+
# variant) is optional, but strongly recommended. Apart from providing
|
371
|
+
# internal documentation, parameter descriptions are used in the
|
372
|
+
# automatically-generated usage information provided by Getopt::Declare.
|
373
|
+
#
|
374
|
+
# Descriptions may be placed after the tab(s) following the
|
375
|
+
# parameter definition and may be continued on subsequent lines,
|
376
|
+
# provided those lines do not contain any tabs after the first
|
377
|
+
# non-whitespace character (because any such line will instead be
|
378
|
+
# treated as a new parameter specification). The description is
|
379
|
+
# terminated by a blank line, an action specification (see below) or
|
380
|
+
# another parameter specification.
|
381
|
+
#
|
382
|
+
# For example:
|
383
|
+
#
|
384
|
+
# -v Verbose mode
|
385
|
+
# in=<infile> Specify input file
|
386
|
+
# (will fail if file does not exist)
|
387
|
+
#
|
388
|
+
# +range <from>..<to> Specify range of columns to consider
|
389
|
+
# --lines <start> - <stop> Specify range of lines to process
|
390
|
+
#
|
391
|
+
# ignore bad lines Ignore bad lines :-)
|
392
|
+
#
|
393
|
+
# <outfile> Specify an output file
|
394
|
+
#
|
395
|
+
# The parameter description may also contain special directives which
|
396
|
+
# alter the way in which the parameter is parsed. See the various
|
397
|
+
# subsections of "ADVANCED FEATURES" for more information.
|
398
|
+
#
|
399
|
+
#
|
400
|
+
# == Actions
|
401
|
+
#
|
402
|
+
# Each parameter specification may also include one or more blocks of
|
403
|
+
# Ruby code, specified in a pair of curly brackets (which _must_ start on
|
404
|
+
# a new line).
|
405
|
+
#
|
406
|
+
# Each action is executed as soon as the corresponding parameter is
|
407
|
+
# successfully matched in the command-line (but see "Deferred actions"
|
408
|
+
# for a means of delaying this response).
|
409
|
+
#
|
410
|
+
# For example:
|
411
|
+
#
|
412
|
+
# -v Verbose mode
|
413
|
+
# { $verbose = 1 }
|
414
|
+
# -q Quiet mode
|
415
|
+
# { $verbose = 0 }
|
416
|
+
#
|
417
|
+
# Actions are executed (as +begin+ blocks) in the package in which the
|
418
|
+
# Getopt::Declare object containing them was created. Hence they
|
419
|
+
# have access to all package variables and functions in that namespace.
|
420
|
+
#
|
421
|
+
# In addition, each parameter variable belonging to the corresponding
|
422
|
+
# parameter is made available as a (block-scoped) Ruby variable with the
|
423
|
+
# same name. For example:
|
424
|
+
#
|
425
|
+
# +range <from>..<to> Set range
|
426
|
+
# { setrange($from, $to) }
|
427
|
+
#
|
428
|
+
# -list <page:i>... Specify pages to list
|
429
|
+
# { page.each { |i|
|
430
|
+
# list(i) if i > 0
|
431
|
+
# }
|
432
|
+
# }
|
433
|
+
#
|
434
|
+
# Note that single parameter variables become scalar Ruby variables,
|
435
|
+
# all matching their type (Fixnum, Float, String) and list parameter
|
436
|
+
# variables become Ruby arrays.
|
437
|
+
#
|
438
|
+
#
|
439
|
+
# == Predefined variables available in actions
|
440
|
+
#
|
441
|
+
# Within an action the following variables are also available:
|
442
|
+
#
|
443
|
+
# * <tt>\_PARAM_</tt> String
|
444
|
+
#
|
445
|
+
# Stores the identifier of the current parameter: either the leading
|
446
|
+
# flag or, if there is no leading flag, the name of the first parameter
|
447
|
+
# variable.
|
448
|
+
#
|
449
|
+
# * <tt>\_PUNCT_</tt> Hash
|
450
|
+
#
|
451
|
+
# Stores the substring matched by each punctuator in the current parameter.
|
452
|
+
# The hash is indexed by the punctuator itself. The main purpose of this
|
453
|
+
# variable is to allow actions to check whether optional punctuators were
|
454
|
+
# in fact matched.
|
455
|
+
#
|
456
|
+
# For example:
|
457
|
+
#
|
458
|
+
# -v[erbose] Set verbose mode
|
459
|
+
# (doubly verbose if full word used)
|
460
|
+
# { if _PUNCT_["erbose"]
|
461
|
+
# verbose = 2
|
462
|
+
# else
|
463
|
+
# verbose = 1
|
464
|
+
# end
|
465
|
+
# }
|
466
|
+
#
|
467
|
+
# * <tt>\_FOUND_</tt> Hash
|
468
|
+
#
|
469
|
+
# This hash stores boolean values indicating whether or not a given
|
470
|
+
# parameter has already been found. The hash keys are the leading flags
|
471
|
+
# or parameter variables of each parameter. For instance, the following
|
472
|
+
# specification makes the <tt>-q</tt> and <tt>-v</tt> parameters mutually
|
473
|
+
# exclusive (but see "Parameter dependencies" for a _much_ easier way
|
474
|
+
# to achieve this effect):
|
475
|
+
#
|
476
|
+
# -v Set verbose mode
|
477
|
+
# { raise "Can't be verbose *and* quiet!\n" if
|
478
|
+
# _FOUND_["-q"]
|
479
|
+
# }
|
480
|
+
#
|
481
|
+
# -q Set quiet mode
|
482
|
+
# { raise "Can't be quiet *and* verbose!\n" if
|
483
|
+
# _FOUND_["-v"]
|
484
|
+
# }
|
485
|
+
#
|
486
|
+
# For reasons that will be explained in "Rejection and termination",
|
487
|
+
# a given parameter is not marked as found until _after_ its
|
488
|
+
# associated actions are executed. That is, <tt>_FOUND_[\_PARAM_]</tt> will not
|
489
|
+
# (usually) be true during a parameter action.
|
490
|
+
#
|
491
|
+
#
|
492
|
+
# Note that, although numerous other internal variables on which the
|
493
|
+
# generated parser relies are also visible within parameter actions,
|
494
|
+
# accessing any of them may have Dire Consequences. Moreover, these
|
495
|
+
# other variables may no longer be accessible (or even present) in
|
496
|
+
# future versions of Getopt::Declare. All such internal variables
|
497
|
+
# have names beginning with an underscore. Avoiding such variables names
|
498
|
+
# will ensure there are no conflicts between actions and the parser
|
499
|
+
# itself.
|
500
|
+
#
|
501
|
+
#
|
502
|
+
# == The command-line parsing process
|
503
|
+
#
|
504
|
+
# Whenever a Getopt::Declare object is created, the current command-line
|
505
|
+
# is parsed by sequentially, by attempting to match each parameter
|
506
|
+
# in the object's specification string against the current elements in the
|
507
|
+
# +ARGV+ array (but see "Parsing from other sources"). The order
|
508
|
+
# in which parameters are tried against +ARGV+ is determined by
|
509
|
+
# three rules:
|
510
|
+
#
|
511
|
+
# 1. Parameters with longer flags are tried first. Hence the command-line
|
512
|
+
# argument "-quiet" would be parsed as matching the parameter
|
513
|
+
# <tt>-quiet</tt> rather than the parameter <tt>-q <string></tt>, even
|
514
|
+
# if the <tt>-q</tt> parameter was defined first.
|
515
|
+
#
|
516
|
+
# 2. Parameter _variants_ with the most components are
|
517
|
+
# matched first. Hence the argument "-rand 12345" would be parsed as
|
518
|
+
# matching the parameter variant <tt>-rand <seed></tt>, rather than the
|
519
|
+
# variant <tt>-rand</tt>, even if the "shorter" <tt>-rand</tt> variant
|
520
|
+
# was defined first.
|
521
|
+
#
|
522
|
+
# 3. Otherwise, parameters are matched in the order they are defined.
|
523
|
+
#
|
524
|
+
# Elements of +ARGV+ which do not match any defined parameter are collected
|
525
|
+
# during the parse and are eventually put back into +ARGV+
|
526
|
+
# (see "Strict and non-strict command-line parsing").
|
527
|
+
#
|
528
|
+
#
|
529
|
+
# = ADVANCED FEATURES
|
530
|
+
#
|
531
|
+
# == Case-insensitive parameter matching
|
532
|
+
#
|
533
|
+
# By default, a Getopt::Declare object parses the command-line in
|
534
|
+
# a <em>case-sensitive</em> manner. The <tt>[nocase]</tt> directive enables
|
535
|
+
# a specific parameter (or, alternatively, _all_ parameters) to be matched
|
536
|
+
# case-insensitively.
|
537
|
+
#
|
538
|
+
# If a <tt>nocase]</tt> directive is included in the description of a
|
539
|
+
# specific parameter variant, then that variant (only) will be matched
|
540
|
+
# without regard for case. For example, the specification:
|
541
|
+
#
|
542
|
+
# -q Quiet mode [nocase]
|
543
|
+
#
|
544
|
+
# -v Verbose mode
|
545
|
+
#
|
546
|
+
# means that the arguments "-q" and "-Q" will both match the <tt>-q</tt> parameter, but
|
547
|
+
# that only "-v" (and _not_ "-V") will match the <tt>-v</tt> parameter.
|
548
|
+
#
|
549
|
+
# If a <tt>[nocase]</tt> directive appears anywhere _outside_ a parameter
|
550
|
+
# description, then the entire specification is declared case-insensitive
|
551
|
+
# and all parameters defined in that specification are matched without
|
552
|
+
# regard to case.
|
553
|
+
#
|
554
|
+
#
|
555
|
+
# == Termination and rejection
|
556
|
+
#
|
557
|
+
# It is sometimes useful to be able to terminate command-line
|
558
|
+
# processing before all arguments have been parsed. To this end,
|
559
|
+
# Getopt::Declare provides a special local operator (+finish+) which
|
560
|
+
# may be used within actions. The +finish+ operator takes a single optional
|
561
|
+
# argument. If the argument is true (or omitted),
|
562
|
+
# command-line processing is terminated at once (although the current
|
563
|
+
# parameter is still marked as having been successfully matched). For
|
564
|
+
# example:
|
565
|
+
#
|
566
|
+
# -- Traditional argument list terminator
|
567
|
+
# { finish }
|
568
|
+
#
|
569
|
+
# -no-- Use non-traditional terminator instead
|
570
|
+
# { nontrad = 1 }
|
571
|
+
#
|
572
|
+
# ## Non-traditional terminator (only valid if -no-- flag seen)
|
573
|
+
# { finish(nontrad) }
|
574
|
+
#
|
575
|
+
# It is also possible to reject a single parameter match from within an
|
576
|
+
# action (and then continue trying other candidates). This allows
|
577
|
+
# actions to be used to perform more sophisticated tests on the type of
|
578
|
+
# a parameter variable, or to implement complicated parameter
|
579
|
+
# interdependencies.
|
580
|
+
#
|
581
|
+
# To reject a parameter match, the +reject+ operator is used. The
|
582
|
+
# +reject+ operator takes an optional argument.
|
583
|
+
# If the argument is true (or was omitted), the current parameter
|
584
|
+
# match is immediately rejected. For example:
|
585
|
+
#
|
586
|
+
# -ar <r:n> Set aspect ratio (must be in the range [0..1])
|
587
|
+
# {
|
588
|
+
# $sawaspect += 1
|
589
|
+
# reject( r <= 0 || r > 1 )
|
590
|
+
# setaspect(r)
|
591
|
+
# }
|
592
|
+
#
|
593
|
+
# -q Quiet option (not available on Wednesdays)
|
594
|
+
# {
|
595
|
+
# reject(Time.new.localtime.day == 3)
|
596
|
+
# $verbose = 0
|
597
|
+
# }
|
598
|
+
#
|
599
|
+
# Note that any actions performed _before_ the call to +reject+ will
|
600
|
+
# still have effect (for example, the variable <tt>$sawaspect</tt> remains
|
601
|
+
# incremented even if the aspect ratio parameter is subsequently rejected).
|
602
|
+
#
|
603
|
+
# The +reject+ operator may also take a second argument, which is
|
604
|
+
# used as an error message if the rejected argument subsequently
|
605
|
+
# fails to match any other parameter. For example:
|
606
|
+
#
|
607
|
+
# -q Quiet option (not available on Wednesdays)
|
608
|
+
# {
|
609
|
+
# reject(Time.new.localtime.day == 3, "Not today!")
|
610
|
+
# $verbose = 0;
|
611
|
+
# }
|
612
|
+
#
|
613
|
+
#
|
614
|
+
# == Specifying other parameter variable types
|
615
|
+
#
|
616
|
+
# As was mentioned in "Type of parameter variables", parameter
|
617
|
+
# variables can be restricted to matching only numbers or only integers
|
618
|
+
# by using the type specifiers ":n" and ":i". Getopt::Declare
|
619
|
+
# provides seven other inbuilt type specifiers, as well as two mechanisms
|
620
|
+
# for defining new restrictions on parameter variables.
|
621
|
+
#
|
622
|
+
# The other inbuilt type specifiers are:
|
623
|
+
#
|
624
|
+
# * :+i
|
625
|
+
#
|
626
|
+
# which restricts a parameter variable to matching positive, non-zero
|
627
|
+
# integers (that is: 1, 2, 3, etc.)
|
628
|
+
#
|
629
|
+
# * :+n
|
630
|
+
#
|
631
|
+
# which restricts a parameter variable to matching positive, non-zero
|
632
|
+
# numbers (that is, floating point numbers strictly greater than zero).
|
633
|
+
#
|
634
|
+
# * :0+i
|
635
|
+
#
|
636
|
+
# which restricts a parameter variable to matching non-negative integers (that
|
637
|
+
# is: 0, 1, 2, 3, etc.)
|
638
|
+
#
|
639
|
+
# * :0+n
|
640
|
+
#
|
641
|
+
# which restricts a parameter variable to matching non-negative numbers (that
|
642
|
+
# is, floating point numbers greater than or equal to zero).
|
643
|
+
#
|
644
|
+
# * :s
|
645
|
+
#
|
646
|
+
# which allows a parameter variable to match any quote-delimited or
|
647
|
+
# whitespace-terminated string. Note that this specifier simply makes
|
648
|
+
# explicit the default behaviour.
|
649
|
+
#
|
650
|
+
# * :d
|
651
|
+
#
|
652
|
+
# which is used to match directory names. Like type ':s', type ':d'
|
653
|
+
# matches any quote-delimited or whitespace-terminated string. However
|
654
|
+
# this type requires that the matched string is name of an existing
|
655
|
+
# (and accesable) directory.
|
656
|
+
#
|
657
|
+
# * :if
|
658
|
+
#
|
659
|
+
# which is used to match input file names. Like type ':s', type ':if'
|
660
|
+
# matches any quote-delimited or whitespace-terminated string. However
|
661
|
+
# this type does _not_ respect other command-line flags and also
|
662
|
+
# requires that the matched string is either "-" (indicating standard
|
663
|
+
# input) or the name of a readable file.
|
664
|
+
#
|
665
|
+
# * :of
|
666
|
+
#
|
667
|
+
# which is used to match output file names. It is exactly like type ':if' except
|
668
|
+
# that it requires that the string is either "-" (indicating standard output)
|
669
|
+
# or the name of a file that is either writable or non-existent.
|
670
|
+
#
|
671
|
+
# * :s
|
672
|
+
#
|
673
|
+
# which allows a parameter variable to match any quote-delimited or
|
674
|
+
# whitespace-terminated string. Note that this specifier simply makes
|
675
|
+
# explicit the default behaviour.
|
676
|
+
#
|
677
|
+
#
|
678
|
+
# For example:
|
679
|
+
#
|
680
|
+
# -repeat <count:+i> Repeat <count> times (must be > 0)
|
681
|
+
#
|
682
|
+
# -scale <factor:0+n> Set scaling factor (cannot be negative)
|
683
|
+
#
|
684
|
+
#
|
685
|
+
# Alternatively, parameter variables can be restricted to matching a
|
686
|
+
# specific regular expression, by providing the required pattern
|
687
|
+
# explicitly (in matched "/" delimiters after the ":"). For example:
|
688
|
+
#
|
689
|
+
# -parity <p:/even|odd|both/> Set parity (<p> must be "even",
|
690
|
+
# "odd" or "both")
|
691
|
+
#
|
692
|
+
# -file <name:/\w*\.[A-Z]{3}/> File name must have a three-
|
693
|
+
# capital-letter extension
|
694
|
+
#
|
695
|
+
# If an explicit regular expression is used, there are three "convenience"
|
696
|
+
# extensions available:
|
697
|
+
#
|
698
|
+
# * %T
|
699
|
+
#
|
700
|
+
# If the sequence <tt>%T</tt> appears in a pattern, it is translated to a negative
|
701
|
+
# lookahead containing the parameter variable's trailing context.
|
702
|
+
# Hence the parameter definition:
|
703
|
+
#
|
704
|
+
# -find <what:/(%T.)+/> ;
|
705
|
+
#
|
706
|
+
# ensures that the command line argument "-find abcd;" causes <tt><-what></tt>
|
707
|
+
# to match "abcd", _not_ "abcd;".
|
708
|
+
#
|
709
|
+
#
|
710
|
+
# * %D
|
711
|
+
#
|
712
|
+
# If the sequence <tt>%D</tt> appears in a pattern, it is translated into
|
713
|
+
# a subpattern which matches any single digit (like a <tt>\d</tt>), but
|
714
|
+
# only if that digit would _not_ match the parameter variable's trailing
|
715
|
+
# context.
|
716
|
+
# Hence <tt>%D</tt> is just a convenient short-hand for <tt>(?:%T\d)</tt>
|
717
|
+
# (and is actually implemented that way).
|
718
|
+
#
|
719
|
+
# * %F
|
720
|
+
#
|
721
|
+
# By default, any explicit pattern is modified by Getopt::Declare
|
722
|
+
# so that it fails if the argument being matched represents some defined
|
723
|
+
# parameter flag. If however the sequence <tt>%F</tt> appears anywhere in a
|
724
|
+
# pattern, it causes the pattern _not_ to reject strings which would
|
725
|
+
# otherwise match another flag. For example, the inbuilt types ':if' and
|
726
|
+
# ':of' use <tt>%F</tt> to enable them to match filenames which happen to be
|
727
|
+
# identical to parameter flags.
|
728
|
+
#
|
729
|
+
#
|
730
|
+
# == Defining new parameter variable types
|
731
|
+
#
|
732
|
+
# Explicit regular expressions are very powerful, but also cumbersome to
|
733
|
+
# use (or reuse) in some situations. Getopt::Declare provides a general
|
734
|
+
# "parameter variable type definition" mechanism to simplify such cases.
|
735
|
+
#
|
736
|
+
# To declare a new parameter variable type, the <tt>[pvtype:...]</tt>
|
737
|
+
# directive is used. A <tt>[pvtype...]</tt> directive specifies the name,
|
738
|
+
# matching pattern, and action for the new parameter variable type
|
739
|
+
# (though both the pattern and action are optional).
|
740
|
+
#
|
741
|
+
# The name string may be _any_ whitespace-terminated sequence of
|
742
|
+
# characters which does not include a ">". The name may also be specified
|
743
|
+
# within a pair of quotation marks (single or double) or within any Perl
|
744
|
+
# quotelike operation. For example:
|
745
|
+
#
|
746
|
+
# [pvtype: num ] # Makes this valid: -count <N:num>
|
747
|
+
# [pvtype: 'a num' ] # Makes this valid: -count <N:a num>
|
748
|
+
# [pvtype: %q{nbr} ] # Makes this valid: -count <N:nbr>
|
749
|
+
#
|
750
|
+
# The pattern is used in initial matching of the parameter variable.
|
751
|
+
# Patterns are normally specified as a "/"-delimited Perl regular
|
752
|
+
# expression:
|
753
|
+
#
|
754
|
+
# [pvtype: num /\d+/ ]
|
755
|
+
# [pvtype: 'a num' /\d+(\.\d*)/ ]
|
756
|
+
# [pvtype: %q{nbr} /[+-]?\d+/ ]
|
757
|
+
#
|
758
|
+
# Alternatively the pattern associated with a new type may be specified
|
759
|
+
# as a ":" followed by the name of another parameter variable type (in
|
760
|
+
# quotes if necessary). In this case the new type matches the same
|
761
|
+
# pattern (and action! - see below) as the named type. For example:
|
762
|
+
#
|
763
|
+
# [pvtype: num :+i ] # <X:num> is the same as <X:+i>
|
764
|
+
# [pvtype: 'a num' :n ] # <X:a num> is the same as <X:n>
|
765
|
+
# [pvtype: %q{nbr} :'a num' ] # <X:nbr> is also the same as <X:n>
|
766
|
+
#
|
767
|
+
# As a third alternative, the pattern may be omitted altogether, in
|
768
|
+
# which case the new type matches whatever the inbuilt pattern ":s"
|
769
|
+
# matches.
|
770
|
+
#
|
771
|
+
# The optional action which may be included in any <tt>[pvtype:...]</tt>
|
772
|
+
# directive is executed _after_ the corresponding parameter variable
|
773
|
+
# matches the command line but _before_ any actions belonging to the
|
774
|
+
# enclosing parameter are executed. Typically, such type actions
|
775
|
+
# will call the +reject+ operator (see "Termination and rejection")
|
776
|
+
# to test extra conditions, but any valid Perl code is acceptible. For
|
777
|
+
# example:
|
778
|
+
#
|
779
|
+
# [pvtype: num /\d+/ { reject if (localtime)[6]==3 } ]
|
780
|
+
# [pvtype: 'a num' :n { print "a num!" } ]
|
781
|
+
# [pvtype: %q{nbr} :'a num' { reject $no_nbr } ]
|
782
|
+
#
|
783
|
+
# If a new type is defined in terms of another (for example, ":a num"
|
784
|
+
# and ":nbr" above), any action specified by that new type is
|
785
|
+
# _prepended_ to the action of that other type. Hence:
|
786
|
+
#
|
787
|
+
#
|
788
|
+
# * the new type ":num" matches any string of digits, but then rejects the
|
789
|
+
# match if it's Wednesday.
|
790
|
+
#
|
791
|
+
# * the new type ":a num" matches any string of digits (like its parent
|
792
|
+
# type ":num"), _then_ prints out "a num!", _and_ _then_ rejects the
|
793
|
+
# match if it's Wednesday (like its parent type ":num").
|
794
|
+
#
|
795
|
+
# * the new type ":nbr" matches any string of digits (like its parent type
|
796
|
+
# ":a num"), but then rejects the match if the global <tt>$no_nbr</tt> variable
|
797
|
+
# is true. Otherwise it next prints out "a num!" (like its parent type
|
798
|
+
# ":a num"), and finally rejects the match if it's Wednesday (like its
|
799
|
+
# grandparent type ":num").
|
800
|
+
#
|
801
|
+
#
|
802
|
+
# When a type action is executed (as part of a particular parameter
|
803
|
+
# match), three local variables are available:
|
804
|
+
#
|
805
|
+
# * <tt>\_VAL_</tt> String/Fixnum/Float
|
806
|
+
#
|
807
|
+
# which contains the value matched by the type's pattern. It is this value which
|
808
|
+
# is ultimately assigned to the local Ruby variable which is available to
|
809
|
+
# parameter actions. Hence if the type action changes the value of <tt>\_VAL_</tt>,
|
810
|
+
# that changed value becomes the "real" value of the corresponding parameter
|
811
|
+
# variable (see the Roman numeral example below).
|
812
|
+
# Note that <tt>\_VAL_</tt> is a variable of different type based on
|
813
|
+
# parameter specified. For [pvtype:...] it is always a String variable.
|
814
|
+
#
|
815
|
+
# * <tt>\_VAR_</tt> String
|
816
|
+
#
|
817
|
+
# which contains the name of the parameter variable being matched.
|
818
|
+
#
|
819
|
+
# * <tt>\_PARAM_</tt> String
|
820
|
+
#
|
821
|
+
# which contains the name of the parameter currently being matched.
|
822
|
+
#
|
823
|
+
#
|
824
|
+
# Here is a example of the use of these variables:
|
825
|
+
#
|
826
|
+
# args = Getopt::Declare.new( <<-'EOPARAM' )
|
827
|
+
#
|
828
|
+
# [pvtype: type /AB|[OAB]/ ]
|
829
|
+
# [pvtype: Rh? /Rh[+-]/ ]
|
830
|
+
# [pvtype: days :+i {
|
831
|
+
# reject(_VAL_ < 14,"#{_PARAM_} (too soon!)")
|
832
|
+
# }
|
833
|
+
# ]
|
834
|
+
#
|
835
|
+
# -donated <d:days> Days since last donation
|
836
|
+
# -applied <a:days> Days since applied to donate
|
837
|
+
#
|
838
|
+
# -blood <type:type> [<rh:Rh?>] Specify blood type
|
839
|
+
# and (optionally) rhesus factor
|
840
|
+
# EOPARAM
|
841
|
+
#
|
842
|
+
# In the above example, the ":days" parameter variable type is defined
|
843
|
+
# to match whatever the ":+i" type matches (that is positive, non-zero
|
844
|
+
# integers), with the proviso that the matching value (<tt>\_VAL_</tt>) must
|
845
|
+
# be at least 14. If a shorter value is specified for <tt>d</tt>,
|
846
|
+
# or <tt>a</tt> parameter variables, then Getopt::Declare would
|
847
|
+
# issue the following (respective) error messages:
|
848
|
+
#
|
849
|
+
# Error: -donated (too soon!)
|
850
|
+
# Error: -applied (too soon!)
|
851
|
+
#
|
852
|
+
# Note that the "inbuilt" parameter variable types ("i", "n", etc.) are
|
853
|
+
# really just predefined type names, and hence can be altered if necessary:
|
854
|
+
#
|
855
|
+
# args = Getopt::Declare.new( <<-'EOPARAM' )
|
856
|
+
#
|
857
|
+
# [pvtype: 'n' /[MDCLXVI]+/ { reject( !(_VAL_=to_roman(_VAL_))) } ]
|
858
|
+
#
|
859
|
+
# -index <number:n> Index number
|
860
|
+
# { print data[number]; }
|
861
|
+
# EOPARAM
|
862
|
+
#
|
863
|
+
# The above <tt>[pvtype:...]</tt> directive means that all parameter variables
|
864
|
+
# specified with a type ":n" henceforth only match valid Roman
|
865
|
+
# numerals, but that any such numerals are _automatically_ converted to
|
866
|
+
# ordinary numbers (by passing <tt>\_VAL_</tt>) through the <tt>to_roman</tt>
|
867
|
+
# function).
|
868
|
+
#
|
869
|
+
# Hence the requirement that all ":n" numbers now must be Roman can be
|
870
|
+
# imposed _transparently_, at least as far as the actual parameter
|
871
|
+
# variables which use the ":n" type are concerned. Thus <tt>number</tt> can
|
872
|
+
# be still used to index the array <tt>data</tt> despite the new restrictions
|
873
|
+
# placed upon it by the redefinition of type ":n".
|
874
|
+
#
|
875
|
+
# Note too that, because the ":+n" and ":0+n" types are implicitly
|
876
|
+
# defined in terms of the original ":n" type (as if the directives:
|
877
|
+
#
|
878
|
+
# [pvtype: '+n' :n { reject if _VAL_ <= 0 } ]
|
879
|
+
# [pvtype: '0+n' :n { reject if _VAL_ < 0 } ]
|
880
|
+
#
|
881
|
+
# were included in every specification), the above redefinition of ":n"
|
882
|
+
# affects those types as well. In such cases the format conversion is
|
883
|
+
# performed _before_ the "sign" tests (in other words, the "inherited"
|
884
|
+
# actions are performed _after_ any newly defined ones).
|
885
|
+
#
|
886
|
+
# Parameter variable type definitions may appear anywhere in a
|
887
|
+
# Getopt::Declare specification and are effective for the entire
|
888
|
+
# scope of the specification. In particular, new parameter variable
|
889
|
+
# types may be defined _after_ they are used.
|
890
|
+
#
|
891
|
+
# == Undocumented parameters
|
892
|
+
#
|
893
|
+
# If a parameter description is omitted, or consists entirely of
|
894
|
+
# whitespace, or contains the special directive <tt>[undocumented]</tt>, then
|
895
|
+
# the parameter is still parsed as normal, but will not appear in the
|
896
|
+
# automatically generated usage information (see "Usage information").
|
897
|
+
#
|
898
|
+
# Apart from allowing for "secret" parameters (a dubious benefit), this
|
899
|
+
# feature enables the programmer to specify some undocumented action
|
900
|
+
# which is to be taken on encountering an otherwise unknown argument.
|
901
|
+
# For example:
|
902
|
+
#
|
903
|
+
# <unknown>
|
904
|
+
# { handle_unknown(unknown) }
|
905
|
+
#
|
906
|
+
#
|
907
|
+
# == "Dittoed" parameters
|
908
|
+
#
|
909
|
+
# Sometimes it is desirable to provide two or more alternate flags for
|
910
|
+
# the same behaviour (typically, a short form and a long form). To
|
911
|
+
# reduce the burden of specifying such pairs, the special directive
|
912
|
+
# <tt>[ditto]</tt> is provided. If the description of a parameter _begins_ with
|
913
|
+
# a <tt>[ditto]</tt> directive, that directive is replaced with the
|
914
|
+
# description for the immediately preceding parameter (including any
|
915
|
+
# other directives). For example:
|
916
|
+
#
|
917
|
+
# -v Verbose mode
|
918
|
+
# --verbose [ditto] (long form)
|
919
|
+
#
|
920
|
+
# In the automatically generated usage information this would be displayed as:
|
921
|
+
#
|
922
|
+
# -v Verbose mode
|
923
|
+
# --verbose " " (long form)
|
924
|
+
#
|
925
|
+
# Furthermore, if the "dittoed" parameter has no action(s) specified, the
|
926
|
+
# action(s) of the preceding parameter are reused. For example, the
|
927
|
+
# specification:
|
928
|
+
#
|
929
|
+
# -v Verbose mode
|
930
|
+
# { $verbose = 1; }
|
931
|
+
# --verbose [ditto]
|
932
|
+
#
|
933
|
+
# would result in the <tt>--verbose</tt> option setting <tt>$verbose</tt> just like the
|
934
|
+
# <tt>-v</tt> option. On the other hand, the specification:
|
935
|
+
#
|
936
|
+
# -v Verbose mode
|
937
|
+
# { $verbose = 1; }
|
938
|
+
# --verbose [ditto]
|
939
|
+
# { $verbose = 2; }
|
940
|
+
#
|
941
|
+
#
|
942
|
+
# would give separate actions to each flag.
|
943
|
+
#
|
944
|
+
#
|
945
|
+
# == Deferred actions
|
946
|
+
#
|
947
|
+
# It is often desirable or necessary to defer actions taken in response
|
948
|
+
# to particular flags until the entire command-line has been parsed. The most
|
949
|
+
# obvious case is where modifier flags must be able to be specified _after_
|
950
|
+
# the command-line arguments they modify.
|
951
|
+
#
|
952
|
+
# To support this, Getopt::Declare provides a local operator (+defer+) which
|
953
|
+
# delays the execution of a particular action until the command-line processing
|
954
|
+
# is finished. The +defer+ operator takes a single block, the execution of which
|
955
|
+
# is deferred until the command-line is fully and successfully parsed. If
|
956
|
+
# command-line processing _fails_ for some reason (see "DIAGNOSTICS"), the
|
957
|
+
# deferred blocks are never executed.
|
958
|
+
#
|
959
|
+
# For example:
|
960
|
+
#
|
961
|
+
# <files>... Files to be processed
|
962
|
+
# { defer { files.each { |i|
|
963
|
+
# print i,"\n" } } }
|
964
|
+
#
|
965
|
+
# -rev[erse] Process in reverse order
|
966
|
+
# { $ordered = -1 }
|
967
|
+
#
|
968
|
+
# -rand[om] Process in random order
|
969
|
+
# { $ordered = 0 }
|
970
|
+
#
|
971
|
+
#
|
972
|
+
# With the above specification, the <tt>-rev</tt> and/or <tt>-rand</tt> flags
|
973
|
+
# can be specified _after_ the list of files, but still affect the processing
|
974
|
+
# of those files. Moreover, if the command-line parsing fails for some reason
|
975
|
+
# (perhaps due to an unrecognized argument), the deferred processing will
|
976
|
+
# not be performed.
|
977
|
+
#
|
978
|
+
#
|
979
|
+
# == Flag clustering
|
980
|
+
#
|
981
|
+
# Like some other Getopt modules, Getopt::Declare allows parameter
|
982
|
+
# flags to be "clustered". That is, if two or more flags have the same
|
983
|
+
# "flag prefix" (one or more leading non-whitespace, non-alphanumeric
|
984
|
+
# characters), those flags may be concatenated behind a single copy of that
|
985
|
+
# flag prefix.
|
986
|
+
# For example, given the parameter specifications:
|
987
|
+
#
|
988
|
+
# -+ Swap signs
|
989
|
+
# -a Append mode
|
990
|
+
# -b Bitwise compare
|
991
|
+
# -c <FILE> Create new file
|
992
|
+
# +del Delete old file
|
993
|
+
# +e <NICE:i> Execute (at specified nice level) when complete
|
994
|
+
#
|
995
|
+
# The following command-lines (amongst others) are all exactly equivalent:
|
996
|
+
#
|
997
|
+
# -a -b -c newfile +e20 +del
|
998
|
+
# -abc newfile +dele20
|
999
|
+
# -abcnewfile+dele20
|
1000
|
+
# -abcnewfile +e 20del
|
1001
|
+
#
|
1002
|
+
# The last two alternatives are correctly parsed because
|
1003
|
+
# Getopt::Declare allows flag clustering at _any point_ where the
|
1004
|
+
# remainder of the command-line being processed starts with a
|
1005
|
+
# non-whitespace character and where the remaining substring would not
|
1006
|
+
# otherwise immediately match a parameter flag.
|
1007
|
+
#
|
1008
|
+
# Hence the trailing "+dele20" in the third command-line example is parsed as
|
1009
|
+
# "+del +e20" and not "-+ del +e20". This is because the previous "-"
|
1010
|
+
# prefix is _not_ propagated (since the leading "+del" _is_ a valid flag).
|
1011
|
+
#
|
1012
|
+
# In contrast, the trailing "+e 20del" in the fourth example is parsed as
|
1013
|
+
# "+e 20 +del" because, after the " 20" is parsed (as the integer
|
1014
|
+
# parameter variable <tt><NICE></tt>, the next characters are "del",
|
1015
|
+
# which _do_ _not_ form a flag themselves unless prefixed with the
|
1016
|
+
# controlling "+".
|
1017
|
+
#
|
1018
|
+
# In some circumstances a clustered sequence of flags on the command-line
|
1019
|
+
# might also match a single (multicharacter) parameter flag. For example, given
|
1020
|
+
# the specifications:
|
1021
|
+
#
|
1022
|
+
# -a Blood type is A
|
1023
|
+
# -b Blood type is B
|
1024
|
+
# -ab Blood type is AB
|
1025
|
+
# -ba Donor has a Bachelor of Arts
|
1026
|
+
#
|
1027
|
+
# A command-line argument "-aba" might be parsed as
|
1028
|
+
# "-a -b -a" or "-a -ba" or "-ab -a". In all such
|
1029
|
+
# cases, Getopt::Declare prefers the longest unmatched flag first.
|
1030
|
+
# Hence the previous example would be parsed as "-ab -a", unless
|
1031
|
+
# the <tt>-ab</tt> flag had already appeared in the command-line (in which
|
1032
|
+
# case, it would be parsed as "-a -ba").
|
1033
|
+
#
|
1034
|
+
# These rules are designed to produce consistency and "least surprise",
|
1035
|
+
# but (as the above example illustrates) may not always do so. If the
|
1036
|
+
# idea of unconstrained flag clustering is too libertarian for a particular
|
1037
|
+
# application, the feature may be restricted (or removed completely),
|
1038
|
+
# by including a <tt>[cluster:...]</tt> directive anywhere in the specification string.
|
1039
|
+
#
|
1040
|
+
# The options are:
|
1041
|
+
#
|
1042
|
+
# * <tt>[cluster: any]</tt>
|
1043
|
+
#
|
1044
|
+
# This version of the directive allows any flag to be clustered (that is,
|
1045
|
+
# it merely makes explicit the default behaviour).
|
1046
|
+
#
|
1047
|
+
# * <tt>[cluster: flags]</tt>
|
1048
|
+
#
|
1049
|
+
# This version of the directive restricts clustering to parameters which are
|
1050
|
+
# "pure" flags (that is, those which have no parameter variables or punctuators).
|
1051
|
+
#
|
1052
|
+
# * <tt>[cluster: singles]</tt>
|
1053
|
+
#
|
1054
|
+
# This version of the directive restricts clustering to parameters which are
|
1055
|
+
# "pure" flags, and which consist of a flag prefix followed by a single
|
1056
|
+
# alphanumeric character.
|
1057
|
+
#
|
1058
|
+
# * <tt>[cluster: none]</tt>
|
1059
|
+
#
|
1060
|
+
# This version of the directive turns off clustering completely.
|
1061
|
+
#
|
1062
|
+
# For example:
|
1063
|
+
#
|
1064
|
+
# args = Getopt::Declare.new(<<-'EOSPEC')
|
1065
|
+
# -a Append mode
|
1066
|
+
# -b Back-up mode
|
1067
|
+
# -bu [ditto]
|
1068
|
+
# -c <file> Copy mode
|
1069
|
+
# -d [<file>] Delete mode
|
1070
|
+
# -e[xec] Execute mode
|
1071
|
+
#
|
1072
|
+
# [cluster:singles]
|
1073
|
+
# EOSPEC
|
1074
|
+
#
|
1075
|
+
# In the above example, only the <tt>-a</tt> and <tt>-b</tt> parameters may be clustered.
|
1076
|
+
# The <tt>-bu</tt> parameter is excluded because it consists of more than one
|
1077
|
+
# letter, whilst the <tt>-c</tt> and <tt>-d</tt> parameters are excluded because they
|
1078
|
+
# take (or may take, in <tt>-d</tt>'s case) a variable. The <tt>-e[xec]</tt> parameter
|
1079
|
+
# is excluded because it may take a trailing punctuator (<tt>[xec]</tt>).
|
1080
|
+
#
|
1081
|
+
# By comparison, if the directive had been <tt>[cluster: flags]</tt>, then
|
1082
|
+
# <tt>-bu</tt> _could_ be clustered, though <tt>-c</tt>, <tt>-d</tt> and <tt>-e[xec]</tt> would
|
1083
|
+
# still be excluded since they are not "pure flags").
|
1084
|
+
#
|
1085
|
+
#
|
1086
|
+
# == Strict and non-strict command-line parsing
|
1087
|
+
#
|
1088
|
+
# "Strictness" in Getopt::Declare refers to the way in which unrecognized
|
1089
|
+
# command-line arguments are handled. By default, Getopt::Declare is
|
1090
|
+
# "non-strict", in that it simply skips silently over any unrecognized
|
1091
|
+
# command-line argument, leaving it in +ARGV+ at the conclusion of
|
1092
|
+
# command-line processing (but only if they were originally parsed
|
1093
|
+
# from +ARGV+).
|
1094
|
+
#
|
1095
|
+
# No matter where they came from, the remaining arguments are also available
|
1096
|
+
# by calling the +unused+ method on the Getopt::Declare object, after it
|
1097
|
+
# has parsed. In a list context, this method returns a list of the
|
1098
|
+
# unprocessed arguments; in a scalar context a single string with the unused
|
1099
|
+
# arguments concatenated is returned.
|
1100
|
+
#
|
1101
|
+
# Likewise, there is a +used+ method that returns the arguments that were
|
1102
|
+
# successfully processed by the parser.
|
1103
|
+
#
|
1104
|
+
# However, if a new Getopt::Declare object is created with a
|
1105
|
+
# specification string containing the <tt>[strict]</tt> directive (at any
|
1106
|
+
# point in the specification):
|
1107
|
+
#
|
1108
|
+
# args = Getopt::Declare.new(<<-'EOSPEC')
|
1109
|
+
#
|
1110
|
+
# [strict]
|
1111
|
+
#
|
1112
|
+
# -a Append mode
|
1113
|
+
# -b Back-up mode
|
1114
|
+
# -c Copy mode
|
1115
|
+
# EOSPEC
|
1116
|
+
#
|
1117
|
+
# then the command-line is parsed "strictly". In this case, any
|
1118
|
+
# unrecognized argument causes an error message (see "DIAGNOSTICS") to
|
1119
|
+
# be written to <tt>$stderr</tt>, and command-line processing to (eventually)
|
1120
|
+
# fail. On such a failure, the call to Getopt::Declare::new() returns
|
1121
|
+
# +nil+ instead of the usual hash.
|
1122
|
+
#
|
1123
|
+
# The only concession that "strict" mode makes to the unknown is that,
|
1124
|
+
# if command-line processing is prematurely terminated via the
|
1125
|
+
# +finish+ operator, any command-line arguments which have not yet
|
1126
|
+
# been examined are left in +ARGV+ and do not cause the parse to fail (of
|
1127
|
+
# course, if any unknown arguments were encountered _before_ the
|
1128
|
+
# +finish+ was executed, those earlier arguments _will_ cause
|
1129
|
+
# command-line processing to fail).
|
1130
|
+
#
|
1131
|
+
# The "strict" option is useful when _all_ possible parameters
|
1132
|
+
# can be specified in a single Getopt::Declare object, whereas the
|
1133
|
+
# "non-strict" approach is needed when unrecognized arguments are either
|
1134
|
+
# to be quietly tolerated, or processed at a later point (possibly in a
|
1135
|
+
# second Getopt::Declare object).
|
1136
|
+
#
|
1137
|
+
#
|
1138
|
+
# == Parameter dependencies
|
1139
|
+
#
|
1140
|
+
# Getopt::Declare provides five other directives which modify the
|
1141
|
+
# behaviour of the command-line parser in some way. One or more of these
|
1142
|
+
# directives may be included in any parameter description. In addition,
|
1143
|
+
# the <tt>[mutex:...]</tt> directive may also appear in any usage "decoration"
|
1144
|
+
# (see "Usage information").
|
1145
|
+
#
|
1146
|
+
# Each directive specifies a particular set of conditions that a
|
1147
|
+
# command-line must fulfil (for example, that certain parameters may not
|
1148
|
+
# appear on the same command-line). If any such condition is violated,
|
1149
|
+
# an appropriate error message is printed (see "DIAGNOSTICS").
|
1150
|
+
# Furthermore, once the command-line is completely parsed, if any
|
1151
|
+
# condition was violated, the program terminates
|
1152
|
+
# (whilst still inside Getopt::Declare::new()).
|
1153
|
+
#
|
1154
|
+
# The directives are:
|
1155
|
+
#
|
1156
|
+
# * <tt>[tight]</tt>
|
1157
|
+
#
|
1158
|
+
# Specifies that the usage description should be printed in a tight
|
1159
|
+
# form, eliminating as many empty or whitespace only lines as possible.
|
1160
|
+
#
|
1161
|
+
#
|
1162
|
+
# * <tt>[required]</tt>
|
1163
|
+
#
|
1164
|
+
# Specifies that an argument matching at least one variant of the
|
1165
|
+
# corresponding parameter _must_ be specified somewhere in the
|
1166
|
+
# command-line. That is, if two or more required parameters share the
|
1167
|
+
# same flag, it suffices that _any_ _one_ of them matches an argument
|
1168
|
+
# (recall that Getopt::Declare considers all parameter specifications
|
1169
|
+
# with the same flag merely to be variant forms of a single "underlying"
|
1170
|
+
# parameter).
|
1171
|
+
#
|
1172
|
+
# If an argument matching a "required" flag is _not_ found in the
|
1173
|
+
# command-line, an error message to that effect is issued,
|
1174
|
+
# command-line processing fails, and Getopt::Declare::new() returns
|
1175
|
+
# +nil+.
|
1176
|
+
#
|
1177
|
+
#
|
1178
|
+
# * <tt>[repeatable]</tt>
|
1179
|
+
#
|
1180
|
+
# By default, Getopt::Declare objects allow each of their parameters to
|
1181
|
+
# be matched only once (that is, once any variant of a particular
|
1182
|
+
# parameter matches an argument, _all_ variants of that same parameter
|
1183
|
+
# are subsequently excluded from further consideration when parsing the
|
1184
|
+
# rest of the command-line).
|
1185
|
+
#
|
1186
|
+
# However, it is sometimes useful to allow a particular parameter to match
|
1187
|
+
# more than once. Any parameter whose description includes the directive
|
1188
|
+
# <tt>[repeatable]</tt> is _never_ excluded as a potential argument match, no matter
|
1189
|
+
# how many times it has matched previously:
|
1190
|
+
#
|
1191
|
+
# -nice Increase nice value (linearly if repeated)
|
1192
|
+
# [repeatable]
|
1193
|
+
# { set_nice( get_nice()+1 ) }
|
1194
|
+
#
|
1195
|
+
# -w Toggle warnings [repeatable] for the rest
|
1196
|
+
# of the command-line
|
1197
|
+
# { warn = !warn }
|
1198
|
+
#
|
1199
|
+
# As a more general mechanism is a <tt>[repeatable]</tt> directive appears in a
|
1200
|
+
# specification anywhere other than a flag's description, then _all_ parameters
|
1201
|
+
# are marked repeatable:
|
1202
|
+
#
|
1203
|
+
# [repeatable]
|
1204
|
+
#
|
1205
|
+
# -nice Increase nice value (linearly if repeated)
|
1206
|
+
# { set_nice( get_nice()+1 ) }
|
1207
|
+
#
|
1208
|
+
# -w Toggle warnings for the rest of the command-line
|
1209
|
+
# { warn = !warn }
|
1210
|
+
#
|
1211
|
+
#
|
1212
|
+
# * <tt>[mutex: <flag list>]</tt>
|
1213
|
+
#
|
1214
|
+
# <tt>[mutex:...]</tt> directive specifies that the parameters whose
|
1215
|
+
# flags it lists are mutually exclusive. That is, no two or more of them
|
1216
|
+
# may appear in the same command-line. For example:
|
1217
|
+
#
|
1218
|
+
# -case set to all lower case
|
1219
|
+
# -CASE SET TO ALL UPPER CASE
|
1220
|
+
# -Case Set to sentence case
|
1221
|
+
# -CaSe SeT tO "RAnSom nOTe" CasE
|
1222
|
+
#
|
1223
|
+
# [mutex: -case -CASE -Case -CaSe]
|
1224
|
+
#
|
1225
|
+
# The interaction of the <tt>[mutex:...]</tt> and <tt>[required]</tt>
|
1226
|
+
# directives is potentially awkward in the case where two "required"
|
1227
|
+
# arguments are also mutually exclusive (since the <tt>[required]</tt>
|
1228
|
+
# directives insist that both parameters must appear in the command-line,
|
1229
|
+
# whilst the <tt>[mutex:...]</tt> directive expressly forbids this).
|
1230
|
+
#
|
1231
|
+
# Getopt::Declare resolves such contradictory constraints by
|
1232
|
+
# relaxing the meaning of "required" slightly. If a flag is marked
|
1233
|
+
# "required", it is considered "found" for the purposes of error
|
1234
|
+
# checking if it or _any_ other flag with which it is mutually
|
1235
|
+
# exclusive appears on the command-line.
|
1236
|
+
#
|
1237
|
+
# Hence the specifications:
|
1238
|
+
#
|
1239
|
+
# -case set to all lower case [required]
|
1240
|
+
# -CASE SET TO ALL UPPER CASE [required]
|
1241
|
+
# -Case Set to sentence case [required]
|
1242
|
+
# -CaSe SeT tO "RAnSom nOTe" CasE [required]
|
1243
|
+
#
|
1244
|
+
# [mutex: -case -CASE -Case -CaSe]
|
1245
|
+
#
|
1246
|
+
# mean that _exactly_ _one_ of these four flags must appear on the
|
1247
|
+
# command-line, but that the presence of any one of them will suffice
|
1248
|
+
# to satisfy the "requiredness" of all four.
|
1249
|
+
#
|
1250
|
+
# It should also be noted that mutual exclusion is only tested for
|
1251
|
+
# _after_ a parameter has been completely matched (that is, after the
|
1252
|
+
# execution of its actions, if any). This prevents "rejected" parameters
|
1253
|
+
# (see "Termination and rejection") from incorrectly generating
|
1254
|
+
# mutual exclusion errors. However, it also sometimes makes it necessary
|
1255
|
+
# to defer the actions of a pair of mutually exclusive parameters (for
|
1256
|
+
# example, if those actions are expensive or irreversible).
|
1257
|
+
#
|
1258
|
+
#
|
1259
|
+
# * <tt>[excludes: <flag list>]</tt>
|
1260
|
+
#
|
1261
|
+
# The <tt>[excludes:...]</tt> directive provides a "pairwise" version of
|
1262
|
+
# mutual exclusion, specifying that the current parameter is mutually exclusive
|
1263
|
+
# with all the other parameters lists, but those other parameters are not
|
1264
|
+
# mutually exclusive with each other. That is, whereas the specification:
|
1265
|
+
#
|
1266
|
+
# -left Justify to left margin
|
1267
|
+
# -right Justify to right margin
|
1268
|
+
# -centre Centre each line
|
1269
|
+
#
|
1270
|
+
# [mutex: -left -right -centre]
|
1271
|
+
#
|
1272
|
+
# means that only one of these three justification alternatives can ever be used
|
1273
|
+
# at once, the specification:
|
1274
|
+
#
|
1275
|
+
# -left Justify to left margin
|
1276
|
+
# -right Justify to right margin
|
1277
|
+
# -centre Centre each line [excludes: -left -right]
|
1278
|
+
#
|
1279
|
+
# means that <tt>-left</tt> and <tt>-right</tt> can still be used together
|
1280
|
+
# (probably to indicate "left _and_ right" justification), but that
|
1281
|
+
# neither can be used with <tt>-centre</tt>. Note that the <tt>[excludes:...]</tt>
|
1282
|
+
# directive also differs from the <tt>[mutex:...]</tt> in that it is always
|
1283
|
+
# connected with a paricular parameter, _implicitly_
|
1284
|
+
# using the flag of that parameter as the target of exclusion.
|
1285
|
+
#
|
1286
|
+
#
|
1287
|
+
# * <tt>[requires: -condition]</tt>
|
1288
|
+
#
|
1289
|
+
# The <tt>[requires]</tt> directive specifies a set of flags which
|
1290
|
+
# must also appear in order for a particular flag to be permitted in the
|
1291
|
+
# command-line. The condition is a boolean expression, in which the
|
1292
|
+
# terms are the flags or various parameters, and the operations are
|
1293
|
+
# <tt>&&</tt>, <tt>||</tt>, <tt>!</tt>, and bracketting. For example, the specifications:
|
1294
|
+
#
|
1295
|
+
# -num Use numeric sort order
|
1296
|
+
# -lex Use "dictionary" sort order
|
1297
|
+
# -len Sort on length of line (or field)
|
1298
|
+
#
|
1299
|
+
# -field <N:+i> Sort on value of field <N>
|
1300
|
+
#
|
1301
|
+
# -rev Reverse sort order
|
1302
|
+
# [requires: -num || -lex || !(-len && -field)]
|
1303
|
+
#
|
1304
|
+
# means that the <tt>-rev</tt> flag is allowed only if either the <tt>-num</tt> or the
|
1305
|
+
# <tt>-lex</tt> parameter has been used, or if it is not true that
|
1306
|
+
# _both_ the <tt>-len</tt> _and_ the <tt>-field</tt> parameters have been used.
|
1307
|
+
#
|
1308
|
+
# Note that the operators <tt>&&</tt>, <tt>||</tt> and <tt>!</tt> retain their normal
|
1309
|
+
# Ruby precedences.
|
1310
|
+
#
|
1311
|
+
#
|
1312
|
+
# == Parsing from other sources
|
1313
|
+
#
|
1314
|
+
# Getopt::Declare normally parses the contents of +ARGV+, but can
|
1315
|
+
# be made to parse specified files or other sources instead.
|
1316
|
+
# To accommodate this, Getopt::Declare::new() takes an optional second parameter, which specifies a file to be parsed.
|
1317
|
+
# This second parameter can also be passed directly onto Getopt::Declare::parse()
|
1318
|
+
# The parameter may be either:
|
1319
|
+
#
|
1320
|
+
# * An +IO+ object
|
1321
|
+
#
|
1322
|
+
# in which case Getopt::Declare::new() reads the corresponding handle until
|
1323
|
+
# end-of-file, and parses the resulting text (even if it is an empty string).
|
1324
|
+
#
|
1325
|
+
# * An ARRAY containing the single string ['-CONFIG']
|
1326
|
+
#
|
1327
|
+
# in which case Getopt::Declare::new() looks for the files
|
1328
|
+
# <tt>ENV['HOME']/.#{progname}rc</tt> and <tt>ENV['PWD']/.#{progname}rc</tt>,
|
1329
|
+
# concatenates their contents, and parses that.
|
1330
|
+
#
|
1331
|
+
# If neither file is found (or if both are inaccessible)
|
1332
|
+
# Getopt::Declare::new() immediately returns zero. If a
|
1333
|
+
# file is found but the parse subsequently fails, +nil+ is returned.
|
1334
|
+
#
|
1335
|
+
# * An ARRAY containing the single string ['-BUILD']
|
1336
|
+
#
|
1337
|
+
# in which case Getopt::Declare::new() builds a parser from the
|
1338
|
+
# supplied grammar and returns it, but does not parse anything.
|
1339
|
+
# See "The Getopt::Declare::code() method" and
|
1340
|
+
# "The Getopt::Declare::parse() method".
|
1341
|
+
#
|
1342
|
+
# * An ARRAY containing the single string ['-SKIP'] or the single value [nil] or nothing []
|
1343
|
+
#
|
1344
|
+
# in which case Getopt::Declare::new() immediately returns zero.
|
1345
|
+
# This alternative is useful when using a +File+:
|
1346
|
+
#
|
1347
|
+
# args = Getopt::Declare.new(grammar,
|
1348
|
+
# File.new(filename) || ['-SKIP'])
|
1349
|
+
#
|
1350
|
+
# because it makes explicit what happens if File::new() fails. Of course,
|
1351
|
+
# if the <tt>['-SKIP']</tt> alternative were omitted, Getopt::Declare::new would
|
1352
|
+
# still return immediately, having found +nil+ as its second argument.
|
1353
|
+
#
|
1354
|
+
# * An ARRAY containing the word "-ARGV" followed by another ARRAY
|
1355
|
+
#
|
1356
|
+
# in which case Getopt::Declare::new() treats the array elements as
|
1357
|
+
# parameters to parse (as if it were +ARGV+).
|
1358
|
+
#
|
1359
|
+
# arr = ['-in','opt with spaces']
|
1360
|
+
# args = Getopt::Declare.new(grammar, ['-ARGV', arr])
|
1361
|
+
#
|
1362
|
+
# * Any other ARRAY
|
1363
|
+
#
|
1364
|
+
# in which case Getopt::Declare::new() treats the array elements as a
|
1365
|
+
# list of filenames, concatenates the contents of those files, and parses that.
|
1366
|
+
#
|
1367
|
+
# If the list does not denote any accessible file(s)
|
1368
|
+
# Getopt::Declare::new() immediately returns zero. If matching files
|
1369
|
+
# are found, but not successfully parsed, +nil+ is returned.
|
1370
|
+
#
|
1371
|
+
# * A string
|
1372
|
+
#
|
1373
|
+
# in which case Getopt::Declare::new() parses that string directly.
|
1374
|
+
#
|
1375
|
+
# Note that when Getopt::Declare::new() parses from a
|
1376
|
+
# source other than +ARGV+, unrecognized arguments are _not_
|
1377
|
+
# placed back in +ARGV+.
|
1378
|
+
#
|
1379
|
+
#
|
1380
|
+
# == Using Getopt::Declare objects after command-line processing
|
1381
|
+
#
|
1382
|
+
# After command-line processing is completed, the object returned by
|
1383
|
+
# Getopt::Declare::new() will have the following features:
|
1384
|
+
#
|
1385
|
+
# * Parameter data
|
1386
|
+
#
|
1387
|
+
# For each successfully matched parameter, the Getopt::Declare object
|
1388
|
+
# will contain a hash element. The key of that element will be the leading flag
|
1389
|
+
# or parameter variable name of the parameter.
|
1390
|
+
#
|
1391
|
+
# The value of the element will be another hash which contains
|
1392
|
+
# the names and values of each distinct parameter variable and/or
|
1393
|
+
# punctuator which was matched by the parameter. Punctuators generate
|
1394
|
+
# string values containing the actual text matched. Other parameter
|
1395
|
+
# variables generate values based on their specification (Fixnum,
|
1396
|
+
# Float, String). List parameter variables generate Arrays.
|
1397
|
+
#
|
1398
|
+
# As a special case, if a parameter consists of a single component
|
1399
|
+
# (either a single flag or a single parameter variable), then the value for the
|
1400
|
+
# corresponding hash key is not another hash, but the actual value matched.
|
1401
|
+
#
|
1402
|
+
# The following example illustrates the various possibilities:
|
1403
|
+
#
|
1404
|
+
# args = Getopt::Declare.new( %q{
|
1405
|
+
#
|
1406
|
+
# -v <value> [etc] One or more values
|
1407
|
+
# <infile> Input file [required]
|
1408
|
+
# -o <outfiles>... Output files
|
1409
|
+
# } )
|
1410
|
+
#
|
1411
|
+
# if args['-v']
|
1412
|
+
# print "Using value: ", args['-v']['<value>']
|
1413
|
+
# print " (etcetera)" if args['-v']['etc']
|
1414
|
+
# print "\n"
|
1415
|
+
# end
|
1416
|
+
#
|
1417
|
+
# infile = File.new( args['<infile>'] )
|
1418
|
+
# data = infile
|
1419
|
+
#
|
1420
|
+
# for outfile in args['-o']
|
1421
|
+
# outfile = File.new(outfile,'w')
|
1422
|
+
# outfile.puts "processed"
|
1423
|
+
# outfile.close
|
1424
|
+
# end
|
1425
|
+
#
|
1426
|
+
# The values which are assigned to the various hash elements are copied from
|
1427
|
+
# the corresponding blocked-scoped variables which are available within
|
1428
|
+
# actions. In particular, if the value of any of those block-scoped variables
|
1429
|
+
# is changed within an action, that changed value is saved in the hash. For
|
1430
|
+
# example, given the specification:
|
1431
|
+
#
|
1432
|
+
# args = Getopt::Declare.new( %q{
|
1433
|
+
#
|
1434
|
+
# -ar <r:n> Set aspect ratio (will be clipped to [0..1])
|
1435
|
+
# {
|
1436
|
+
# r = 0 if r < 0
|
1437
|
+
# r = 1 if r > 1
|
1438
|
+
# }
|
1439
|
+
# } )
|
1440
|
+
#
|
1441
|
+
# then the value of <tt>args['-ar']</tt> will always be between zero
|
1442
|
+
# and one.
|
1443
|
+
#
|
1444
|
+
# * The +ARGV+ array
|
1445
|
+
#
|
1446
|
+
# In its "non-strict" mode, once a Getopt::Declare object has
|
1447
|
+
# completed its command-line processing, it pushes any unrecognized
|
1448
|
+
# arguments back into the emptied command-line array +ARGV+ (whereas
|
1449
|
+
# all _recognized_ arguments will have been removed).
|
1450
|
+
#
|
1451
|
+
# Note that these remaining arguments will be in sequential elements
|
1452
|
+
# (starting at <tt>ARGV[0]</tt>), _not_ in their original positions in
|
1453
|
+
# +ARGV+.
|
1454
|
+
#
|
1455
|
+
#
|
1456
|
+
# * The Getopt::Declare::usage() method
|
1457
|
+
#
|
1458
|
+
# Once a Getopt::Declare object is created, its <tt>usage()</tt> method may be called
|
1459
|
+
# to explicitly print out usage information corresponding to the specification
|
1460
|
+
# with which it was built. See "Usage information" for more details.
|
1461
|
+
# If the <tt>usage()</tt> method is called with an argument, that argument is passed
|
1462
|
+
# to <tt>exit</tt> after the usage information is printed (the no-argument version of
|
1463
|
+
# <tt>usage()</tt> simply returns at that point).
|
1464
|
+
#
|
1465
|
+
#
|
1466
|
+
# * The Getopt::Declare::version() method
|
1467
|
+
#
|
1468
|
+
# Another useful method of a Getopt::Declare object is <tt>version()</tt>,
|
1469
|
+
# which prints out the name of the enclosing program, the last time it
|
1470
|
+
# was modified, and the value of <tt>$VERSION</tt>, if it is defined.
|
1471
|
+
# Note that this implies that _all_ Getopt::Declare objects in a
|
1472
|
+
# single program will print out identical version information.
|
1473
|
+
#
|
1474
|
+
# Like the <tt>usage()</tt> method, if <tt>version</tt> is passed an argument, it
|
1475
|
+
# will exit with that value after printing.
|
1476
|
+
#
|
1477
|
+
#
|
1478
|
+
# * The Getopt::Declare::parse() method
|
1479
|
+
#
|
1480
|
+
# It is possible to separate the construction of a Getopt::Declare
|
1481
|
+
# parser from the actual parsing it performs. If
|
1482
|
+
# Getopt::Declare::new() is called with a second parameter ['-BUILD']
|
1483
|
+
# (see "Parsing from other sources", it constructs and returns a
|
1484
|
+
# parser, without parsing anything.
|
1485
|
+
# The resulting parser object can then be used to parse multiple sources,
|
1486
|
+
# by calling its <tt>parse()</tt> method.
|
1487
|
+
#
|
1488
|
+
# Getopt::Declare::parse() takes an optional parameter which specifies
|
1489
|
+
# the source of the text to be parsed (it parses +ARGV+ if the
|
1490
|
+
# parameter is omitted). This parameter takes the same set of values as the
|
1491
|
+
# optional second parameter of Getopt::Declare::new() (see "Parsing
|
1492
|
+
# from other sources").
|
1493
|
+
#
|
1494
|
+
# Getopt::Declare::parse() returns true if the source is located and
|
1495
|
+
# parsed successfully. It returns a defined false (zero) if the source is
|
1496
|
+
# not located. A +nil+ is returned if the source is located, but not
|
1497
|
+
# successfully parsed.
|
1498
|
+
#
|
1499
|
+
# Thus, the following code first constructs a parsers for a series of
|
1500
|
+
# alternate configuration files and the command line, and then parses them:
|
1501
|
+
#
|
1502
|
+
# # BUILD PARSERS
|
1503
|
+
# config = Getopt::Declare::new(config_grammar, ['-BUILD']);
|
1504
|
+
# cmdline = Getopt::Declare::new(cmdline_grammar, ['-BUILD']);
|
1505
|
+
#
|
1506
|
+
# # TRY STANDARD CONFIG FILES
|
1507
|
+
# config.parse(['-CONFIG'])
|
1508
|
+
#
|
1509
|
+
# # OTHERWISE, TRY GLOBAL CONFIG
|
1510
|
+
# or config.parse('/usr/local/config/.demo_rc')
|
1511
|
+
#
|
1512
|
+
# # OTHERWISE, TRY OPENING A FILEHANDLE (OR JUST GIVE UP)
|
1513
|
+
# or config.parse(File.new(".config") || ['-SKIP']);
|
1514
|
+
#
|
1515
|
+
# # NOW PARSE THE COMMAND LINE
|
1516
|
+
#
|
1517
|
+
# cmdline.parse() or raise "cannot parse";
|
1518
|
+
#
|
1519
|
+
#
|
1520
|
+
# * The Getopt::Declare::code() method
|
1521
|
+
#
|
1522
|
+
# It is also possible to retreive the command-line parsing code generated
|
1523
|
+
# internally by Getopt::Declare::new(). The Getopt::Declare::code()
|
1524
|
+
# method returns a string containing the complete command-line processing
|
1525
|
+
# code, as a single +begin+ block plus a leading +package+ declaration.
|
1526
|
+
#
|
1527
|
+
# Getopt::Declare::code() takes as its sole argument a string
|
1528
|
+
# containing the complete name of the package (for the leading
|
1529
|
+
# +package+ declaration in the generated code). If this string is empty
|
1530
|
+
# or undefined, the package name defaults to "main".
|
1531
|
+
#
|
1532
|
+
# Since the default behaviour of Getopt::Declare::new() is to execute
|
1533
|
+
# the command-line parsing code it generates, if the goal is only to
|
1534
|
+
# generate the parser code, the optional second ['-BUILD'] parameter
|
1535
|
+
# (see "Parsing from other sources") should be specified when calling
|
1536
|
+
# Getopt::Declare::new().
|
1537
|
+
#
|
1538
|
+
# For example, the following program "inlines" a Getopt::Declare
|
1539
|
+
# specification, by extracting it from between the first "=for
|
1540
|
+
# Getopt::Declare" and the next "=cut" appearing on +$stdin+:
|
1541
|
+
#
|
1542
|
+
# =begin
|
1543
|
+
# Just type in something, like:
|
1544
|
+
#
|
1545
|
+
# =for Getopt::Declare
|
1546
|
+
#
|
1547
|
+
# -a Append mode
|
1548
|
+
# =cut
|
1549
|
+
#
|
1550
|
+
# =end
|
1551
|
+
#
|
1552
|
+
# $/ = '=cut'
|
1553
|
+
# if t = $stdin.readline
|
1554
|
+
# t.sub!( /^=for\s+Getopt::Declare\s*\n(.*?)\n=cut/esm ) {
|
1555
|
+
# '(self,source) = []'+encode("#$1") }
|
1556
|
+
# end
|
1557
|
+
#
|
1558
|
+
# print t
|
1559
|
+
#
|
1560
|
+
#
|
1561
|
+
# Note that the generated inlined version expects to find a lexical variable
|
1562
|
+
# named +source+, which tells it what to parse (this variable is
|
1563
|
+
# normally set by the optional parameters of Getopt::Declare::new() or
|
1564
|
+
# Getopt::Declare::parse()).
|
1565
|
+
#
|
1566
|
+
# The inlined code leaves all extracted parameters in the lexical
|
1567
|
+
# variable +self+ and the does not autogenerate help or version flags
|
1568
|
+
# (since there is no actual Getopt::Declare object in the inlined code
|
1569
|
+
# through which to generate them).
|
1570
|
+
#
|
1571
|
+
# = AUTOGENERATED FEATURES
|
1572
|
+
#
|
1573
|
+
# == Usage information
|
1574
|
+
#
|
1575
|
+
# The specification passed to Getopt::Declare::new is used (almost
|
1576
|
+
# verbatim) as a "usage" display whenever usage information is
|
1577
|
+
# requested.
|
1578
|
+
#
|
1579
|
+
# Such requests may be made either by specifying an argument matching
|
1580
|
+
# the help parameter (see "Help parameters") or by explicitly calling
|
1581
|
+
# the Getopt::Declare::usage() method (through an action or after
|
1582
|
+
# command-line processing):
|
1583
|
+
#
|
1584
|
+
# args = Getopt::Declare.new( %q{
|
1585
|
+
#
|
1586
|
+
# -usage Show usage information and exit
|
1587
|
+
# { usage(0) }
|
1588
|
+
#
|
1589
|
+
# +usage Show usage information at end of program
|
1590
|
+
# } )
|
1591
|
+
#
|
1592
|
+
# # PROGRAM HERE
|
1593
|
+
#
|
1594
|
+
# args.usage if args['+usage'];
|
1595
|
+
#
|
1596
|
+
#
|
1597
|
+
# The following changes are made to the original specification before
|
1598
|
+
# it is displayed:
|
1599
|
+
#
|
1600
|
+
# * All actions and comments are deleted,
|
1601
|
+
#
|
1602
|
+
# * any <tt>[ditto]</tt> directive is converted to an appropriate set of "ditto" marks,
|
1603
|
+
#
|
1604
|
+
# * any text in matching square brackets (including any directive) is deleted,
|
1605
|
+
#
|
1606
|
+
# * any parameter variable type specifier (":i", ":n", ":/pat/", etc.) is deleted.
|
1607
|
+
#
|
1608
|
+
# Otherwise, the usage information displayed retains all the formatting
|
1609
|
+
# present in the original specification.
|
1610
|
+
#
|
1611
|
+
# In addition to this information, if the input source is +ARGV+,
|
1612
|
+
# Getopt::Declare displays three sample command-lines: one indicating
|
1613
|
+
# the normal usage (including any required parameter variables), one
|
1614
|
+
# indicating how to invoke help (see "Help parameters"), and one
|
1615
|
+
# indicating how to determine the current version of the program (see
|
1616
|
+
# "Version parameters").
|
1617
|
+
#
|
1618
|
+
# The usage information is printed to <tt>$stdout</tt> and (since Getopt::Declare
|
1619
|
+
# tends to encourage longer and better-documented parameter lists) if
|
1620
|
+
# the IO::Pager> package is available, an IO::Pager> object is used to
|
1621
|
+
# page out the entire usage documentation.
|
1622
|
+
#
|
1623
|
+
# == Usage "decoration"
|
1624
|
+
#
|
1625
|
+
# It is sometimes convenient to add other "decorative" features to a
|
1626
|
+
# program's usage information, such as subheadings, general notes,
|
1627
|
+
# separators, etc. Getopt::Declare accommodates this need by ignoring
|
1628
|
+
# such items when interpreting a specification string, but printing them
|
1629
|
+
# when asked for usage information.
|
1630
|
+
#
|
1631
|
+
# Any line which cannot be interpreted as either a parameter
|
1632
|
+
# definition, a parameter description, or a parameter action, is treated
|
1633
|
+
# as a "decorator" line, and is printed verbatim (after any square
|
1634
|
+
# bracketted substrings have been removed from it).
|
1635
|
+
#
|
1636
|
+
# The key to successfully decorating Getopt::Declare usage
|
1637
|
+
# information is to ensure that decorator lines are separated from
|
1638
|
+
# any preceding parameter specification, either by an action or by an
|
1639
|
+
# empty line. In addition, like a parameter description, a decorator
|
1640
|
+
# line cannot contain a tab character after the first non-whitespace
|
1641
|
+
# character (because it would then be treated as a parameter
|
1642
|
+
# specification).
|
1643
|
+
#
|
1644
|
+
# The following specification demonstrates various forms of usage
|
1645
|
+
# decoration. In fact, there are only four actual parameters (<tt>-in</tt>,
|
1646
|
+
# <tt>-r</tt>, <tt>-p</tt>, and <tt>-out</tt>) specified. Note in particular that _leading_ tabs
|
1647
|
+
# are perfectly acceptible in decorator lines.
|
1648
|
+
#
|
1649
|
+
# args = Getopt::Declare.new(<<-'EOPARAM');
|
1650
|
+
#
|
1651
|
+
# ============================================================
|
1652
|
+
# Required parameter:
|
1653
|
+
#
|
1654
|
+
# -in <infile> Input file [required]
|
1655
|
+
#
|
1656
|
+
# ------------------------------------------------------------
|
1657
|
+
#
|
1658
|
+
# Optional parameters:
|
1659
|
+
#
|
1660
|
+
# (The first two are mutually exclusive) [mutex: -r -p]
|
1661
|
+
#
|
1662
|
+
# -r[and[om]] Output in random order
|
1663
|
+
# -p[erm[ute]] Output all permutations
|
1664
|
+
#
|
1665
|
+
# ---------------------------------------------------
|
1666
|
+
#
|
1667
|
+
# -out <outfile> Optional output file
|
1668
|
+
#
|
1669
|
+
# ------------------------------------------------------------
|
1670
|
+
# Note: this program is known to run very slowly of files with
|
1671
|
+
# long individual lines.
|
1672
|
+
# ============================================================
|
1673
|
+
# EOPARAM
|
1674
|
+
#
|
1675
|
+
#
|
1676
|
+
# == Help parameters
|
1677
|
+
#
|
1678
|
+
# By default, Getopt::Declare automatically defines _all_ of the following
|
1679
|
+
# parameters:
|
1680
|
+
#
|
1681
|
+
# -help Show usage information [undocumented]
|
1682
|
+
# { usage(0) }
|
1683
|
+
# -Help [ditto]
|
1684
|
+
# -HELP [ditto]
|
1685
|
+
# --help [ditto]
|
1686
|
+
# --Help [ditto]
|
1687
|
+
# --HELP [ditto]
|
1688
|
+
# -h [ditto]
|
1689
|
+
# -H [ditto]
|
1690
|
+
#
|
1691
|
+
# Hence, most attempts by the user to get help will automatically work
|
1692
|
+
# successfully.
|
1693
|
+
#
|
1694
|
+
# Note however that, if a parameter with any of these flags is
|
1695
|
+
# explicitly specified in the string passed to Getopt::Declare::new(),
|
1696
|
+
# that flag (only) is removed from the list of possible help flags. For
|
1697
|
+
# example:
|
1698
|
+
#
|
1699
|
+
# -w <pixels:+i> Specify width in pixels
|
1700
|
+
# -h <pixels:+i> Specify height in pixels
|
1701
|
+
#
|
1702
|
+
# would cause the <tt>-h</tt> help parameter to be removed (although help
|
1703
|
+
# would still be accessible through the other seven alternatives).
|
1704
|
+
#
|
1705
|
+
#
|
1706
|
+
# == Version parameters
|
1707
|
+
#
|
1708
|
+
# Getopt::Declare also automatically creates a set of parameters which can be
|
1709
|
+
# used to retreive program version information:
|
1710
|
+
#
|
1711
|
+
# -version Show version information [undocumented]
|
1712
|
+
# { version(0) }
|
1713
|
+
# -Version [ditto]
|
1714
|
+
# -VERSION [ditto]
|
1715
|
+
# --version [ditto]
|
1716
|
+
# --Version [ditto]
|
1717
|
+
# --VERSION [ditto]
|
1718
|
+
# -v [ditto]
|
1719
|
+
# -V [ditto]
|
1720
|
+
#
|
1721
|
+
# As with the various help commands, explicitly specifying a parameter
|
1722
|
+
# with any of the above flags removes that flag from the list of version
|
1723
|
+
# flags.
|
1724
|
+
#
|
1725
|
+
#
|
1726
|
+
# = DIAGNOSTICS
|
1727
|
+
#
|
1728
|
+
# Getopt::Declare may issue the following diagnostics whilst parsing a
|
1729
|
+
# command-line. All of them are fatal (the first five, instantly so):
|
1730
|
+
#
|
1731
|
+
# * "Error: bad Getopt::Declare parameter variable specification near %s"
|
1732
|
+
#
|
1733
|
+
# A matching pair of angle brackets were specified as part of a
|
1734
|
+
# parameter definition, but did not form a valid parameter variable
|
1735
|
+
# specification (that is, it wasn't in the form: <_name_> or
|
1736
|
+
# <_name_:_type_>).
|
1737
|
+
#
|
1738
|
+
# * "Error: bad type in Getopt::Declare parameter variable specification near %s"
|
1739
|
+
#
|
1740
|
+
# An unknown type specifier was used in a parameter variable type suffix.
|
1741
|
+
#
|
1742
|
+
# * "Error: bad action in Getopt::Declare specification:\n %s"
|
1743
|
+
#
|
1744
|
+
# A Perl syntax error was detected in the indicated action.
|
1745
|
+
#
|
1746
|
+
# * "Error: unattached action in Getopt::Declare specification:\n %s"
|
1747
|
+
#
|
1748
|
+
# An action was found for which there was no preceding parameter specification.
|
1749
|
+
# This usually occurs because the trailing tab was omitted from the preceding
|
1750
|
+
# parameter specification.
|
1751
|
+
#
|
1752
|
+
# * "Error: incomplete action in Getopt::Declare specification:\n %s"
|
1753
|
+
#
|
1754
|
+
# An action was found, but it was missing one or more closing '}'s.
|
1755
|
+
#
|
1756
|
+
# * "Error: bad condition in directive [requires: %s]\n"
|
1757
|
+
#
|
1758
|
+
# The condition specified as part of the indicated <tt>[requires:...]</tt>
|
1759
|
+
# directive was not a well-formed boolean expression. Common problems
|
1760
|
+
# include: omitting a <tt>&&</tt>/<tt>||</tt> operator between two flags,
|
1761
|
+
# mismatched brackets, or using <tt>and</tt>/<tt>or</tt> instead of <tt>&&</tt>/<tt>||</tt>.
|
1762
|
+
#
|
1763
|
+
# * "Error: in generated command-line parser code:\n %s"
|
1764
|
+
#
|
1765
|
+
# Either there was a Ruby syntax error in one some action (which was
|
1766
|
+
# not caught by the previous diagnostic), or (less likely) there is a
|
1767
|
+
# bug in the code generator inside Getopt::Declare.
|
1768
|
+
#
|
1769
|
+
# * "Error: incorrect specification of %s parameter"
|
1770
|
+
#
|
1771
|
+
# The flag for the indicated parameter was found, but the argument did not
|
1772
|
+
# then match any of that parameter's variant syntaxes.
|
1773
|
+
#
|
1774
|
+
# * "Error: parameter %s not allowed with %s"
|
1775
|
+
#
|
1776
|
+
# Two mutually exclusive flags were specified together.
|
1777
|
+
#
|
1778
|
+
# * "Error: required parameter %s not found"
|
1779
|
+
#
|
1780
|
+
# No argument matching the specified "required" parameter was found
|
1781
|
+
# during command-line processing.
|
1782
|
+
#
|
1783
|
+
# * "Error: parameter %s can only be specified with %s"
|
1784
|
+
#
|
1785
|
+
# The indicated parameter has a <tt>[requires:...]</tt> directive, which
|
1786
|
+
# was not satisfied.
|
1787
|
+
#
|
1788
|
+
# * "Error: unknown command-line argument (%s)"
|
1789
|
+
#
|
1790
|
+
# A command-line argument was encountered which did not match any
|
1791
|
+
# specified parameter. This diagnostic can only only appear if the
|
1792
|
+
# "strict" option is in effect.
|
1793
|
+
#
|
1794
|
+
# * "Error: in parameter %s (%s must be an integer greater than zero)"
|
1795
|
+
#
|
1796
|
+
# A parameter variable in the indicated parameter was declared with the
|
1797
|
+
# type ":+i" (or a type derived from it), but the corresponding
|
1798
|
+
# argument was not a positive, non-zero integer.
|
1799
|
+
#
|
1800
|
+
# * "Error: in parameter %s (%s must be a number greater than zero)"
|
1801
|
+
#
|
1802
|
+
# A parameter variable in the indicated parameter was declared with the
|
1803
|
+
# type ":+n" (or a type derived from it), but the corresponding
|
1804
|
+
# argument was not a positive, non-zero number.
|
1805
|
+
#
|
1806
|
+
# * "Error: in parameter %s (%s must be an positive integer)"
|
1807
|
+
#
|
1808
|
+
# A parameter variable in the indicated parameter was declared with the
|
1809
|
+
# type ":0+i" (or a type derived from it), but the corresponding
|
1810
|
+
# argument was not a positive integer.
|
1811
|
+
#
|
1812
|
+
# * "Error: in parameter %s (%s must be a positive number)"
|
1813
|
+
#
|
1814
|
+
# A parameter variable in the indicated parameter was declared with the
|
1815
|
+
# type ":0+n" (or a type derived from it), but the corresponding
|
1816
|
+
# argument was not a positive number.
|
1817
|
+
#
|
1818
|
+
# = AUTHORS
|
1819
|
+
#
|
1820
|
+
# Damian Conway (damian@conway.org) Perl Implementation.
|
1821
|
+
#
|
1822
|
+
# Gonzalo Garramuno (GGarramuno@aol.com) Ruby Port, Minor Bug Fixes,
|
1823
|
+
# Inline docs, and :d stdtype.
|
1824
|
+
##
|
1825
|
+
# = BUGS AND ANNOYANCES
|
1826
|
+
#
|
1827
|
+
# There are undoubtedly serious bugs lurking somewhere in this code.
|
1828
|
+
#
|
1829
|
+
# If nothing else, it shouldn't take 1500 lines to explain a
|
1830
|
+
# package that was designed for intuitive ease of use!
|
1831
|
+
#
|
1832
|
+
# Bug reports and other feedback are most welcome.
|
1833
|
+
#
|
1834
|
+
#
|
1835
|
+
# = COPYRIGHT
|
1836
|
+
#
|
1837
|
+
# Ruby Port:
|
1838
|
+
# Copyright (c) 2004, Gonzalo Garramuno. All Rights Reserved.
|
1839
|
+
# This package is free software. It may be used, redistributed
|
1840
|
+
# and/or modified under the terms of the Perl Artistic License
|
1841
|
+
# (see http://www.perl.com/perl/misc/Artistic.html)
|
1842
|
+
#
|
1843
|
+
# Original Perl Code:
|
1844
|
+
# Copyright (c) 1997-2000, Damian Conway. All Rights Reserved.
|
1845
|
+
# This package is free software. It may be used, redistributed
|
1846
|
+
# and/or modified under the terms of the Perl Artistic License
|
1847
|
+
# (see http://www.perl.com/perl/misc/Artistic.html)
|
1848
|
+
#
|
1849
|
+
# This Getopt::Declare module relies on a custom version of DelimScanner.rb,
|
1850
|
+
# which is roughly a port of Perl's Text::Balanced.
|
1851
|
+
# The main change added to that library was to add returning :suffix to several
|
1852
|
+
# functions. DelimScanner.rb is:
|
1853
|
+
#
|
1854
|
+
# Copyright (c) 2002, 2003 The FaerieMUD Consortium. Most rights reserved.
|
1855
|
+
#
|
1856
|
+
# This work is licensed under the Creative Commons Attribution License. To view
|
1857
|
+
# a copy of this license, visit http://creativecommons.org/licenses/by/1.0 or
|
1858
|
+
# send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California
|
1859
|
+
# 94305, USA.
|
1860
|
+
|
1861
|
+
|