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