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