1Getopt::Euclid(3)     User Contributed Perl Documentation    Getopt::Euclid(3)
2
3
4

NAME

6       Getopt::Euclid - Executable Uniform Command-Line Interface Descriptions
7

VERSION

9       This document describes Getopt::Euclid version 0.4.5
10

SYNOPSIS

12           use Getopt::Euclid;
13
14           if ($ARGV{-i}) {
15               print "Interactive mode...\n";
16           }
17
18           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
24           __END__
25
26           =head1 NAME
27
28           yourprog - Your program here
29
30           =head1 VERSION
31
32           This documentation refers to yourprog version 1.9.4
33
34           =head1 USAGE
35
36               yourprog [options]  -s[ize]=<h>x<w>  -o[ut][file] <file>
37
38           =head1 REQUIRED ARGUMENTS
39
40           =over
41
42           =item  -s[ize]=<h>x<w>
43
44           Specify size of simulation
45
46           =for Euclid:
47               h.type:    int > 0
48               h.default: 24
49               w.type:    int >= 10
50               w.default: 80
51
52           =item  -o[ut][file] <file>
53
54           Specify output file
55
56           =for Euclid:
57               file.type:    writable
58               file.default: '-'
59
60           =back
61
62           =head1 OPTIONS
63
64           =over
65
66           =item  -i
67
68           Specify interactive simulation
69
70           =item  -l[[en][gth]] <l>
71
72           Length of simulation. The default is l.default
73
74           =for Euclid:
75               l.type:    int > 0
76               l.default: 99
77
78           =item --debug [<log_level>]
79
80           Set the log level. Default is log_level.default but if you provide --debug,
81           then it is log_level.opt_default.
82
83           =for Euclid:
84               log_level.type:        int
85               log_level.default:     0
86               log_level.opt_default: 1
87
88           =item --version
89
90           =item --usage
91
92           =item --help
93
94           =item --man
95
96           Print the usual program information
97
98           =back
99
100           Remainder of documentation starts here...
101
102           =head1 AUTHOR
103
104           Damian Conway (DCONWAY@CPAN.org)
105
106           =head1 BUGS
107
108           There are undoubtedly serious bugs lurking somewhere in this code.
109           Bug reports and other feedback are most welcome.
110
111           =head1 COPYRIGHT
112
113           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

DESCRIPTION

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

INTERFACE

167   Program interface
168       You write:
169
170           use Getopt::Euclid;
171
172       and your command-line is parsed automagically.
173
174   Module interface
175       import()
176           You write:
177
178               use Getopt::Euclid;
179
180           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
187           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
191           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
195               use Module1::Getopt (); # No argument parsing
196               use Module2::Getopt (); # No argument parsing
197               use Getopt::Euclid;     # Arguments parsed
198
199       process_args()
200           Alternatively, to parse arguments from a source different from
201           @ARGV, use the "process_args()" subroutine.
202
203               use Getopt::Euclid qw(:defer);
204               my @args = ( '-in', 'file.txt', '-out', 'results.txt' );
205               Getopt::Euclid->process_args(\@args);
206
207           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
210               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
214           This is particularly when you plan on processing POD manually.
215
216       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
221               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
227           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
231   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
238           use Getopt::Euclid;
239
240           =head1 NAME
241
242           yourprog - Your program here
243
244           =head1 REQUIRED ARGUMENTS
245
246           =over
247
248           =item  -s[ize]=<h>x<w>
249
250           Specify size of simulation
251
252           =for Euclid:
253               h.type:    int > 0
254               h.default: 24
255               w.type:    int >= 10
256               w.default: 80
257
258           =back
259
260           =head1 OPTIONS
261
262           =over
263
264           =item  -i
265
266           Specify interactive simulation
267
268           =back
269
270           =cut
271
272           # Getopt::Euclid has parsed commandline parameters and stored them in %ARGV
273
274           if ($ARGV{-i}) {
275               print "Interactive mode...\n";
276           }
277
278           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
284       When Getopt::Euclid is loaded in a non-".pm" file, it searches that
285       file for the following POD documentation:
286
287       =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
294       =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
301       =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
308               =head1 VERSION
309
310               This is version 1.2.3
311
312           or:
313
314               =head1 VERSION
315
316               This is alpha release 1.2_34
317
318           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
322               BEGIN { use version; our $VERSION = qv('1.2.3') }
323               use Getopt::Euclid;
324
325           Euclid stores the version as $Getopt::Euclid::SCRIPT_VERSION.
326
327       =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
334           The actual headings that Getopt::Euclid can recognize here are:
335
336               =head1 [STANDARD|STD|PROGRAM|SCRIPT|CLI|COMMAND[-| ]LINE] [REQUIRED|MANDATORY] [PARAM|PARAMETER|ARG|ARGUMENT][S]
337
338           Caveat: Do not put additional subheadings (=headX) inside the
339           REQUIRED ARGUMENTS section.
340
341       =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
348           Typically a program will specify both "REQUIRED ARGUMENTS" and
349           "OPTIONS", but there is no requirement that it supply both, or
350           either.
351
352           The actual headings that Getopt::Euclid recognizes here are:
353
354               =head1 [STANDARD|STD|PROGRAM|SCRIPT|CLI|COMMAND[-| ]LINE] OPTION[AL|S] [PARAM|PARAMETER|ARG|ARGUMENT][S]
355
356           Caveat: Do not put additional subheadings (=headX) inside the
357           REQUIRED ARGUMENTS section.
358
359       =head1 COPYRIGHT
360           Getopt::Euclid prints this section whenever the standard
361           "--version" option is specified on the command-line.
362
363           The actual heading that Getopt::Euclid recognizes here is any
364           heading containing any of the words "COPYRIGHT", "LICENCE", or
365           "LICENSE".
366
367   Specifying arguments
368       Each required or optional argument is specified in the POD in the
369       following format:
370
371           =item ARGUMENT_STRUCTURE
372
373           ARGUMENT_DESCRIPTION
374
375           =for Euclid:
376               ARGUMENT_OPTIONS
377               PLACEHOLDER_CONSTRAINTS
378
379       Argument structure
380
381       ·   Each argument is specified as an "=item".
382
383       ·   Any part(s) of the specification that appear in square brackets are
384           treated as optional.
385
386       ·   Any parts that appear in angle brackets are placeholders for actual
387           values that must be specified on the command-line.
388
389       ·   Any placeholder that is immediately followed by "..." may be
390           repeated as many times as desired.
391
392       ·   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
396       ·   A vertical bar indicates the start of an alternative variant of the
397           argument.
398
399       For example, the argument specification:
400
401           =item -i[n] [=] <file> | --from <file>
402
403       indicates that any of the following may appear on the command-line:
404
405           -idata.txt    -i data.txt    -i=data.txt    -i = data.txt
406
407           -indata.txt   -in data.txt   -in=data.txt   -in = data.txt
408
409           --from data.text
410
411       as well as any other combination of whitespacing.
412
413       Any of the above variations would cause all three of:
414
415           $ARGV{'-i'}
416           $ARGV{'-in'}
417           $ARGV{'--from'}
418
419       to be set to the string 'data.txt'.
420
421       You could allow the optional "=" to also be an optional colon by
422       specifying:
423
424           =item -i[n] [=|:] <file>
425
426       Optional components may also be nested, so you could write:
427
428           =item -i[n[put]] [=] <file>
429
430       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
434       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
438   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
443           =item file=<filename>
444
445           =for Euclid:
446               repeatable
447
448       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
454   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
458       For a boolean argument, you can also specify variations that are false,
459       if they appear. For example, a common idiom is:
460
461           =item --print
462
463           Print results
464
465           =item --noprint
466
467           Do not print results
468
469       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
473       As an alternative you can specify a single argument that accepts either
474       value and sets both appropriately:
475
476           =item --[no]print
477
478           [Do not] print results
479
480           =for Euclid:
481               false: --noprint
482
483       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
488       The specified false values can follow any convention you wish:
489
490           =item [+|-]print
491
492           =for Euclid:
493               false: -print
494
495       or:
496
497           =item -report[_no[t]]
498
499           =for Euclid:
500               false: -report_no[t]
501
502       et cetera.
503
504   Multiple placeholders
505       An argument can have two or more placeholders:
506
507           =item -size <h> <w>
508
509       The corresponding command line argument would then have to provide two
510       values:
511
512           -size 24 80
513
514       Multiple placeholders can optionally be separated by literal characters
515       (which must then appear on the command-line). For example:
516
517           =item -size <h>x<w>
518
519       would then require a command-line of the form:
520
521           -size 24x80
522
523       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
528   Optional placeholders
529       Placeholders can be specified as optional as well:
530
531           =item -size <h> [<w>]
532
533       This specification then allows either:
534
535           -size 24
536
537       or:
538
539           -size 24 80
540
541       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
545   Unflagged placeholders
546       If an argument consists of a single placeholder with no "flag" marking
547       it:
548
549           =item <filename>
550
551       then the corresponding entry in %ARG will have a key the same as the
552       placeholder (including the surrounding angle brackets):
553
554           if ($ARGV{'<filename>'} eq '-') {
555               $fh = \*STDIN;
556           }
557
558       The same is true for any more-complicated arguments that begin with a
559       placeholder:
560
561           =item <h> [x <w>]
562
563       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
567           my $total_size
568               = $ARGV{'<h>'}{'h'} * $ARGV{'<h>'}{'w'}
569
570       Note that, as in earlier multi-placeholder examples, the individual
571       second- level placeholder keys do not retain their angle-brackets.
572
573   Repeated placeholders
574       Any placeholder that is immediately followed by "...", like so:
575
576           =item -lib <file>...
577
578           =for Euclid:
579               file.type: readable
580
581       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
585           -lib file1.txt file2.txt
586
587       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
591           =item -n <name>
592
593           =item <offset>...
594
595           =for Euclid:
596               offset.type: 0+int
597
598       and on the command-line:
599
600           -n foobar 1 5 0 23
601
602       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
606           for my $lib (@{ $ARGV{'-lib'} }) {
607               add_lib($lib);
608           }
609
610           warn "First offset is: $ARGV{'<offsets>'}[0]";
611           my $first_offset = shift @{ $ARGV{'<offsets>'} };
612
613   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
618           =item -size <h>x<w>
619
620           =for Euclid:
621               h.type: integer
622               w.type: integer
623
624       specifies that both the "<h>" and "<w>" must be given integers.  You
625       can also specify an operator expression after the type name:
626
627           =for Euclid:
628               h.type: integer > 0
629               w.type: number <= 100
630
631       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
635       These type constraints have two alternative syntaxes:
636
637           PLACEHOLDER.type: TYPE BINARY_OPERATOR EXPRESSION
638
639       as shown above, and the more general:
640
641           PLACEHOLDER.type: TYPE [, EXPRESSION_INVOLVING(PLACEHOLDER)]
642
643       Using the second syntax, you could write the previous constraints as:
644
645           =for Euclid:
646               h.type: integer, h > 0
647               w.type: number,  w <= 100
648
649       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
653           =for Euclid:
654               h.type: integer, h > 0 && h < 100
655               w.type: number,  Math::is_prime(w) || w % 2 == 0
656
657       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
662       You can also use constraints that involve variables. You must use the
663       :defer mode and the variables must be globally accessible:
664
665           use Getopt::Euclid qw(:defer);
666           our $MIN_VAL = 100;
667           Getopt::Euclid->process_args(\@ARGV);
668
669           __END__
670
671           =head1 OPTIONS
672
673           =over
674
675           =item --magnitude <magnitude>
676
677           =for Euclid
678              magnitude.type: number, magnitude > $MIN_VAL
679
680           =back
681
682   Standard placeholder types
683       Getopt::Euclid recognizes the following standard placeholder types:
684
685           Name            Placeholder value...        Synonyms
686           ============    ====================        ================
687
688           integer         ...must be an integer       int    i
689
690           +integer        ...must be a positive       +int   +i
691                           integer
692                           (same as: integer > 0)
693
694           0+integer       ...must be a positive       0+int  0+i
695                           integer or zero
696                           (same as: integer >= 0)
697
698           number          ...must be an number        num    n
699
700           +number         ...must be a positive       +num   +n
701                           number
702                           (same as: number > 0)
703
704           0+number        ...must be a positive       0+num  0+n
705                           number or zero
706                           (same as: number >= 0)
707
708           string          ...may be any string        str    s
709                           (default type)
710
711           readable        ...must be the name         input  in
712                           of a readable file
713
714           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
720           /<regex>/       ...must be a string
721                           matching the specified
722                           pattern
723
724       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
730           use Regexp::Common qw /zip/;
731           use Getopt::Euclid;
732
733           ...
734
735           =item -p <postcode>
736
737           Enter your postcode here
738
739           =for Euclid:
740               postcode.type:  /$RE{zip}{France}/
741               postcode.type.error: <postcode> must be a valid ZIP code
742
743   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
749           =for Euclid:
750               h.type:        integer, h > 0 && h < 100
751               h.type.error:  <h> must be between 0 and 100 (not h)
752
753               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
756       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
760   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
766           =item -size <h>[x<w>]
767
768           Set the size of the simulation
769
770           =for Euclid:
771               h.default: 24
772               w.default: 80
773
774       This ensures that if no "<w>" value is supplied:
775
776           -size 20
777
778       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
782       However, Getopt::Euclid also supports a second type of default,
783       optional defaults, that apply only to flagged, optional placeholders.
784
785       For example:
786
787           =item --debug [<log_level>]
788
789           Set the log level
790
791           =for Euclid:
792               log_level.type:        int
793               log_level.default:     0
794               log_level.opt_default: 1
795
796       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
800           --debug
801
802       then $ARGV{'--debug'} is set to 1, the optional default.
803
804       The default value can be any valid Perl compile-time expression:
805
806           =item -pi=<pi value>
807
808           =for Euclid:
809               pi value.default: atan2(0,-1)
810
811       You can refer to an argument default or optional default value in its
812       POD entry as shown below:
813
814           =item -size <h>[x<w>]
815
816           Set the size of the simulation [default: h.default x w.default]
817
818           =for Euclid:
819               h.default: 24
820               w.default: 80
821
822           =item --debug <level>
823
824           Set the debug level. The default is level.default if you supply --debug but
825           omit a <level> value.
826
827           =for Euclid:
828               level.opt_default: 3
829
830       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
834           use Getopt::Euclid qw(:defer);
835           Getopt::Euclid->process_args(\@ARGV);
836
837           __END__
838
839           =head1 OPTIONS
840
841           =over
842
843           =item --home <home>
844
845           Your project home. When omitted, this defaults to the location stored in
846           the HOME environment variable.
847
848           =for Euclid
849              home.default: $ENV{'HOME'}
850
851           =back
852
853   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
858           =item -height <h>
859
860           Set the desired height
861
862           =item -width <w>
863
864           Set the desired width
865
866           =item -volume <v>
867
868           Set the desired volume
869
870           =for Euclid:
871               v.excludes: h, w
872               v.excludes.error: Either set the volume or the height and weight
873
874       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
878       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
882   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
887           =item -v
888
889           =item -x
890
891           =item +1
892
893           =item =z
894
895       Cuddling means that two or more such arguments can be concatenated
896       after a single common non-alphanumeric. For example:
897
898           -vx
899
900       Note, however, that only flags with the same leading non-alphanumeric
901       can be cuddled together. Getopt::Euclid would not allow:
902
903           -vxz
904
905       This is because cuddling is recognized by progressively removing the
906       second character of the cuddle. In other words:
907
908           -vxz
909
910       becomes:
911
912           -v -xz
913
914       which becomes:
915
916           -v -x z
917
918       which will fail, unless a "z" argument has also been specified.
919
920       On the other hand, if the argument:
921
922           =item -e <cmd>
923
924       had been specified, the module would accept:
925
926           -vxe'print time'
927
928       as a cuddled version of:
929
930           -v -x -e'print time'
931
932   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
937           use Getopt::Euclid qw( :vars );
938
939       That is, if your program accepts the following arguments:
940
941           -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
950       Then these variables will be exported
951
952           $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
961       For options that have multiple variants, only the longest variant is
962       exported.
963
964       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
970       If you do not like the default prefix of "ARGV_", you can specify your
971       own, such as "opt_", like this:
972
973           use Getopt::Euclid qw( :vars<opt_> );
974
975       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
979   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
985       The standard arguments are:
986
987       --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
992       --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
999       --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
1005       --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
1016           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
1020              my @args = ($^X, '-Ilib', '/path/to/script', '--podfile');
1021              system(@args) == 0 or die "System call to '@args' failed:\n$?\n";
1022
1023           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
1027       --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
1035   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
1039           -v
1040           --mode <modename>
1041           <infile>
1042           <outfile>
1043           --auto-fudge
1044
1045       Then the keys that appear in %ARGV will be:
1046
1047           '-v'
1048           '--mode'
1049           '<infile>'
1050           '<outfile>'
1051           '--auto-fudge'
1052
1053       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
1057           'v'
1058           'mode'
1059           'infile'
1060           'outfile'
1061           'auto_fudge'
1062
1063       You can arrange this by loading the module with the special
1064       ':minimal_keys' specifier:
1065
1066           use Getopt::Euclid qw( :minimal_keys );
1067
1068       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
1072   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
1079       To defer the parsing of arguments, use the specifier ':defer':
1080
1081           use Getopt::Euclid qw( :defer );
1082           # Do something...
1083           Getopt::Euclid->process_args(\@ARGV);
1084

DIAGNOSTICS

1086   Compile-time diagnostics
1087       The following diagnostics are mainly caused by problems in the POD
1088       specification of the command-line interface:
1089
1090       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
1096       .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
1102       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
1109       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
1114               =for Euclid
1115                   count.type: inetger
1116
1117           or else the module simply does not know about the type you
1118           specified:
1119
1120               =for Euclid
1121                   count.type: complex
1122
1123           See "Standard placeholder types" for a list of types that
1124           Getopt::Euclid does recognize.
1125
1126       Invalid .type constraint: %s
1127           You specified a type constraint that is not valid Perl. For
1128           example:
1129
1130               =for Euclid
1131                   max.type: integer not equals 0
1132
1133           instead of:
1134
1135               =for Euclid
1136                   max.type: integer != 0
1137
1138       Invalid .default value: %s
1139           You specified a default value that is not valid Perl. For example:
1140
1141               =for Euclid
1142                   curse.default: *$@!&
1143
1144           instead of:
1145
1146               =for Euclid
1147                   curse.default: '*$@!&'
1148
1149       Invalid .opt_default value: %s
1150           Same as previous diagnostic, but for optional defaults.
1151
1152       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
1157               =item -a <age>
1158
1159               An optional age. Default: years.default
1160
1161               =for Euclid
1162                   age.default: 21
1163
1164           instead of:
1165
1166               =item -a <age>
1167
1168               An optional age. Default: age.default
1169
1170               =for Euclid
1171                   age.default: 21
1172
1173       Invalid reference to field %s.opt_default in argument description: %s
1174           Same as previous diagnostic, but for optional defaults.
1175
1176       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
1180               =item  -l[[en][gth]] <l>
1181
1182               =for Euclid:
1183                   l.opt_default: 123
1184
1185           instead of:
1186
1187               =item  -l[[en][gth]] [<l>]
1188
1189               =for Euclid:
1190                   l.opt_default: 123
1191
1192       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
1196               =item  <length>
1197
1198               =for Euclid:
1199                   l.opt_default: 123
1200
1201           instead of:
1202
1203               =item  -l [<length>]
1204
1205               =for Euclid:
1206                   l.opt_default: 123
1207
1208       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
1212       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
1217               =item -foo <bar>
1218
1219               =for Euclid:
1220                   baz.type: integer
1221
1222           or a "=for Euclid:" that has drifted away from its argument:
1223
1224               =item -foo <bar>
1225
1226               =item -verbose
1227
1228               =for Euclid:
1229                   bar.type: integer
1230
1231       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
1235       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
1241       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
1250   Run-time diagnostics
1251       The following diagnostics are caused by problems in parsing the
1252       command-line
1253
1254       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
1258       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
1263       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

CONFIGURATION AND ENVIRONMENT

1269       Getopt::Euclid requires no configuration files or environment
1270       variables.
1271

DEPENDENCIES

1273       ·   version
1274
1275       ·   Pod::Select
1276
1277       ·   Pod::PlainText
1278
1279       ·   File::Basename
1280
1281       ·   File::Spec::Functions
1282
1283       ·   List::Util
1284
1285       ·   Text::Balanced
1286
1287       ·   IO::Pager::Page (recommended)
1288

INCOMPATIBILITIES

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

BUGS AND LIMITATIONS

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
1300       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

AUTHOR

1310       Damian Conway  "<DCONWAY@cpan.org>"
1311
1312       Florent Angly "<florent.angly@gmail.com>"
1313
1315       Copyright (c) 2005, Damian Conway "<DCONWAY@cpan.org>". All rights
1316       reserved.
1317
1318       This module is free software; you can redistribute it and/or modify it
1319       under the same terms as Perl itself.
1320

DISCLAIMER OF WARRANTY

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
1332       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.
1342
1343
1344
1345perl v5.32.0                      2020-07-28                 Getopt::Euclid(3)
Impressum