Debian Codegraph @

README

raw
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