| 1 |
NAME |
| 2 |
|
| 3 |
Getopt::Euclid - Executable Uniform Command-Line Interface Descriptions |
| 4 |
|
| 5 |
VERSION |
| 6 |
|
| 7 |
This document describes Getopt::Euclid version 0.4.5 |
| 8 |
|
| 9 |
SYNOPSIS |
| 10 |
|
| 11 |
use Getopt::Euclid; |
| 12 |
|
| 13 |
if ($ARGV{-i}) { |
| 14 |
print "Interactive mode...\n"; |
| 15 |
} |
| 16 |
|
| 17 |
for my $x (0..$ARGV{-size}{h}-1) { |
| 18 |
for my $y (0..$ARGV{-size}{w}-1) { |
| 19 |
do_something_with($x, $y); |
| 20 |
} |
| 21 |
} |
| 22 |
|
| 23 |
__END__ |
| 24 |
|
| 25 |
=head1 NAME |
| 26 |
|
| 27 |
yourprog - Your program here |
| 28 |
|
| 29 |
=head1 VERSION |
| 30 |
|
| 31 |
This documentation refers to yourprog version 1.9.4 |
| 32 |
|
| 33 |
=head1 USAGE |
| 34 |
|
| 35 |
yourprog [options] -s[ize]=<h>x<w> -o[ut][file] <file> |
| 36 |
|
| 37 |
=head1 REQUIRED ARGUMENTS |
| 38 |
|
| 39 |
=over |
| 40 |
|
| 41 |
=item -s[ize]=<h>x<w> |
| 42 |
|
| 43 |
Specify size of simulation |
| 44 |
|
| 45 |
=for Euclid: |
| 46 |
h.type: int > 0 |
| 47 |
h.default: 24 |
| 48 |
w.type: int >= 10 |
| 49 |
w.default: 80 |
| 50 |
|
| 51 |
=item -o[ut][file] <file> |
| 52 |
|
| 53 |
Specify output file |
| 54 |
|
| 55 |
=for Euclid: |
| 56 |
file.type: writable |
| 57 |
file.default: '-' |
| 58 |
|
| 59 |
=back |
| 60 |
|
| 61 |
=head1 OPTIONS |
| 62 |
|
| 63 |
=over |
| 64 |
|
| 65 |
=item -i |
| 66 |
|
| 67 |
Specify interactive simulation |
| 68 |
|
| 69 |
=item -l[[en][gth]] <l> |
| 70 |
|
| 71 |
Length of simulation. The default is l.default |
| 72 |
|
| 73 |
=for Euclid: |
| 74 |
l.type: int > 0 |
| 75 |
l.default: 99 |
| 76 |
|
| 77 |
=item --debug [<log_level>] |
| 78 |
|
| 79 |
Set the log level. Default is log_level.default but if you provide --debug, |
| 80 |
then it is log_level.opt_default. |
| 81 |
|
| 82 |
=for Euclid: |
| 83 |
log_level.type: int |
| 84 |
log_level.default: 0 |
| 85 |
log_level.opt_default: 1 |
| 86 |
|
| 87 |
=item --version |
| 88 |
|
| 89 |
=item --usage |
| 90 |
|
| 91 |
=item --help |
| 92 |
|
| 93 |
=item --man |
| 94 |
|
| 95 |
Print the usual program information |
| 96 |
|
| 97 |
=back |
| 98 |
|
| 99 |
Remainder of documentation starts here... |
| 100 |
|
| 101 |
=head1 AUTHOR |
| 102 |
|
| 103 |
Damian Conway ([email protected]) |
| 104 |
|
| 105 |
=head1 BUGS |
| 106 |
|
| 107 |
There are undoubtedly serious bugs lurking somewhere in this code. |
| 108 |
Bug reports and other feedback are most welcome. |
| 109 |
|
| 110 |
=head1 COPYRIGHT |
| 111 |
|
| 112 |
Copyright (c) 2005, Damian Conway. All Rights Reserved. |
| 113 |
This module is free software. It may be used, redistributed |
| 114 |
and/or modified under the terms of the Perl Artistic License |
| 115 |
(see http://www.perl.com/perl/misc/Artistic.html) |
| 116 |
|
| 117 |
DESCRIPTION |
| 118 |
|
| 119 |
Getopt::Euclid uses your program's own POD documentation to create a |
| 120 |
powerful command-line argument parser. This ensures that your program's |
| 121 |
documented interface and its actual interface always agree. |
| 122 |
|
| 123 |
The created command-line argument parser includes many features such as |
| 124 |
argument type checking, required arguments, exclusive arguments, |
| 125 |
optional arguments with default values, automatic usage message, ... |
| 126 |
|
| 127 |
To use the module, simply write the following at the top of your |
| 128 |
program: |
| 129 |
|
| 130 |
use Getopt::Euclid; |
| 131 |
|
| 132 |
This will cause Getopt::Euclid to be require'd and its import method |
| 133 |
will be called. It is important that the import method be allowed to |
| 134 |
run, so do not invoke Getopt::Euclid in the following manner: |
| 135 |
|
| 136 |
# Will not work |
| 137 |
use Getopt::Euclid (); |
| 138 |
|
| 139 |
When the module is loaded within a regular Perl program, it will: |
| 140 |
|
| 141 |
1. locate any POD in the same *.pl file or its associated *.pod file. |
| 142 |
|
| 143 |
2. extract information from that POD, most especially from the =head1 |
| 144 |
REQUIRED ARGUMENTS and =head1 OPTIONS sections, |
| 145 |
|
| 146 |
3. build a parser that parses the arguments and options the POD |
| 147 |
specifies, |
| 148 |
|
| 149 |
4. remove the command-line arguments from @ARGV and parse them, and |
| 150 |
|
| 151 |
5. put the results in the global %ARGV variable (or into specifically |
| 152 |
named optional variables, if you request that -- see "Exporting |
| 153 |
option variables"). |
| 154 |
|
| 155 |
As a special case, if the module is loaded within some other module |
| 156 |
(i.e. from within a .pm file), it still locates and extracts POD |
| 157 |
information, but instead of parsing @ARGV immediately, it caches that |
| 158 |
information and installs an import() subroutine in the caller module. |
| 159 |
This new import() acts just like Getopt::Euclid's own import, except |
| 160 |
that it adds the POD from the caller module to the POD of the callee. |
| 161 |
|
| 162 |
All of which just means you can put some or all of your CLI |
| 163 |
specification in a module, rather than in the application's source |
| 164 |
file. See "Module interface" for more details. |
| 165 |
|
| 166 |
INTERFACE |
| 167 |
|
| 168 |
Program interface |
| 169 |
|
| 170 |
You write: |
| 171 |
|
| 172 |
use Getopt::Euclid; |
| 173 |
|
| 174 |
and your command-line is parsed automagically. |
| 175 |
|
| 176 |
Module interface |
| 177 |
|
| 178 |
import() |
| 179 |
|
| 180 |
You write: |
| 181 |
|
| 182 |
use Getopt::Euclid; |
| 183 |
|
| 184 |
and your module will then act just like Getopt::Euclid (i.e. you can |
| 185 |
use your module instead of Getopt::Euclid>, except that your module's |
| 186 |
POD will also be prepended to the POD of any module that loads yours. |
| 187 |
In other words, you can use Getopt::Euclid in a module to create a |
| 188 |
standard set of CLI arguments, which can then be added to any |
| 189 |
application simply by loading your module. |
| 190 |
|
| 191 |
To accomplish this trick Getopt::Euclid installs an import() |
| 192 |
subroutine in your module. If your module already has an import() |
| 193 |
subroutine defined, terrible things happen. So do not do that. |
| 194 |
|
| 195 |
You may also short-circuit the import method within your calling |
| 196 |
program to have the POD from several modules included for argument |
| 197 |
parsing. |
| 198 |
|
| 199 |
use Module1::Getopt (); # No argument parsing |
| 200 |
use Module2::Getopt (); # No argument parsing |
| 201 |
use Getopt::Euclid; # Arguments parsed |
| 202 |
|
| 203 |
process_args() |
| 204 |
|
| 205 |
Alternatively, to parse arguments from a source different from @ARGV, |
| 206 |
use the process_args() subroutine. |
| 207 |
|
| 208 |
use Getopt::Euclid qw(:defer); |
| 209 |
my @args = ( '-in', 'file.txt', '-out', 'results.txt' ); |
| 210 |
Getopt::Euclid->process_args(\@args); |
| 211 |
|
| 212 |
If you want to use the :minimal or :vars mode in this type of |
| 213 |
scenario, you can pass extra options to process_args(): |
| 214 |
|
| 215 |
use Getopt::Euclid qw(:defer); |
| 216 |
my @args = ( '-in', 'file.txt', '-out', 'results.txt' ); |
| 217 |
Getopt::Euclid->process_args(\@args, {-minimal => 1, -vars => 'prefix_'}); |
| 218 |
|
| 219 |
This is particularly when you plan on processing POD manually. |
| 220 |
|
| 221 |
process_pods() |
| 222 |
|
| 223 |
Similarly, to parse argument specifications from a source different |
| 224 |
than the current script (and its dependencies), use the |
| 225 |
process_pods() subroutine. |
| 226 |
|
| 227 |
use Getopt::Euclid (); |
| 228 |
my @pods = ( 'script.pl', 'Module.pm' ); |
| 229 |
$Getopt::Euclid::MAN = Getopt::Euclid->process_pods(\@pods, {-strict => 1}); |
| 230 |
my @args = ( '-in', 'file.txt', '-out', 'results.txt' ); |
| 231 |
Getopt::Euclid->process_args(\@args); |
| 232 |
|
| 233 |
By default, this method will look for .pod files associated with the |
| 234 |
given .pl and .pm files and use these .pod files preferentially when |
| 235 |
available. Set -strict to 1 to only use the given files. |
| 236 |
|
| 237 |
POD interface |
| 238 |
|
| 239 |
This is where all the action is. POD markup can be placed in a .pod |
| 240 |
file that has the same prefix as the corresponding Perl file. |
| 241 |
Alternatively, POD can be inserted anywhere in the Perl code, but is |
| 242 |
typically added either after an __END__ statement (like in the |
| 243 |
SYNOPSIS), or interspersed in the code: |
| 244 |
|
| 245 |
use Getopt::Euclid; |
| 246 |
|
| 247 |
=head1 NAME |
| 248 |
|
| 249 |
yourprog - Your program here |
| 250 |
|
| 251 |
=head1 REQUIRED ARGUMENTS |
| 252 |
|
| 253 |
=over |
| 254 |
|
| 255 |
=item -s[ize]=<h>x<w> |
| 256 |
|
| 257 |
Specify size of simulation |
| 258 |
|
| 259 |
=for Euclid: |
| 260 |
h.type: int > 0 |
| 261 |
h.default: 24 |
| 262 |
w.type: int >= 10 |
| 263 |
w.default: 80 |
| 264 |
|
| 265 |
=back |
| 266 |
|
| 267 |
=head1 OPTIONS |
| 268 |
|
| 269 |
=over |
| 270 |
|
| 271 |
=item -i |
| 272 |
|
| 273 |
Specify interactive simulation |
| 274 |
|
| 275 |
=back |
| 276 |
|
| 277 |
=cut |
| 278 |
|
| 279 |
# Getopt::Euclid has parsed commandline parameters and stored them in %ARGV |
| 280 |
|
| 281 |
if ($ARGV{-i}) { |
| 282 |
print "Interactive mode...\n"; |
| 283 |
} |
| 284 |
|
| 285 |
for my $x (0..$ARGV{-size}{h}-1) { |
| 286 |
for my $y (0..$ARGV{-size}{w}-1) { |
| 287 |
do_something_with($x, $y); |
| 288 |
} |
| 289 |
} |
| 290 |
|
| 291 |
When Getopt::Euclid is loaded in a non-.pm file, it searches that file |
| 292 |
for the following POD documentation: |
| 293 |
|
| 294 |
=head1 NAME |
| 295 |
|
| 296 |
Getopt::Euclid ignores the name specified here. In fact, if you use |
| 297 |
the standard --help, --usage, --man, --podfile, or --version |
| 298 |
arguments (see "Standard arguments"), the module replaces the name |
| 299 |
specified in this POD section with the actual name by which the |
| 300 |
program was invoked (i.e. with $0). |
| 301 |
|
| 302 |
=head1 USAGE |
| 303 |
|
| 304 |
Getopt::Euclid ignores the usage line specified here. If you use the |
| 305 |
standard --help, --usage, --man or --podfile arguments, the module |
| 306 |
replaces the usage line specified in this POD section with a usage |
| 307 |
line that reflects the actual interface that the module has |
| 308 |
constructed. |
| 309 |
|
| 310 |
=head1 VERSION |
| 311 |
|
| 312 |
Getopt::Euclid extracts the current version number from this POD |
| 313 |
section. To do that it simply takes the first substring that matches |
| 314 |
<digit>.<digit> or <digit>_<digit>. It also accepts one or more |
| 315 |
additional trailing .<digit> or _<digit>, allowing for multi-level |
| 316 |
and "alpha" version numbers such as: |
| 317 |
|
| 318 |
=head1 VERSION |
| 319 |
|
| 320 |
This is version 1.2.3 |
| 321 |
|
| 322 |
or: |
| 323 |
|
| 324 |
=head1 VERSION |
| 325 |
|
| 326 |
This is alpha release 1.2_34 |
| 327 |
|
| 328 |
You may also specify the version number in your code. However, in |
| 329 |
order for Getopt::Euclid to properly read it, it must be in a BEGIN |
| 330 |
block: |
| 331 |
|
| 332 |
BEGIN { use version; our $VERSION = qv('1.2.3') } |
| 333 |
use Getopt::Euclid; |
| 334 |
|
| 335 |
Euclid stores the version as $Getopt::Euclid::SCRIPT_VERSION. |
| 336 |
|
| 337 |
=head1 REQUIRED ARGUMENTS |
| 338 |
|
| 339 |
Getopt::Euclid uses the specifications in this POD section to build a |
| 340 |
parser for command-line arguments. That parser requires that every |
| 341 |
one of the specified arguments is present in any command-line |
| 342 |
invocation. See "Specifying arguments" for details of the |
| 343 |
specification syntax. |
| 344 |
|
| 345 |
The actual headings that Getopt::Euclid can recognize here are: |
| 346 |
|
| 347 |
=head1 [STANDARD|STD|PROGRAM|SCRIPT|CLI|COMMAND[-| ]LINE] [REQUIRED|MANDATORY] [PARAM|PARAMETER|ARG|ARGUMENT][S] |
| 348 |
|
| 349 |
Caveat: Do not put additional subheadings (=headX) inside the |
| 350 |
REQUIRED ARGUMENTS section. |
| 351 |
|
| 352 |
=head1 OPTIONS |
| 353 |
|
| 354 |
Getopt::Euclid uses the specifications in this POD section to build a |
| 355 |
parser for command-line arguments. That parser does not require that |
| 356 |
any of the specified arguments is actually present in a command-line |
| 357 |
invocation. Again, see "Specifying arguments" for details of the |
| 358 |
specification syntax. |
| 359 |
|
| 360 |
Typically a program will specify both REQUIRED ARGUMENTS and OPTIONS, |
| 361 |
but there is no requirement that it supply both, or either. |
| 362 |
|
| 363 |
The actual headings that Getopt::Euclid recognizes here are: |
| 364 |
|
| 365 |
=head1 [STANDARD|STD|PROGRAM|SCRIPT|CLI|COMMAND[-| ]LINE] OPTION[AL|S] [PARAM|PARAMETER|ARG|ARGUMENT][S] |
| 366 |
|
| 367 |
Caveat: Do not put additional subheadings (=headX) inside the |
| 368 |
REQUIRED ARGUMENTS section. |
| 369 |
|
| 370 |
=head1 COPYRIGHT |
| 371 |
|
| 372 |
Getopt::Euclid prints this section whenever the standard --version |
| 373 |
option is specified on the command-line. |
| 374 |
|
| 375 |
The actual heading that Getopt::Euclid recognizes here is any heading |
| 376 |
containing any of the words "COPYRIGHT", "LICENCE", or "LICENSE". |
| 377 |
|
| 378 |
Specifying arguments |
| 379 |
|
| 380 |
Each required or optional argument is specified in the POD in the |
| 381 |
following format: |
| 382 |
|
| 383 |
=item ARGUMENT_STRUCTURE |
| 384 |
|
| 385 |
ARGUMENT_DESCRIPTION |
| 386 |
|
| 387 |
=for Euclid: |
| 388 |
ARGUMENT_OPTIONS |
| 389 |
PLACEHOLDER_CONSTRAINTS |
| 390 |
|
| 391 |
Argument structure |
| 392 |
|
| 393 |
* Each argument is specified as an =item. |
| 394 |
|
| 395 |
* Any part(s) of the specification that appear in square brackets are |
| 396 |
treated as optional. |
| 397 |
|
| 398 |
* Any parts that appear in angle brackets are placeholders for actual |
| 399 |
values that must be specified on the command-line. |
| 400 |
|
| 401 |
* Any placeholder that is immediately followed by ... may be repeated |
| 402 |
as many times as desired. |
| 403 |
|
| 404 |
* Any whitespace in the structure specifies that any amount of |
| 405 |
whitespace (including none) is allowed at the same position on the |
| 406 |
command-line. |
| 407 |
|
| 408 |
* A vertical bar indicates the start of an alternative variant of the |
| 409 |
argument. |
| 410 |
|
| 411 |
For example, the argument specification: |
| 412 |
|
| 413 |
=item -i[n] [=] <file> | --from <file> |
| 414 |
|
| 415 |
indicates that any of the following may appear on the command-line: |
| 416 |
|
| 417 |
-idata.txt -i data.txt -i=data.txt -i = data.txt |
| 418 |
|
| 419 |
-indata.txt -in data.txt -in=data.txt -in = data.txt |
| 420 |
|
| 421 |
--from data.text |
| 422 |
|
| 423 |
as well as any other combination of whitespacing. |
| 424 |
|
| 425 |
Any of the above variations would cause all three of: |
| 426 |
|
| 427 |
$ARGV{'-i'} |
| 428 |
$ARGV{'-in'} |
| 429 |
$ARGV{'--from'} |
| 430 |
|
| 431 |
to be set to the string 'data.txt'. |
| 432 |
|
| 433 |
You could allow the optional = to also be an optional colon by |
| 434 |
specifying: |
| 435 |
|
| 436 |
=item -i[n] [=|:] <file> |
| 437 |
|
| 438 |
Optional components may also be nested, so you could write: |
| 439 |
|
| 440 |
=item -i[n[put]] [=] <file> |
| 441 |
|
| 442 |
which would allow -i, -in, and -input as synonyms for this argument and |
| 443 |
would set all three of $ARGV{'-i'}, $ARGV{'-in'}, and $ARGV{'-input'} |
| 444 |
to the supplied file name. |
| 445 |
|
| 446 |
The point of setting every possible variant within %ARGV is that this |
| 447 |
allows you to use a single key (say $ARGV{'-input'}, regardless of how |
| 448 |
the argument is actually specified on the command-line. |
| 449 |
|
| 450 |
Repeatable arguments |
| 451 |
|
| 452 |
Normally Getopt::Euclid only accepts each specified argument once, the |
| 453 |
first time it appears in @ARGV. However, you can specify that an |
| 454 |
argument may appear more than once, using the repeatable option: |
| 455 |
|
| 456 |
=item file=<filename> |
| 457 |
|
| 458 |
=for Euclid: |
| 459 |
repeatable |
| 460 |
|
| 461 |
When an argument is marked repeatable the corresponding entry of %ARGV |
| 462 |
will not contain a single value, but rather an array reference. If the |
| 463 |
argument also has "Multiple placeholders", then the corresponding entry |
| 464 |
in %ARGV will be an array reference with each array entry being a hash |
| 465 |
reference. |
| 466 |
|
| 467 |
Boolean arguments |
| 468 |
|
| 469 |
If an argument has no placeholders it is treated as a boolean switch |
| 470 |
and its entry in %ARGV will be true if the argument appeared in @ARGV. |
| 471 |
|
| 472 |
For a boolean argument, you can also specify variations that are false, |
| 473 |
if they appear. For example, a common idiom is: |
| 474 |
|
| 475 |
=item --print |
| 476 |
|
| 477 |
Print results |
| 478 |
|
| 479 |
=item --noprint |
| 480 |
|
| 481 |
Do not print results |
| 482 |
|
| 483 |
These two arguments are effectively the same argument, just with |
| 484 |
opposite boolean values. However, as specified above, only one of |
| 485 |
$ARGV{'--print'} and $ARGV{'--noprint'} will be set. |
| 486 |
|
| 487 |
As an alternative you can specify a single argument that accepts either |
| 488 |
value and sets both appropriately: |
| 489 |
|
| 490 |
=item --[no]print |
| 491 |
|
| 492 |
[Do not] print results |
| 493 |
|
| 494 |
=for Euclid: |
| 495 |
false: --noprint |
| 496 |
|
| 497 |
With this specification, if --print appears in @ARGV, then |
| 498 |
$ARGV{'--print'} will be true and $ARGV{'--noprint'} will be false. On |
| 499 |
the other hand, if --noprint appears in @ARGV, then $ARGV{'--print'} |
| 500 |
will be false and $ARGV{'--noprint'} will be true. |
| 501 |
|
| 502 |
The specified false values can follow any convention you wish: |
| 503 |
|
| 504 |
=item [+|-]print |
| 505 |
|
| 506 |
=for Euclid: |
| 507 |
false: -print |
| 508 |
|
| 509 |
or: |
| 510 |
|
| 511 |
=item -report[_no[t]] |
| 512 |
|
| 513 |
=for Euclid: |
| 514 |
false: -report_no[t] |
| 515 |
|
| 516 |
et cetera. |
| 517 |
|
| 518 |
Multiple placeholders |
| 519 |
|
| 520 |
An argument can have two or more placeholders: |
| 521 |
|
| 522 |
=item -size <h> <w> |
| 523 |
|
| 524 |
The corresponding command line argument would then have to provide two |
| 525 |
values: |
| 526 |
|
| 527 |
-size 24 80 |
| 528 |
|
| 529 |
Multiple placeholders can optionally be separated by literal characters |
| 530 |
(which must then appear on the command-line). For example: |
| 531 |
|
| 532 |
=item -size <h>x<w> |
| 533 |
|
| 534 |
would then require a command-line of the form: |
| 535 |
|
| 536 |
-size 24x80 |
| 537 |
|
| 538 |
If an argument has two or more placeholders, the corresponding entry in |
| 539 |
%ARGV becomes a hash reference, with each of the placeholder names as |
| 540 |
one key. That is, the above command-line would set both |
| 541 |
$ARGV{'-size'}{'h'} and $ARGV{'-size'}{'w'}. |
| 542 |
|
| 543 |
Optional placeholders |
| 544 |
|
| 545 |
Placeholders can be specified as optional as well: |
| 546 |
|
| 547 |
=item -size <h> [<w>] |
| 548 |
|
| 549 |
This specification then allows either: |
| 550 |
|
| 551 |
-size 24 |
| 552 |
|
| 553 |
or: |
| 554 |
|
| 555 |
-size 24 80 |
| 556 |
|
| 557 |
on the command-line. If the second placeholder value is not provided, |
| 558 |
the corresponding $ARGV{'-size'}{'w'} entry is set to undef. See also |
| 559 |
"Placeholder defaults". |
| 560 |
|
| 561 |
Unflagged placeholders |
| 562 |
|
| 563 |
If an argument consists of a single placeholder with no "flag" marking |
| 564 |
it: |
| 565 |
|
| 566 |
=item <filename> |
| 567 |
|
| 568 |
then the corresponding entry in %ARG will have a key the same as the |
| 569 |
placeholder (including the surrounding angle brackets): |
| 570 |
|
| 571 |
if ($ARGV{'<filename>'} eq '-') { |
| 572 |
$fh = \*STDIN; |
| 573 |
} |
| 574 |
|
| 575 |
The same is true for any more-complicated arguments that begin with a |
| 576 |
placeholder: |
| 577 |
|
| 578 |
=item <h> [x <w>] |
| 579 |
|
| 580 |
The only difference in the more-complex cases is that, if the argument |
| 581 |
has any additional placeholders, the entire entry in %ARGV becomes a |
| 582 |
hash: |
| 583 |
|
| 584 |
my $total_size |
| 585 |
= $ARGV{'<h>'}{'h'} * $ARGV{'<h>'}{'w'} |
| 586 |
|
| 587 |
Note that, as in earlier multi-placeholder examples, the individual |
| 588 |
second- level placeholder keys do not retain their angle-brackets. |
| 589 |
|
| 590 |
Repeated placeholders |
| 591 |
|
| 592 |
Any placeholder that is immediately followed by ..., like so: |
| 593 |
|
| 594 |
=item -lib <file>... |
| 595 |
|
| 596 |
=for Euclid: |
| 597 |
file.type: readable |
| 598 |
|
| 599 |
will match at least once, but as many times as possible before |
| 600 |
encountering the next argument on the command-line. This allows one to |
| 601 |
specify multiple values for an argument, for example: |
| 602 |
|
| 603 |
-lib file1.txt file2.txt |
| 604 |
|
| 605 |
An unconstrained repeated unflagged placeholder (see "Placeholder |
| 606 |
constraints" and "Unflagged placeholders") will consume the rest of the |
| 607 |
command-line, and so should be specified last in the POD |
| 608 |
|
| 609 |
=item -n <name> |
| 610 |
|
| 611 |
=item <offset>... |
| 612 |
|
| 613 |
=for Euclid: |
| 614 |
offset.type: 0+int |
| 615 |
|
| 616 |
and on the command-line: |
| 617 |
|
| 618 |
-n foobar 1 5 0 23 |
| 619 |
|
| 620 |
If a placeholder is repeated, the corresponding entry in %ARGV will |
| 621 |
then be an array reference, with each individual placeholder match in a |
| 622 |
separate element. For example: |
| 623 |
|
| 624 |
for my $lib (@{ $ARGV{'-lib'} }) { |
| 625 |
add_lib($lib); |
| 626 |
} |
| 627 |
|
| 628 |
warn "First offset is: $ARGV{'<offsets>'}[0]"; |
| 629 |
my $first_offset = shift @{ $ARGV{'<offsets>'} }; |
| 630 |
|
| 631 |
Placeholder constraints |
| 632 |
|
| 633 |
You can specify that the value provided for a particular placeholder |
| 634 |
must satisfy a particular set of restrictions by using a =for Euclid |
| 635 |
block. For example: |
| 636 |
|
| 637 |
=item -size <h>x<w> |
| 638 |
|
| 639 |
=for Euclid: |
| 640 |
h.type: integer |
| 641 |
w.type: integer |
| 642 |
|
| 643 |
specifies that both the <h> and <w> must be given integers. You can |
| 644 |
also specify an operator expression after the type name: |
| 645 |
|
| 646 |
=for Euclid: |
| 647 |
h.type: integer > 0 |
| 648 |
w.type: number <= 100 |
| 649 |
|
| 650 |
specifies that <h> has to be given an integer that is greater than |
| 651 |
zero, and that <w> has to be given a number (not necessarily an |
| 652 |
integer) that is no more than 100. |
| 653 |
|
| 654 |
These type constraints have two alternative syntaxes: |
| 655 |
|
| 656 |
PLACEHOLDER.type: TYPE BINARY_OPERATOR EXPRESSION |
| 657 |
|
| 658 |
as shown above, and the more general: |
| 659 |
|
| 660 |
PLACEHOLDER.type: TYPE [, EXPRESSION_INVOLVING(PLACEHOLDER)] |
| 661 |
|
| 662 |
Using the second syntax, you could write the previous constraints as: |
| 663 |
|
| 664 |
=for Euclid: |
| 665 |
h.type: integer, h > 0 |
| 666 |
w.type: number, w <= 100 |
| 667 |
|
| 668 |
In other words, the first syntax is just sugar for the most common case |
| 669 |
of the second syntax. The expression can be as complex as you wish and |
| 670 |
can refer to the placeholder as many times as necessary: |
| 671 |
|
| 672 |
=for Euclid: |
| 673 |
h.type: integer, h > 0 && h < 100 |
| 674 |
w.type: number, Math::is_prime(w) || w % 2 == 0 |
| 675 |
|
| 676 |
Note that the expressions are evaluated in the package main namespace, |
| 677 |
so it is important to qualify any subroutines that are not in that |
| 678 |
namespace. Furthermore, any subroutines used must be defined (or loaded |
| 679 |
from a module) before the use Getopt::Euclid statement. |
| 680 |
|
| 681 |
You can also use constraints that involve variables. You must use the |
| 682 |
:defer mode and the variables must be globally accessible: |
| 683 |
|
| 684 |
use Getopt::Euclid qw(:defer); |
| 685 |
our $MIN_VAL = 100; |
| 686 |
Getopt::Euclid->process_args(\@ARGV); |
| 687 |
|
| 688 |
__END__ |
| 689 |
|
| 690 |
=head1 OPTIONS |
| 691 |
|
| 692 |
=over |
| 693 |
|
| 694 |
=item --magnitude <magnitude> |
| 695 |
|
| 696 |
=for Euclid |
| 697 |
magnitude.type: number, magnitude > $MIN_VAL |
| 698 |
|
| 699 |
=back |
| 700 |
|
| 701 |
Standard placeholder types |
| 702 |
|
| 703 |
Getopt::Euclid recognizes the following standard placeholder types: |
| 704 |
|
| 705 |
Name Placeholder value... Synonyms |
| 706 |
============ ==================== ================ |
| 707 |
|
| 708 |
integer ...must be an integer int i |
| 709 |
|
| 710 |
+integer ...must be a positive +int +i |
| 711 |
integer |
| 712 |
(same as: integer > 0) |
| 713 |
|
| 714 |
0+integer ...must be a positive 0+int 0+i |
| 715 |
integer or zero |
| 716 |
(same as: integer >= 0) |
| 717 |
|
| 718 |
number ...must be an number num n |
| 719 |
|
| 720 |
+number ...must be a positive +num +n |
| 721 |
number |
| 722 |
(same as: number > 0) |
| 723 |
|
| 724 |
0+number ...must be a positive 0+num 0+n |
| 725 |
number or zero |
| 726 |
(same as: number >= 0) |
| 727 |
|
| 728 |
string ...may be any string str s |
| 729 |
(default type) |
| 730 |
|
| 731 |
readable ...must be the name input in |
| 732 |
of a readable file |
| 733 |
|
| 734 |
writeable ...must be the name writable output out |
| 735 |
of a writeable file |
| 736 |
(or of a non-existent |
| 737 |
file in a writeable |
| 738 |
directory) |
| 739 |
|
| 740 |
/<regex>/ ...must be a string |
| 741 |
matching the specified |
| 742 |
pattern |
| 743 |
|
| 744 |
Since regular expressions are supported, you can easily match many more |
| 745 |
type of strings for placeholders by using the regular expressions |
| 746 |
available in Regexp::Common. If you do that, you may want to also use |
| 747 |
custom placeholder error messages (see "Placeholder type errors") since |
| 748 |
the messages would otherwise not be very informative to users. |
| 749 |
|
| 750 |
use Regexp::Common qw /zip/; |
| 751 |
use Getopt::Euclid; |
| 752 |
|
| 753 |
... |
| 754 |
|
| 755 |
=item -p <postcode> |
| 756 |
|
| 757 |
Enter your postcode here |
| 758 |
|
| 759 |
=for Euclid: |
| 760 |
postcode.type: /$RE{zip}{France}/ |
| 761 |
postcode.type.error: <postcode> must be a valid ZIP code |
| 762 |
|
| 763 |
Placeholder type errors |
| 764 |
|
| 765 |
If a command-line argument's placeholder value does not satisify the |
| 766 |
specified type, an error message is automatically generated. However, |
| 767 |
you can provide your own message instead, using the .type.error |
| 768 |
specifier: |
| 769 |
|
| 770 |
=for Euclid: |
| 771 |
h.type: integer, h > 0 && h < 100 |
| 772 |
h.type.error: <h> must be between 0 and 100 (not h) |
| 773 |
|
| 774 |
w.type: number, Math::is_prime(w) || w % 2 == 0 |
| 775 |
w.type.error: Cannot use w for <w> (must be an even prime number) |
| 776 |
|
| 777 |
Whenever an explicit error message is provided, any occurrence within |
| 778 |
the message of the placeholder's unbracketed name is replaced by the |
| 779 |
placeholder's value (just as in the type test itself). |
| 780 |
|
| 781 |
Placeholder defaults |
| 782 |
|
| 783 |
You can also specify a default value for any placeholders that are not |
| 784 |
given values on the command-line (either because their argument is not |
| 785 |
provided at all, or because the placeholder is optional within the |
| 786 |
argument). For example: |
| 787 |
|
| 788 |
=item -size <h>[x<w>] |
| 789 |
|
| 790 |
Set the size of the simulation |
| 791 |
|
| 792 |
=for Euclid: |
| 793 |
h.default: 24 |
| 794 |
w.default: 80 |
| 795 |
|
| 796 |
This ensures that if no <w> value is supplied: |
| 797 |
|
| 798 |
-size 20 |
| 799 |
|
| 800 |
then $ARGV{'-size'}{'w'} is set to 80. Likewise, of the -size argument |
| 801 |
is omitted entirely, both $ARGV{'-size'}{'h'} and $ARGV{'-size'}{'w'} |
| 802 |
are set to their respective default values |
| 803 |
|
| 804 |
However, Getopt::Euclid also supports a second type of default, |
| 805 |
optional defaults, that apply only to flagged, optional placeholders. |
| 806 |
|
| 807 |
For example: |
| 808 |
|
| 809 |
=item --debug [<log_level>] |
| 810 |
|
| 811 |
Set the log level |
| 812 |
|
| 813 |
=for Euclid: |
| 814 |
log_level.type: int |
| 815 |
log_level.default: 0 |
| 816 |
log_level.opt_default: 1 |
| 817 |
|
| 818 |
This ensures that if the option --debug is not specified, then |
| 819 |
$ARGV{'--debug'} is set to 0, the regular default. But if no |
| 820 |
<log_level> value is supplied: |
| 821 |
|
| 822 |
--debug |
| 823 |
|
| 824 |
|
| 825 |
then $ARGV{'--debug'} is set to 1, the optional default. |
| 826 |
|
| 827 |
The default value can be any valid Perl compile-time expression: |
| 828 |
|
| 829 |
=item -pi=<pi value> |
| 830 |
|
| 831 |
=for Euclid: |
| 832 |
pi value.default: atan2(0,-1) |
| 833 |
|
| 834 |
You can refer to an argument default or optional default value in its |
| 835 |
POD entry as shown below: |
| 836 |
|
| 837 |
=item -size <h>[x<w>] |
| 838 |
|
| 839 |
Set the size of the simulation [default: h.default x w.default] |
| 840 |
|
| 841 |
=for Euclid: |
| 842 |
h.default: 24 |
| 843 |
w.default: 80 |
| 844 |
|
| 845 |
=item --debug <level> |
| 846 |
|
| 847 |
Set the debug level. The default is level.default if you supply --debug but |
| 848 |
omit a <level> value. |
| 849 |
|
| 850 |
=for Euclid: |
| 851 |
level.opt_default: 3 |
| 852 |
|
| 853 |
Just like for "Placeholder constraints", you can also use variables to |
| 854 |
define default values. You must use the :defer mode and the variables |
| 855 |
must be globally accessible: |
| 856 |
|
| 857 |
use Getopt::Euclid qw(:defer); |
| 858 |
Getopt::Euclid->process_args(\@ARGV); |
| 859 |
|
| 860 |
__END__ |
| 861 |
|
| 862 |
=head1 OPTIONS |
| 863 |
|
| 864 |
=over |
| 865 |
|
| 866 |
=item --home <home> |
| 867 |
|
| 868 |
Your project home. When omitted, this defaults to the location stored in |
| 869 |
the HOME environment variable. |
| 870 |
|
| 871 |
=for Euclid |
| 872 |
home.default: $ENV{'HOME'} |
| 873 |
|
| 874 |
=back |
| 875 |
|
| 876 |
Exclusive placeholders |
| 877 |
|
| 878 |
Some arguments can be mutually exclusive. In this case, it is possible |
| 879 |
to specify that a placeholder excludes a list of other placeholders, |
| 880 |
for example: |
| 881 |
|
| 882 |
=item -height <h> |
| 883 |
|
| 884 |
Set the desired height |
| 885 |
|
| 886 |
=item -width <w> |
| 887 |
|
| 888 |
Set the desired width |
| 889 |
|
| 890 |
=item -volume <v> |
| 891 |
|
| 892 |
Set the desired volume |
| 893 |
|
| 894 |
=for Euclid: |
| 895 |
v.excludes: h, w |
| 896 |
v.excludes.error: Either set the volume or the height and weight |
| 897 |
|
| 898 |
Specifying both placeholders at the same time on the command-line will |
| 899 |
generate an error. Note that the error message can be customized, as |
| 900 |
illustrated above. |
| 901 |
|
| 902 |
When using exclusive arguments that have default values, the default |
| 903 |
value of the placeholder with the .excludes statement has precedence |
| 904 |
over any other placeholders. |
| 905 |
|
| 906 |
Argument cuddling |
| 907 |
|
| 908 |
Getopt::Euclid allows any "flag" argument to be "cuddled". A flag |
| 909 |
argument consists of a single non- alphanumeric character, followed by |
| 910 |
a single alpha-numeric character: |
| 911 |
|
| 912 |
=item -v |
| 913 |
|
| 914 |
=item -x |
| 915 |
|
| 916 |
=item +1 |
| 917 |
|
| 918 |
=item =z |
| 919 |
|
| 920 |
Cuddling means that two or more such arguments can be concatenated |
| 921 |
after a single common non-alphanumeric. For example: |
| 922 |
|
| 923 |
-vx |
| 924 |
|
| 925 |
Note, however, that only flags with the same leading non-alphanumeric |
| 926 |
can be cuddled together. Getopt::Euclid would not allow: |
| 927 |
|
| 928 |
-vxz |
| 929 |
|
| 930 |
This is because cuddling is recognized by progressively removing the |
| 931 |
second character of the cuddle. In other words: |
| 932 |
|
| 933 |
-vxz |
| 934 |
|
| 935 |
becomes: |
| 936 |
|
| 937 |
-v -xz |
| 938 |
|
| 939 |
which becomes: |
| 940 |
|
| 941 |
-v -x z |
| 942 |
|
| 943 |
which will fail, unless a z argument has also been specified. |
| 944 |
|
| 945 |
On the other hand, if the argument: |
| 946 |
|
| 947 |
=item -e <cmd> |
| 948 |
|
| 949 |
had been specified, the module would accept: |
| 950 |
|
| 951 |
-vxe'print time' |
| 952 |
|
| 953 |
as a cuddled version of: |
| 954 |
|
| 955 |
-v -x -e'print time' |
| 956 |
|
| 957 |
Exporting option variables |
| 958 |
|
| 959 |
By default, the module only stores arguments into the global %ARGV |
| 960 |
hash. You can request that options are exported as variables into the |
| 961 |
calling package using the special ':vars' specifier: |
| 962 |
|
| 963 |
use Getopt::Euclid qw( :vars ); |
| 964 |
|
| 965 |
That is, if your program accepts the following arguments: |
| 966 |
|
| 967 |
-v |
| 968 |
--mode <modename> |
| 969 |
<infile> |
| 970 |
<outfile> |
| 971 |
--auto-fudge <factor> (repeatable) |
| 972 |
--also <a>... |
| 973 |
--size <w>x<h> |
| 974 |
--multiply <num1>x<num2> (repeatable) |
| 975 |
|
| 976 |
Then these variables will be exported |
| 977 |
|
| 978 |
$ARGV_v |
| 979 |
$ARGV_mode |
| 980 |
$ARGV_infile |
| 981 |
$ARGV_outfile |
| 982 |
@ARGV_auto_fudge |
| 983 |
@ARGV_also |
| 984 |
%ARGV_size # With entries $ARGV_size{w} and $ARGV_size{h} |
| 985 |
@ARGV_multiply # With entries that are hashref similar to \%ARGV_size |
| 986 |
|
| 987 |
For options that have multiple variants, only the longest variant is |
| 988 |
exported. |
| 989 |
|
| 990 |
The type of variable exported (scalar, hash, or array) is determined by |
| 991 |
the type of the corresponding value in %ARGV. Command-line flags and |
| 992 |
arguments that take single values will produce scalars, arguments that |
| 993 |
take multiple values will produce hashes, and repeatable arguments will |
| 994 |
produce arrays. |
| 995 |
|
| 996 |
If you do not like the default prefix of "ARGV_", you can specify your |
| 997 |
own, such as "opt_", like this: |
| 998 |
|
| 999 |
use Getopt::Euclid qw( :vars<opt_> ); |
| 1000 |
|
| 1001 |
The major advantage of using exported variables is that any misspelling |
| 1002 |
of argument variables in your code will be caught at compile-time by |
| 1003 |
use strict. |
| 1004 |
|
| 1005 |
Standard arguments |
| 1006 |
|
| 1007 |
Getopt::Euclid automatically provides four standard arguments to any |
| 1008 |
program that uses the module. The behaviours of these arguments are |
| 1009 |
"hard- wired" and cannot be changed, not even by defining your own |
| 1010 |
arguments of the same name. |
| 1011 |
|
| 1012 |
The standard arguments are: |
| 1013 |
|
| 1014 |
--usage usage() |
| 1015 |
|
| 1016 |
The --usage argument causes the program to print a short usage |
| 1017 |
summary and exit. The Getopt::Euclid-usage()> subroutine provides |
| 1018 |
access to the string of this message. |
| 1019 |
|
| 1020 |
--help help() |
| 1021 |
|
| 1022 |
The --help argument causes the program to take a longer usage summary |
| 1023 |
(with a full list of required and optional arguments) provided in POD |
| 1024 |
format by help(), convert it to plaintext, display it and exit. The |
| 1025 |
message is paged using IO::Pager::Page (or IO::Page) if possible. |
| 1026 |
|
| 1027 |
--man man() |
| 1028 |
|
| 1029 |
The --man argument causes the program to take the POD documentation |
| 1030 |
for the program, provided by man(), convert it to plaintext, display |
| 1031 |
it and exit. The message is paged using IO::Pager::Page (or IO::Page) |
| 1032 |
if possible. |
| 1033 |
|
| 1034 |
--podfile podfile() |
| 1035 |
|
| 1036 |
The --podfile argument is provided for authors. It causes the program |
| 1037 |
to take the POD manual from man(), write it in a .pod file with the |
| 1038 |
same base name as the program, display the name of the output file |
| 1039 |
and exit. These actions can also be executed by calling the podfile() |
| 1040 |
subroutine.This argument is not really a standard argument, but it is |
| 1041 |
useful if the program's POD is to be passed to a POD converter |
| 1042 |
because, among other things, any default value specified is |
| 1043 |
interpolated and replaced by its value in the .pod file, contrary to |
| 1044 |
in the program's .pl file. |
| 1045 |
|
| 1046 |
If you want to automate the creation of a POD file during the build |
| 1047 |
process, you can edit you Makefile.PL or Build.PL file and add these |
| 1048 |
lines: |
| 1049 |
|
| 1050 |
my @args = ($^X, '-Ilib', '/path/to/script', '--podfile'); |
| 1051 |
system(@args) == 0 or die "System call to '@args' failed:\n$?\n"; |
| 1052 |
|
| 1053 |
If you use Module::Install to bundle your script, you might be |
| 1054 |
interested in using Module::Install::PodFromEuclid to include the |
| 1055 |
--podfile step into the installation process. |
| 1056 |
|
| 1057 |
--version version() |
| 1058 |
|
| 1059 |
The --version argument causes the program to print the version number |
| 1060 |
of the program (as specified in the =head1 VERSION section of the |
| 1061 |
POD) and any copyright information (as specified in the =head1 |
| 1062 |
COPYRIGHT POD section) and then exit. The Getopt::Euclid-version()> |
| 1063 |
subroutine provides access to the string of this message. |
| 1064 |
|
| 1065 |
Minimalist keys |
| 1066 |
|
| 1067 |
By default, the keys of %ARGV will match the program's interface |
| 1068 |
exactly. That is, if your program accepts the following arguments: |
| 1069 |
|
| 1070 |
-v |
| 1071 |
--mode <modename> |
| 1072 |
<infile> |
| 1073 |
<outfile> |
| 1074 |
--auto-fudge |
| 1075 |
|
| 1076 |
Then the keys that appear in %ARGV will be: |
| 1077 |
|
| 1078 |
'-v' |
| 1079 |
'--mode' |
| 1080 |
'<infile>' |
| 1081 |
'<outfile>' |
| 1082 |
'--auto-fudge' |
| 1083 |
|
| 1084 |
In some cases, however, it may be preferable to have Getopt::Euclid set |
| 1085 |
up those hash keys without "decorations". That is, to have the keys of |
| 1086 |
%ARGV be simply: |
| 1087 |
|
| 1088 |
'v' |
| 1089 |
'mode' |
| 1090 |
'infile' |
| 1091 |
'outfile' |
| 1092 |
'auto_fudge' |
| 1093 |
|
| 1094 |
You can arrange this by loading the module with the special |
| 1095 |
':minimal_keys' specifier: |
| 1096 |
|
| 1097 |
use Getopt::Euclid qw( :minimal_keys ); |
| 1098 |
|
| 1099 |
Note that, in rare cases, using this mode may cause you to lose data |
| 1100 |
(for example, if the interface specifies both a --step and a <step> |
| 1101 |
option). The module throws an exception if this happens. |
| 1102 |
|
| 1103 |
Deferring argument parsing |
| 1104 |
|
| 1105 |
In some instances, you may want to avoid the parsing of arguments to |
| 1106 |
take place as soon as your program is executed and Getopt::Euclid is |
| 1107 |
loaded. For example, you may need to examine @ARGV before it is |
| 1108 |
processed (and emptied) by Getopt::Euclid. Or you may intend to pass |
| 1109 |
your own arguments manually only using process_args(). |
| 1110 |
|
| 1111 |
To defer the parsing of arguments, use the specifier ':defer': |
| 1112 |
|
| 1113 |
use Getopt::Euclid qw( :defer ); |
| 1114 |
# Do something... |
| 1115 |
Getopt::Euclid->process_args(\@ARGV); |
| 1116 |
|
| 1117 |
DIAGNOSTICS |
| 1118 |
|
| 1119 |
Compile-time diagnostics |
| 1120 |
|
| 1121 |
The following diagnostics are mainly caused by problems in the POD |
| 1122 |
specification of the command-line interface: |
| 1123 |
|
| 1124 |
Getopt::Euclid was unable to access POD |
| 1125 |
|
| 1126 |
Something is horribly wrong. Getopt::Euclid was unable to read your |
| 1127 |
program to extract the POD from it. Check your program's permissions, |
| 1128 |
though it is a mystery how perl was able to run the program in the |
| 1129 |
first place, if it is not readable. |
| 1130 |
|
| 1131 |
.pm file cannot define an explicit import() when using Getopt::Euclid |
| 1132 |
|
| 1133 |
You tried to define an import() subroutine in a module that was also |
| 1134 |
using Getopt::Euclid. Since the whole point of using Getopt::Euclid |
| 1135 |
in a module is to have it build an import() for you, supplying your |
| 1136 |
own import() as well defeats the purpose. |
| 1137 |
|
| 1138 |
Unknown specification: %s |
| 1139 |
|
| 1140 |
You specified something in a =for Euclid section that Getopt::Euclid |
| 1141 |
did not understand. This is often caused by typos, or by reversing a |
| 1142 |
placeholder.type or placeholder.default specification (that is, |
| 1143 |
writing type.placeholder or default.placeholder instead). |
| 1144 |
|
| 1145 |
Unknown type (%s) in specification: %s |
| 1146 |
|
| 1147 |
Unknown .type constraint: %s |
| 1148 |
|
| 1149 |
Both these errors mean that you specified a type constraint that |
| 1150 |
Getopt::Euclid did not recognize. This may have been a typo: |
| 1151 |
|
| 1152 |
=for Euclid |
| 1153 |
count.type: inetger |
| 1154 |
|
| 1155 |
or else the module simply does not know about the type you specified: |
| 1156 |
|
| 1157 |
=for Euclid |
| 1158 |
count.type: complex |
| 1159 |
|
| 1160 |
See "Standard placeholder types" for a list of types that |
| 1161 |
Getopt::Euclid does recognize. |
| 1162 |
|
| 1163 |
Invalid .type constraint: %s |
| 1164 |
|
| 1165 |
You specified a type constraint that is not valid Perl. For example: |
| 1166 |
|
| 1167 |
=for Euclid |
| 1168 |
max.type: integer not equals 0 |
| 1169 |
|
| 1170 |
instead of: |
| 1171 |
|
| 1172 |
=for Euclid |
| 1173 |
max.type: integer != 0 |
| 1174 |
|
| 1175 |
Invalid .default value: %s |
| 1176 |
|
| 1177 |
You specified a default value that is not valid Perl. For example: |
| 1178 |
|
| 1179 |
=for Euclid |
| 1180 |
curse.default: *$@!& |
| 1181 |
|
| 1182 |
instead of: |
| 1183 |
|
| 1184 |
=for Euclid |
| 1185 |
curse.default: '*$@!&' |
| 1186 |
|
| 1187 |
Invalid .opt_default value: %s |
| 1188 |
|
| 1189 |
Same as previous diagnostic, but for optional defaults. |
| 1190 |
|
| 1191 |
Invalid reference to field %s.default in argument description: %s |
| 1192 |
|
| 1193 |
You referred to a default value in the description of an argument, |
| 1194 |
but there is no such default. It may be a typo, or you may be |
| 1195 |
referring to the default value for a different argument, e.g.: |
| 1196 |
|
| 1197 |
=item -a <age> |
| 1198 |
|
| 1199 |
An optional age. Default: years.default |
| 1200 |
|
| 1201 |
=for Euclid |
| 1202 |
age.default: 21 |
| 1203 |
|
| 1204 |
instead of: |
| 1205 |
|
| 1206 |
=item -a <age> |
| 1207 |
|
| 1208 |
An optional age. Default: age.default |
| 1209 |
|
| 1210 |
=for Euclid |
| 1211 |
age.default: 21 |
| 1212 |
|
| 1213 |
Invalid reference to field %s.opt_default in argument description: %s |
| 1214 |
|
| 1215 |
Same as previous diagnostic, but for optional defaults. |
| 1216 |
|
| 1217 |
Invalid .opt_default constraint: Placeholder <%s> must be optional |
| 1218 |
|
| 1219 |
You specified an optional default but the placeholder that it affects |
| 1220 |
is not an optional placeholder. For example: |
| 1221 |
|
| 1222 |
=item -l[[en][gth]] <l> |
| 1223 |
|
| 1224 |
=for Euclid: |
| 1225 |
l.opt_default: 123 |
| 1226 |
|
| 1227 |
instead of: |
| 1228 |
|
| 1229 |
=item -l[[en][gth]] [<l>] |
| 1230 |
|
| 1231 |
=for Euclid: |
| 1232 |
l.opt_default: 123 |
| 1233 |
|
| 1234 |
Invalid .opt_default constraint: Parameter %s must have a flag |
| 1235 |
|
| 1236 |
You specified an optional default but the parameter that it affects |
| 1237 |
is unflagged. For example: |
| 1238 |
|
| 1239 |
=item <length> |
| 1240 |
|
| 1241 |
=for Euclid: |
| 1242 |
l.opt_default: 123 |
| 1243 |
|
| 1244 |
instead of: |
| 1245 |
|
| 1246 |
=item -l [<length>] |
| 1247 |
|
| 1248 |
=for Euclid: |
| 1249 |
l.opt_default: 123 |
| 1250 |
|
| 1251 |
Invalid .excludes value for variable %s: <%s> does not exist |
| 1252 |
|
| 1253 |
You specified to exclude a variable that was not seen in the POD. |
| 1254 |
Make sure that this is not a typo. |
| 1255 |
|
| 1256 |
Invalid constraint: %s (No <%s> placeholder in argument: %s) |
| 1257 |
|
| 1258 |
You attempted to define a .type constraint for a placeholder that did |
| 1259 |
not exist. Typically this is the result of the misspelling of a |
| 1260 |
placeholder name: |
| 1261 |
|
| 1262 |
=item -foo <bar> |
| 1263 |
|
| 1264 |
=for Euclid: |
| 1265 |
baz.type: integer |
| 1266 |
|
| 1267 |
or a =for Euclid: that has drifted away from its argument: |
| 1268 |
|
| 1269 |
=item -foo <bar> |
| 1270 |
|
| 1271 |
=item -verbose |
| 1272 |
|
| 1273 |
=for Euclid: |
| 1274 |
bar.type: integer |
| 1275 |
|
| 1276 |
Getopt::Euclid loaded a second time |
| 1277 |
|
| 1278 |
You tried to load the module twice in the same program. |
| 1279 |
Getopt::Euclid does not work that way. Load it only once. |
| 1280 |
|
| 1281 |
Unknown mode ('%s') |
| 1282 |
|
| 1283 |
The only argument that a use Getopt::Euclid command accepts is |
| 1284 |
':minimal_keys' (see "Minimalist keys"). You specified something else |
| 1285 |
instead (or possibly forgot to put a semicolon after use |
| 1286 |
Getopt::Euclid). |
| 1287 |
|
| 1288 |
Internal error: minimalist mode caused arguments '%s' and '%s' to clash |
| 1289 |
|
| 1290 |
Minimalist mode removes certain characters from the keys hat are |
| 1291 |
returned in %ARGV. This can mean that two command-line options (such |
| 1292 |
as --step and <step>) map to the same key (i.e. 'step'). This in turn |
| 1293 |
means that one of the two options has overwritten the other within |
| 1294 |
the %ARGV hash. The program developer should either turn off |
| 1295 |
':minimal_keys' mode within the program, or else change the name of |
| 1296 |
one of the options so that the two no longer clash. |
| 1297 |
|
| 1298 |
Run-time diagnostics |
| 1299 |
|
| 1300 |
The following diagnostics are caused by problems in parsing the |
| 1301 |
command-line |
| 1302 |
|
| 1303 |
Missing required argument(s): %s |
| 1304 |
|
| 1305 |
At least one argument specified in the REQUIRED ARGUMENTS POD section |
| 1306 |
was not present on the command-line. |
| 1307 |
|
| 1308 |
Invalid %s argument. %s must be %s but the supplied value (%s) is not. |
| 1309 |
|
| 1310 |
Getopt::Euclid recognized the argument you were trying to specify on |
| 1311 |
the command-line, but the value you gave to one of that argument's |
| 1312 |
placeholders was of the wrong type. |
| 1313 |
|
| 1314 |
Unknown argument: %s |
| 1315 |
|
| 1316 |
Getopt::Euclid did not recognize an argument you were trying to |
| 1317 |
specify on the command-line. This is often caused by command-line |
| 1318 |
typos or an incomplete interface specification. |
| 1319 |
|
| 1320 |
CONFIGURATION AND ENVIRONMENT |
| 1321 |
|
| 1322 |
Getopt::Euclid requires no configuration files or environment |
| 1323 |
variables. |
| 1324 |
|
| 1325 |
DEPENDENCIES |
| 1326 |
|
| 1327 |
* version |
| 1328 |
|
| 1329 |
* Pod::Select |
| 1330 |
|
| 1331 |
* Pod::PlainText |
| 1332 |
|
| 1333 |
* File::Basename |
| 1334 |
|
| 1335 |
* File::Spec::Functions |
| 1336 |
|
| 1337 |
* List::Util |
| 1338 |
|
| 1339 |
* Text::Balanced |
| 1340 |
|
| 1341 |
* IO::Pager::Page (recommended) |
| 1342 |
|
| 1343 |
INCOMPATIBILITIES |
| 1344 |
|
| 1345 |
Getopt::Euclid may not work properly with POD in Perl files that have |
| 1346 |
been converted into an executable with PerlApp or similar software. A |
| 1347 |
possible workaround may be to move the POD to a __DATA__ section or a |
| 1348 |
separate .pod file. |
| 1349 |
|
| 1350 |
BUGS AND LIMITATIONS |
| 1351 |
|
| 1352 |
Please report any bugs or feature requests via GitHub issues |
| 1353 |
<https://github.com/bigpresh/Getopt-Euclid/issues> |
| 1354 |
|
| 1355 |
Pull requests to fix bugs / add features welcome! |
| 1356 |
|
| 1357 |
GitHub repo <https://github.com/bigpresh/Getopt-Euclid> |
| 1358 |
|
| 1359 |
git clone [email protected]:bigpresh/Getopt-Euclid.git |
| 1360 |
|
| 1361 |
The RT queue |
| 1362 |
<https://rt.cpan.org/Public/Dist/Display.html?Name=Getopt-Euclid> still |
| 1363 |
exists but GitHub issues are preferred due to their integration with |
| 1364 |
pull requests etc. |
| 1365 |
|
| 1366 |
AUTHOR |
| 1367 |
|
| 1368 |
Damian Conway <[email protected]> |
| 1369 |
|
| 1370 |
Florent Angly <[email protected]> |
| 1371 |
|
| 1372 |
David Precious (BIGPRESH) <[email protected]> |
| 1373 |
|
| 1374 |
LICENCE AND COPYRIGHT |
| 1375 |
|
| 1376 |
Copyright (c) 2005, Damian Conway <[email protected]>. All rights |
| 1377 |
reserved. |
| 1378 |
|
| 1379 |
This module is free software; you can redistribute it and/or modify it |
| 1380 |
under the same terms as Perl itself. |
| 1381 |
|
| 1382 |
DISCLAIMER OF WARRANTY |
| 1383 |
|
| 1384 |
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY |
| 1385 |
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT |
| 1386 |
WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER |
| 1387 |
PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, |
| 1388 |
EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
| 1389 |
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE |
| 1390 |
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH |
| 1391 |
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL |
| 1392 |
NECESSARY SERVICING, REPAIR, OR CORRECTION. |
| 1393 |
|
| 1394 |
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING |
| 1395 |
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR |
| 1396 |
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE |
| 1397 |
TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR |
| 1398 |
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE |
| 1399 |
SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING |
| 1400 |
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A |
| 1401 |
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF |
| 1402 |
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH |
| 1403 |
DAMAGES. |
| 1404 |
|