blib/lib/Getopt/Mixed/Help.pm

filter: Statementstmt 99.1% 221 / 223 Branchbran 96.5% 141 / 146 Conditioncond 91.6% 22 / 24 MC/DCmcdc 78.5% 11 / 14 Subroutinesub 100% 18 / 18 Podpod n/a totaltotal 97.1% 413 / 425 CC 91 SCAR 43.4
CC
91
Cov
98%
import
91.1
BEGIN
1.0
BEGIN
1.0
CRAP 76.9
↑ Summary
1 package Getopt::Mixed::Help;
2  
3 # Author, Copyright and License: see end of file
4  
5 =head1 NAME
6  
7 Getopt::Mixed::Help - combine L<C<Getopt::Mixed>> with usage and help
8  
9 =head1 SYNOPSIS
10  
11 use constant DEFAULT_LOOPS => 10;
12 use Getopt::Mixed::Help
13 ('<filenames>...' => 'filenames to be processed',
14 'ENV' => 'SCRIPT_OPT_',
15 'ENV_' => 'SCRIPT_OPT_',
16 'd>debug:i number' => 'turn on debugging information (*)',
17 'e>execute' => 'do it without asking for confirmation',
18 'f>force' => 'override all safety checks',
19 'i>interactive' => 'asks for confirmation before doing it',
20 'l>loops count' => 'number of loops to do',
21 'n>no-execute' => 'just print what would be done without doing it',
22 'q>quiet' => 'suppress all information',
23 's>summary' => 'print summary information on exit',
24 'v>verbose:i number' => 'turn on verbose information (*)',
25 '(*)' => '(*) You may add a positive integer for a higher level.'
26 );
27 if ($opt_...
28  
29 export SCRIPT_OPT_INTERACTIVE=1
30 test_script -d -v 2 --summary some_file.ext other_file.ext
31  
32 =head1 ABSTRACT
33  
34 Getopt::Mixed::Help is a simplified interface to Getopt::Long adding
35 usage (help) functionality. It automatically adds the options -?, -h
36 and --help (the last two configurable) to print the usage text. It
37 allows to get option values from the environment (if the operating
38 system it runs on supports environment variables). It can
39 automatically get default values from Perl constants. It can also add
40 different flavours of support for multiple options. Finally it
41 supports debugging output of the options used.
42  
43 So like Getopt::Long it is (just another) module that parses options
44 passed on the command line into variables while removing them from
45 @ARGV. Only normal parameters remain in @ARGV.
46  
47 =head1 DESCRIPTION
48  
49 The module uses a direct import mechanism called with a hash as
50 parameter. The structure of the hash is as follows:
51  
52 The key is a combined (SHORT > LONG [ARGUMENT SPECIFIER [VALUE
53 IDENTIFIER]]) option description for the outdated module
54 L<C<Getopt::Mixed>>, except for the VALUE IDENTIFIER which is simply
55 included into the help text. The value following the key is simply
56 the help text for this option. The examples should make everything
57 clear even if you are not familiar with L<C<Getopt::Mixed>>.
58  
59 If the second character of the first key is not C<E<gt>>, the first
60 key is taken as descriptive identifiers for additional parameters and
61 the help for them.
62  
63 Any key starting with C<(> and ending with C<)> will be interpreted as
64 a footnote (additional help text) to the real options. They should be
65 used at the end of the list only.
66  
67 A key equal to C<ENV> is used to get default values for the remaining
68 options from the environment. For any option not initialised on the
69 command line an environment variable with the prefix of the value
70 following C<ENV> and a rest of the name identical to the uppercase
71 long option name (e.g. C<SCRIPT_OPT_DEBUG>) will be checked. If this
72 environment variable exists, it will be used to set the option. Note
73 that in the name of the rest of the environment variable uppercase is
74 used and hyphens are relaced with underlines.
75  
76 A key equal to C<ENV_> is used in the same way as the key C<ENV>. In
77 addition it allows for a special environment variable with the prefix
78 of the value following C<ENV> followed by a single underline (C<_>) as
79 combined initialiser (for more than one option, e.g. C<export
80 SCRIPT_OPT__='debug verbose=2'>). Note that no whitespaces are
81 allowed in the values of the options initialised this way as the
82 string in the environment variable is parsed in a simple way.
83  
84 The module defines the variable $optUsage containing the complete help
85 text.
86  
87 If an option C<debug> exists and is choosen on the command line, this
88 module will print all option values and all remaining parameters to
89 standard error. The name of this option may be changed, see
90 C<"changing the debug option"> below in the L</"CHANGING DEFAULT
91 BEHAVIOUR"> section.
92  
93 Perl constants with the prefix C<DEBUG_> and a name matching the
94 option are used as default values for the options, see below for
95 details.
96  
97 =head1 EXPORT
98  
99 The module automatically exports all option variables (C<$opt_>) as
100 well as the usage text (C<$optUsage>).
101  
102 =head1 OPTION DETAILS
103  
104 =head2 parameter help ('parameter text' => 'parameter description')
105  
106 If a script takes normal parameters (as oposed to options starting
107 with a hyphen), their description for the help text must be the first
108 parameter of the hash passed on import. It is also necessary that the
109 second character of the key is not C<E<gt>>. An example, if a script
110 using this module accepts one or more filenames as parameters, you
111 might want to use the following import parameter:
112  
113 '<filenames>...' => 'filenames to be processed'
114  
115 This would produce the following help text:
116  
117 usage: script.pl [<options>] [--] <filenames>...
118  
119 filenames to be processed
120  
121 =head2 combined options ('o>long-option ...' => 'option description')
122  
123 Combined options are options that allow to use both a long and a short
124 option to set the same option variable for a script (see
125 L<C<Getopt::Mixed>> for details). In principle Getopt::Mixed::Help
126 uses a syntax similar to L<C<Getopt::Mixed>> for the key of the import
127 parameter, but it changes their sequence within the alias. The
128 minimal key for the import parameter just uses the character of the
129 short option followed by C<E<gt>> followed by the long option (without
130 C<-->). It would define a boolean option variable, for example the
131 import parameter
132  
133 'o>long-option' => 'some long option'
134  
135 defines a boolean option with the identifier C<$opt_long_option> that
136 can be set with the short option C<-o> and the long option
137 C<--long-option> (which may be abbreviated as described in
138 L<C<Getopt::Mixed>>). Its help text would look as follows:
139  
140 -o|--long-option
141 some long option
142  
143 For string, integer or real number options the key of the import
144 parameter must be extended with an argument specifier. There are 6
145 possible argument specifiers:
146  
147 =s for a mandatory string argument
148 =i for a mandatory integer argument
149 =f for a mandatory real number argument
150 :s for an optional string argument
151 :i for an optional integer argument
152 :f for an optional real number argument
153  
154 The argument specifieres may be followed by a blank and the value
155 identifier, a short text describing the argument. This text will
156 become part of the help text. If no describing text is specified,
157 C<string> will be used for strings, C<integer> for integers and
158 C<float> for real numbers. Consider the import parameters of the
159 following example:
160  
161 'd>directory=s directory' => 'name of the directory',
162 'o>offset:f' => 'offset in the file in % (default 0.0)'
163  
164 This defines a string option with a mandatory value and the
165 indentifier C<$opt_directory> as well as a real number option with an
166 optional value and the identifier C<$opt_offset>. The help text for
167 these options would be:
168  
169 -d|--directory <directory>
170 name of the directory
171 -o|--offset [<float>]
172 offset in the file in % (default 0.0)
173  
174 For an optional value the default value that is used if no value is
175 specified depends on its type. For strings it is an empty string
176 (C<''>), for integers it is 1 and for real numbers it is 0.0.
177  
178 =head2 long options ('long-option ...' => 'option description')
179  
180 If you run out of characters for short options you end up with the
181 need for options that only exist as a long option. They are just
182 declared like the combined options without the leading short option
183 character and the C<E<gt>>, e.g.
184  
185 'long-optional-string:s' => 'optional string'
186  
187 The only pitfall with long options comes when the first option you
188 declare is not a combined option and you don't have normal parameters
189 as Getopt::Mixed::Help then would treat your long option declaration
190 as a L</"parameter help">. To avoid this just put a C<-E<gt>->
191 declaration before it (see C<separator> in L</"CHANGING DEFAULT
192 BEHAVIOUR"> below).
193  
194 =head2 getting options from environment variables ('ENV' => 'SCRIPT_OPT_')
195  
196 There are two special import parameter keys that allow your script to
197 be able to read options from environment variables (if your operating
198 system supports it).
199  
200 The first key is the string C<'ENV'>. If it is defined, each option
201 variable cat get its default value from an environment variable if
202 that environment variable is set. The name of that environment
203 variable is composed of the value of the C<'ENV'> import parameter and
204 the name of the long option where all characters are turned into
205 uppercase and all hyphens are replaces with underscores, e.g. for the
206 import parameters
207  
208 'ENV' => 'MYSEARCH',
209 'd>start-dir=s directory' => 'name of the first directory'
210  
211 the option variable C<$opt_start_dir> will be filled with the value of
212 the environment variable MYSEARCHSTART_DIR if that is set and the
213 option is not set on the command line.
214  
215 The second environment import parameter key is the string C<'ENV_'>.
216 It works similar to the other one except that it defines an
217 environment variable that can be used to set a whole default command
218 line at once (well, only its options and not if their values would
219 contain blanks). For this key the name of that environment variable
220 is composed of the value of the C<'ENV_'> import parameter followed by
221 an underscore (C<_>). To put several long options into the
222 environment variable so created, just concatenate them together with
223 blanks and without their leading C<-->. If for example above's
224 directory and offset options are preceeded by
225  
226 'ENV_' => 'MYSEARCH'
227  
228 you could set the environment variable MYSEARCH_ from a shell like
229 this:
230  
231 export MYSEARCH_='offset=12.5 directory=/tmp/somewhere'
232  
233 But remember, this works for simple things only, for more complicated
234 defaults from the environment you must create one variable for each
235 option as described above. If you do both the value of the specific
236 environment variable overwrites that of the combined one.
237  
238 And a warnings for this features, if you use both environment import
239 parameters (which is quite reasonable) you must use the same value for
240 both of them, otherwise only the last one specified works.
241  
242 =head2 footnotes
243  
244 Sometimes you'll like to describe an option in more details, want to
245 give additional information concerning more than one option or just
246 like to add some more text at the end of a generated help. To do
247 that, Getopt::Mixed::Help allows you to add just about any text you
248 like to your import parameter list using keys that begin and end in
249 parentheses. The key is not used any further, so you can use any text
250 as long as you put it into parentheses. The text of the description
251 is put into the help text as it is, but preceeded and followed by a
252 newline.
253  
254 Normally all footnotes are put at the end of the option list but
255 theoretically you could also put one in-between to split the option
256 list into two (or more) parts - the footnote is put into the help text
257 just where it occurs.
258  
259 =head1 DEFINING DEFAULT VALUES USING PERL CONSTANTS
260  
261 If you define a Perl constant (C<use constant>) beginning with
262 C<DEFAULT_> and ending with the name of the long option where all
263 characters are turned into uppercase and all hyphens are replaces with
264 underscores, e.g. for the import parameters
265  
266 'd>start-dir=s directory' => 'name of the first directory'
267  
268 a
269  
270 use constant DEFAULT_START_DIR => '.';
271  
272 the variable C<$opt_start_dir> will be initialised, if no other value
273 is specified by environment variable or on the command line. (Options
274 on the command line overrule the values specified in environment
275 variables, which themselves overrule the default values of the Perl
276 constants.)
277  
278 In addition the default value will also be added to the help text for
279 that option. The additional text will be put into parentheses and
280 starts with the words C<defaults to>. See below how to change that.
281  
282 Note that all Perl constants with default values must be defined
283 before the C<use> command including this module, otherwise they have
284 no effect. Also note that they must belong to the C<main::>
285 namespace. And finally note that only simple values and array
286 references are supported yet.
287  
288 =head1 CHANGING DEFAULT BEHAVIOUR
289  
290 Some declarations looking like silly declarations (they all start with
291 a hyphen as the short option character) can change the behaviour of
292 the module.
293  
294 =head2 separator ('->-' => '')
295  
296 The separator is only needed if you don't have normal parameters and
297 your first option only comes in a long form, e.g. like in
298  
299 '->-' => '', 'long-optional-string:s' => 'optional string'
300  
301 which produces the following help text:
302  
303 usage: script.pl [<options>] [--]
304  
305 options: --long-optional-string [<string>]
306 optional string
307  
308 Instead of the separator any of the other behavior changing
309 declarations will have the same effect.
310  
311 =head2 changing the help option ('->help' => 'H>Hilfe')
312  
313 With C<-E<gt>help> you can replace the default names C<h> (as short
314 option) and C<help> (as long option) of the help options. The value
315 part of this declaration must contain the new short option character
316 followed by C<E<gt>> followed by the long option (without C<-->) as in
317 a normal boolean option declaration.
318  
319 Note that C<-?> will always remain as help option as well and can not
320 be renamed or removed!
321  
322 =head2 changing the debug option ('->debug' => 'verbose')
323  
324 With C<-E<gt>debug> you can replace the default (long option) name
325 C<debug> of the debug option. (Remember that the module prints all
326 options on STDERR if a long option called C<debug> is declared and
327 set.) The value part of this declaration is just the new long option
328 name (without C<-->).
329  
330 Note that the debugging option still has to be declared as normal
331 option as well.
332  
333 =head2 changing the usage text ('->usage' => 'use as')
334  
335 With this modifying option you can replace the text C<usage> at the
336 beginning of the help text with the string specified in the value part
337 of this declaration.
338  
339 Note that the variable used for the help text is still called
340 C<$optUsage>.
341  
342 =head2 changing the options text ('->options' => 'switches')
343  
344 With this modifying option you can replace the text C<options> in the
345 help text with the string specified in the value part of this
346 declaration. Note that the string occurs two times.
347  
348 Due to the way the help text is constructed this option has to be
349 specified before the first normal option of the import (use)
350 statement!
351  
352 =head2 changing the default value text ('->default' => ' (init. %s)')
353  
354 With this modifying option you can replace the text appended for
355 options with default values set by Perl constant (C< (defaults to
356 %s)>) in the help text with the string specified in the value part of
357 this declaration. Note that the string must contain a C<%s> as it is
358 put together with C<sprintf> (see L<perldoc/sprintf>). You may also
359 set this modifying option to C<undef> to disable the additional help
360 text.
361  
362 Due to the way the help text is constructed this option has to be
363 specified before the first normal option of the import (use)
364 statement!
365  
366 =head2 enabling multiple support ('->multiple' => ...)
367  
368 This neat modifying option gives you support to process multiple
369 occurances of the same option. It comes in two flavours, depending on
370 the value part of the declaration:
371  
372 =head3 multiple support using concatenation ('->multiple' => 'text')
373  
374 With this flavour multiple occurances of the same option are (sort of)
375 concatenated. The kind of C<concatenation> depends on the type of the
376 option: string options are concatenated (joined) with the given text
377 put between each occurance, integers and floats are added together and
378 boolean are just counted.
379  
380 If you take the following example declaration of import parameters
381  
382 '->multiple' => ', ',
383 'd>directory=s directory' => 'name of the directory',
384 'o>offset:f' => 'offset in the file in % (default 0.0)'
385  
386 and call the script using them with a command line like:
387  
388 -d a --offset -o=0.25 -d b -d=c -o=0.33
389  
390 Now your option variable C<$opt_directory> will be set to C<a, b, c>
391 and your option variable C<$opt_offset> will be set to the value 0.58
392 (0.0 + 0.25 + 0.33).
393  
394 Note that an empty string is a valid input for this flavour of
395 multiple occurances, the strings then are just concatenated without
396 anything between them.
397  
398 =head3 multiple support using arrays ('->multiple' => undef)
399  
400 With this flavour (yes, this one uses an explicit C<undef> value to
401 distinguish it from the last one) each option passed more than once
402 will not be returned in a normal scalar variable but in a reference to
403 an array.
404  
405 For example take the declaration from the C<concatenation> flavour and
406 just replace the value part C<', '> with C<undef>. If you use this
407 with the following options on your command line:
408  
409 -d a -o 0.25 --directory=b
410  
411 This time your option variable C<$opt_offset> will be a scalar with
412 the value 0.25 but the option variable C<$opt_directory> will be a
413 reference to an array containing the values C<a> and C<b> (in that
414 sequence).
415  
416 It is up to you to handle the different variable types adequately!
417 (But it is guaranteed that a C<ref> will either return C<''> or
418 C<'ARRAY'>.)
419  
420 =head2 multiple per option support using arrays
421  
422 A third method to support multiple options, again as arrays but only
423 for selected options works by slightly modifying their import
424 parameter key using a double C<E<gt>E<gt>>. So suppose you have the
425 following import parameters (without any C<-E<gt>multiple> option at
426 all):
427  
428 'd>>directory=s directory' => 'name of the directory',
429 'o>offset:f' => 'offset in the file in % (default 0.0)'
430  
431 If you now call your script with
432  
433 -d a -o0.25 --directory=b -o0.5
434  
435 you'll end up with the value 0.5 in C<$opt_offset> and a reference to
436 an array with C<a> and C<b> in C<$opt_directory>. So this gives you
437 an easy way to enable multiple option support just for selected
438 options easing the overhead for analysing all of them to be possible
439 array references.
440  
441 For long options (without a character for a short option) you just
442 start them with the double C<E<gt>E<gt>>.
443  
444 Multiple options as string on a per-option-base is not supported, but
445 you can get that with short statement like the following:
446  
447 $opt_directory = join(' ', @$opt_directory)
448 if ref($opt_directory) eq 'ARRAY';
449  
450 =head1 FUNCTIONS
451  
452 =cut
453  
454 #########################################################################
455  
456 14 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
457 14 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
458 14 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
459  
460 14 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
461 14 ▶use File::Basename;
Subroutine BEGIN: called CC=1 SCAR=0.0
462 14 ▶use Getopt::Long qw(:config posix_default no_ignore_case bundling_override
Subroutine BEGIN: called CC=1 SCAR=0.0
463 14 );
464 # debug);
465  
466 #******************************************************************
467  
468 14 ▶use vars '$optUsage';
Subroutine BEGIN: called CC=1 SCAR=0.0
469  
470 14 our $VERSION = '0.26';
471  
472 # default strings (they are the ones used for indent!):
473 14 ▶use constant DEFAULT_USAGE => 'usage';
Subroutine BEGIN: called CC=1 SCAR=0.0
474 14 ▶use constant DEFAULT_OPTIONS => 'options';
Subroutine BEGIN: called CC=1 SCAR=0.0
475 14 ▶use constant DEFAULT_DEFAULT => ' (defaults to %s)';
Subroutine BEGIN: called CC=1 SCAR=0.0
476  
477 #########################################################################
478  
479 =head2 B<import> - main and only function
480  
481 see above in the main documentation how to use it
482  
483 One confession about the internals, this function doesn't use a real
484 hash; it just uses the same syntax as it really expects an array of
485 pairs (as most of you might have guessed already ;-).
486  
487 =cut
488  
489 # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
490 sub import
491 117 ▶{
Subroutine import: called CC=91 SCAR=45.1
492 117 local $_;
493 117 my $this = shift;
494 117 ▶ croak 'bad usage of ', __PACKAGE__ unless $this eq __PACKAGE__;
Branch: 1 branch
BranchTrueFalseTotal
unless $this eq __PACKAGE__ 1 116 117
495 116 ▶ croak 'no parameter passed to ', __PACKAGE__ unless 0 < @_;
Branch: 1 branch
BranchTrueFalseTotal
unless 0 < @_ 2 114 116
496 114 ▶ croak 'unbalanced parameter list passed to ', __PACKAGE__
Branch: 1 branch
BranchTrueFalseTotal
unless @_ % 2 == 0 2 112 114
497 unless @_ % 2 == 0;
498 112 my %env = %ENV;
499  
500 112 my $usage_text = DEFAULT_USAGE;
501 112 my $options_text = DEFAULT_OPTIONS;
502 112 my $indent_opt1 = $options_text.': ';
503 112 my $indent_opt2 = ' ' x (length($options_text) + 3);
504 112 my $indent_help = ' ' x (length($options_text) + 7);
505 112 my $default_template = DEFAULT_DEFAULT;
506  
507 112 $optUsage = '';
508 # check/support commandline parameters that are NOT options:
509 112 my $has_only_options = 1;
510 112 ▶ if ($_[0] =~ m/^.[^>].*$/ and $_[0] ne 'ENV' and $_[0] ne 'ENV_')
Branch: 1 branch
BranchTrueFalseTotal
if ($_[0] =~ /^.[^>].*$/ and $_[0] ne "ENV" and $_[0] ne "ENV_") 33 79 112
Condition100%6/6
$_[0] =~ /^.[^>].*$/ and $_[0] ne "ENV" and $_[0] ne "ENV_"
!ll&&!rl&&r
78133
$_[0] =~ /^.[^>].*$/ and $_[0] ne "ENV"
!ll&&!rl&&r
77134
MC/DC100%3/3
$_[0] =~ /^.[^>].*$/ and $_[0] ne "ENV" and $_[0] ne "ENV_"
$_[0] =~ /^.[^>].*$/ $_[0] ne "ENV" $_[0] ne "ENV_"
Truth table100%4/4
A and B and C
A= $_[0] =~ /^.[^>].*$/B= $_[0] ne "ENV"C= $_[0] ne "ENV_"
ABCresult
0XX0
10X0
1100
1111
511 {
512 33 $optUsage .= ' '.(shift)."\n\n".(shift);
513 33 $has_only_options = 0;
514 }
515 112 $optUsage .= "\n\n";
516  
517 112 my $help_long = 'help';
518 112 my $help_opt_name = 'opt_help';
519 112 my $help_options = 'help|h|?+';
520 112 my $debug_opt_name = 'opt_debug';
521  
522 112 my @options = ();
523 112 my @option_vars = ();
524 112 my %default_value = ();
525 112 my %option_type = ();
526 112 my %optional_integers = ();
527 112 my %optional_floats = ();
528 112 my $max_length = 0;
529 112 my $env_prefix = undef;
530 112 my $use_multiple = 0;
531 112 my $multiple = undef;
532 112 my %multiple_options = ();
533 112 my $package = (caller)[0];
534  
535 # preparation loop (module parameters):
536 112 ▶ while (@_ > 0)
Branch: 1 branch
BranchTrueFalseTotal
if (@_ > 0) 462 104 566
537 {
538 462 my $option = shift;
539 462 ▶ if ($option =~
Branch: 11 branches
BranchTrueFalseTotal
if ($option =~ /^(?:(\w)?>(>)?)?([-a-z0-9]{2,})(?:([:=][isf])\s*(.*))?$/) { } 339 123 462
elsif ($option =~ /^\(.+\)$/) { } 32 91 123
elsif ($option eq '->-') { } 4 87 91
elsif ($option eq '->debug') { } 2 85 87
elsif ($option eq '->default') { } 2 83 85
elsif ($option eq '->help') { } 3 80 83
elsif ($option eq '->multiple') { } 10 70 80
elsif ($option eq '->options') { } 1 69 70
elsif ($option eq '->usage') { } 1 68 69
elsif ($option eq 'ENV') { } 33 35 68
elsif ($option eq 'ENV_') { } 33 2 35
540 m/^(?:(\w)?>(>)?)?([-a-z0-9]{2,})(?:([:=][isf])\s*(.*))?$/)
541 {
542 339 my ($short_option, $is_multiple, $long_option, $specifier,
543 $opt_valtext) = ($1, $2, $3, $4, $5);
544 339 my $var = 'opt_'.$long_option;
545 339 $var =~ s/\W/_/g;
546 339 my $default_text = '';
547 {
548 339 my $default_constant = 'DEFAULT_'.uc($long_option);
549 339 $default_constant =~ s/\W/_/g;
550 14 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
551 14 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
552 339 my $default_cref = *{$package.'::'.$default_constant}{CODE};
553 339 ▶ if ( ref($default_cref) eq 'CODE')
Branch: 1 branch
BranchTrueFalseTotal
if (ref $default_cref eq "CODE") 6 333 339
554 {
555 6 ▶ if (ref(&$default_cref) eq '')
Branch: 2 branches
BranchTrueFalseTotal
if (ref &$default_cref eq '') { } 3 3 6
elsif (ref &$default_cref eq 'ARRAY') { } 2 1 3
556 {
557 3 $default_text =
558 sprintf($default_template, &$default_cref);
559 }
560 elsif (ref(&$default_cref) eq 'ARRAY')
561 {
562 $default_text =
563 sprintf($default_template,
564 2 join(', ', @{&$default_cref}));
565 }
566 else
567 {
568 1 croak(ref(&$default_cref), ' constants as ',
569 'default values are not yet supported in ',
570 __PACKAGE__);
571 }
572 5 $default_value{$var} = &$default_cref;
573 }
574 }
575 338 ▶ $specifier = '' unless defined $specifier;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $specifier 48 290 338
576 338 ▶ if ($opt_valtext and $specifier =~ m/^=/)
Branch: 5 branches
BranchTrueFalseTotal
if ($opt_valtext and $specifier =~ /^=/) { } 6 332 338
elsif ($opt_valtext and $specifier =~ /^:/) { } 3 329 332
elsif ($specifier =~ /^=/) { } 128 201 329
elsif ($specifier =~ /^:/) { } 153 48 201
elsif (defined $opt_valtext) { } 0 48 48
Condition100%3/3
$opt_valtext and $specifier =~ /^=/
!ll&&!rl&&r
32936
MC/DC100%2/2
$opt_valtext and $specifier =~ /^=/
$opt_valtext $specifier =~ /^=/
Truth table100%3/3
A and B
A= $opt_valtextB= $specifier =~ /^=/
ABresult
0X0
100
111
577 {
578 6 ▶ if ($opt_valtext =~ m/^{.*}$/)
Branch: 1 branch
BranchTrueFalseTotal
if ($opt_valtext =~ /^{.*}$/) { } 1 5 6
579 {
580 1 $opt_valtext = ' '.$opt_valtext;
581 }
582 else
583 {
584 5 $opt_valtext = ' <'.$opt_valtext.'>';
585 }
586 }
587 ▶ elsif ($opt_valtext and $specifier =~ m/^:/)
Condition66%2/3
$opt_valtext and $specifier =~ /^:/
!ll&&!rl&&r
32903
MC/DC50%1/2
$opt_valtext and $specifier =~ /^:/
$opt_valtext $specifier =~ /^:/
Truth table66%2/3
A and B
A= $opt_valtextB= $specifier =~ /^:/
ABresult
0X0
100
111
588 {
589 3 $opt_valtext = ' [<'.$opt_valtext.'>]';
590 }
591 elsif ($specifier =~ m/^=/)
592 {
593 128 ▶ $opt_valtext = ($specifier =~ m/i$/ ? ' <integer>' :
Branch: 3 branches
BranchTrueFalseTotal
$specifier =~ /i$/ ? : 46 82 128
$specifier =~ /s$/ ? : 42 40 82
$specifier =~ /f$/ ? : 40 0 40
594 $specifier =~ m/s$/ ? ' <string>' :
595 $specifier =~ m/f$/ ? ' <float>' : ' <???>');
596 }
597 elsif ($specifier =~ m/^:/)
598 {
599 153 ▶ $opt_valtext = ($specifier =~ m/i$/ ? ' [<integer>]' :
Branch: 3 branches
BranchTrueFalseTotal
$specifier =~ /i$/ ? : 39 114 153
$specifier =~ /s$/ ? : 75 39 114
$specifier =~ /f$/ ? : 39 0 39
600 $specifier =~ m/s$/ ? ' [<string>]' :
601 $specifier =~ m/f$/ ? ' [<float>]' :
602 ' [<???>]');
603 }
604 elsif (defined $opt_valtext)
605 {
606 0 die 'internal inconsistency: specifierless value text in ',
607 $option
608 }
609 else
610 {
611 48 $opt_valtext = '';
612 }
613 338 ▶ $optUsage .= 0 == @option_vars ? $indent_opt1 : $indent_opt2;
Branch: 1 branch
BranchTrueFalseTotal
0 == @option_vars ? : 105 233 338
614 338 ▶ $optUsage .= '-'.$short_option.'|' if defined $short_option;
Branch: 1 branch
BranchTrueFalseTotal
if defined $short_option 300 38 338
615 338 $optUsage .= '--'.$long_option.$opt_valtext."\n";
616 338 $optUsage .= $indent_help.(shift).$default_text."\n";
617 338 my $option_key = $long_option;
618 338 ▶ $option_key .= '|'.$short_option if defined $short_option;
Branch: 1 branch
BranchTrueFalseTotal
if defined $short_option 300 38 338
619 # fix default numeric values of optional integer parameters:
620 338 ▶ $option_key .= $specifier eq ':i' ? ':+' : $specifier;
Branch: 1 branch
BranchTrueFalseTotal
$specifier eq ':i' ? : 40 298 338
621 {
622 14 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
623 338 push @options, $option_key, *{$var}{SCALAR};
624 }
625 338 push @option_vars, $var;
626 338 $option_type{$var} = $specifier;
627 338 $option_type{$var} =~ s/[:=]//;
628 338 ▶ $max_length = length($var) if $max_length < length($var);
Branch: 1 branch
BranchTrueFalseTotal
if $max_length < length $var 139 199 338
629 338 ▶ if ($is_multiple)
Branch: 1 branch
BranchTrueFalseTotal
if ($is_multiple) 9 329 338
630 {
631 9 ▶ croak('multiple option support per option and per global',
Branch: 1 branch
BranchTrueFalseTotal
if $use_multiple 1 8 9
632 ' flag is mutually exclusive in ', __PACKAGE__)
633 if $use_multiple;
634 8 $options[-2] .= '@';
635 8 $multiple_options{$var} = $long_option;
636 }
637 # Undefined optional options must be defaulted to undef to
638 # distinguish them from the default value "empty string":
639 337 ▶ if ($specifier =~ m/^:i$/)
Branch: 2 branches
BranchTrueFalseTotal
if ($specifier =~ /^:i$/) { } 40 297 337
elsif ($specifier =~ /^:f$/) { } 40 257 297
640 {
641 40 $optional_integers{$var} = 1;
642 }
643 elsif ($specifier =~ m/^:f$/)
644 {
645 40 $optional_floats{$var} = 0.0;
646 }
647 }
648  
649 elsif ($option =~ m/^\(.+\)$/)
650 {
651 32 $optUsage .= "\n".(shift)."\n";
652 }
653 elsif ($option eq '->-')
654 {
655 4 shift;
656 }
657 elsif ($option eq '->debug')
658 {
659 2 $_ = shift;
660 2 ▶ m/^([-a-z0-9]{2,})$/i or
Branch: 1 branch
BranchTrueFalseTotal
/^([-a-z0-9]{2,})$/i or croak("bad renaming of debug in ", __PACKAGE__) 1 1 2
661 croak 'bad renaming of debug in ', __PACKAGE__;
662 1 $debug_opt_name = 'opt_'.$1;
663 }
664 elsif ($option eq '->default')
665 {
666 2 $_ = shift;
667 2 ▶ m/%s/i or
Branch: 1 branch
BranchTrueFalseTotal
/%s/i or croak("default text must contain %s in ", __PACKAGE__) 1 1 2
668 croak 'default text must contain %s in ', __PACKAGE__;
669 1 $default_template = $_;
670 }
671 elsif ($option eq '->help')
672 {
673 3 $_ = shift;
674 3 ▶ m/^(\w)>([-a-z0-9]{2,})$/i or
Branch: 1 branch
BranchTrueFalseTotal
/^(\w)>([-a-z0-9]{2,})$/i or croak("bad renaming of help in ", __PACKAGE__) 2 1 3
675 croak 'bad renaming of help in ', __PACKAGE__;
676 2 $help_long = $2;
677 2 $help_opt_name = 'opt_'.$2;
678 2 $help_options = $2.'|'.$1.'|?+';
679 }
680 elsif ($option eq '->multiple')
681 {
682 10 ▶ croak('multiple option support per option and per global',
Branch: 1 branch
BranchTrueFalseTotal
if 0 < (my(@list) = %multiple_options) 1 9 10
683 ' flag is mutually exclusive in ', __PACKAGE__)
684 if 0 < (my @list = %multiple_options);
685 9 $use_multiple = 1;
686 9 $multiple = shift;
687 }
688 elsif ($option eq '->options')
689 {
690 1 $options_text = shift;
691 1 $indent_opt1 = $options_text.': ';
692 1 $indent_opt2 = ' ' x (length($options_text) + 3);
693 1 $indent_help = ' ' x (length($options_text) + 7);
694 }
695 elsif ($option eq '->usage')
696 {
697 1 $usage_text = shift;
698 }
699 elsif ($option eq 'ENV')
700 {
701 33 $env_prefix = shift;
702 }
703 elsif ($option eq 'ENV_')
704 {
705 33 $env_prefix = shift;
706 33 ▶ if (defined $env{$env_prefix.'_'})
Branch: 1 branch
BranchTrueFalseTotal
if (defined $env{$env_prefix . '_'}) 4 29 33
707 {
708 4 foreach (split(/\s+/, $env{$env_prefix.'_'}))
709 {
710 7 s/^([-_a-z0-9]{2,})=?//;
711 7 (my $env_var = $env_prefix.uc($1)) =~ tr/-/_/;
712 $env{$env_var} = $_ ne '' ? $_ : 1
713 7 ▶ unless defined $env{$env_var};
Branch: 2 branches
BranchTrueFalseTotal
unless defined $env{$env_var} 6 1 7
$_ ne '' ? : 5 1 6
714 }
715 }
716 }
717 else
718 {
719 2 croak 'bad option ', $option, ' passed to ', __PACKAGE__;
720 }
721 }
722 # for global multiple set-up using arrays:
723 104 ▶ if ($use_multiple)
Branch: 1 branch
BranchTrueFalseTotal
if ($use_multiple) 8 96 104
724 {
725 8 ▶ for ($_ = 0; $_ < $#options; $_ += 2)
Branch: 1 branch
BranchTrueFalseTotal
if ($_ < $#options) 65 8 73
726 {
727 65 $options[$_] =~ s/:\+/:i/;
728 65 ▶ if ($options[$_] =~ m/[:=][fis]$/)
Branch: 1 branch
BranchTrueFalseTotal
if ($options[$_] =~ /[:=][fis]$/) { } 56 9 65
729 {
730 56 $options[$_] .= '@';
731 }
732 else
733 {
734 9 $options[$_] .= ':+';
735 }
736 }
737 }
738 # finish help text:
739 $optUsage =
740 104 $usage_text.': '.basename($0).' [<'.$options_text.'>] [--]'.$optUsage;
741  
742 {
743 14 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
744 104 unshift @options, $help_options, *{$help_opt_name}{SCALAR};
745 }
746 104 ▶ unless (GetOptions(@options))
Branch: 1 branch
BranchTrueFalseTotal
unless (&GetOptions(@options)) 2 102 104
747 {
748 2 $_ = $0;
749 2 s|.*/||;
750 2 print STDERR "Try `$_ --$help_long' for more information.\n";
751 2 exit 1;
752 }
753  
754 14 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
755 14 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
756 102 ▶ if ($$help_opt_name or ($has_only_options and 0 <= $#ARGV))
Branch: 1 branch
BranchTrueFalseTotal
if ($$help_opt_name or $has_only_options and 0 <= $#ARGV) 5 97 102
Condition100%6/6
$$help_opt_name or $has_only_options and 0 <= $#ARGV
l!l&&r!l&&!r
4197
$has_only_options and 0 <= $#ARGV
!ll&&!rl&&r
30671
MC/DC100%3/3
$$help_opt_name or $has_only_options and 0 <= $#ARGV
$$help_opt_name $has_only_options 0 <= $#ARGV
Truth table100%4/4
A or B and C
A= $$help_opt_nameB= $has_only_optionsC= 0 <= $#ARGV
ABCresult
1XX1
0111
00X0
0100
757 {
758 5 print STDERR $optUsage; exit -1;
759 }
760  
761 # handle concatenated multiples:
762 97 ▶ if ($use_multiple)
Branch: 1 branch
BranchTrueFalseTotal
if ($use_multiple) 8 89 97
763 {
764 8 ▶ if (defined $multiple)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $multiple) { } 5 3 8
765 {
766 5 foreach my $option (@option_vars)
767 {
768 41 ▶ next unless defined $$option;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $$option 4 37 41
769 37 ▶ next unless ref($$option) eq 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $$option eq "ARRAY" 5 32 37
770 32 ▶ if ($option_type{$option} eq 's')
Branch: 2 branches
BranchTrueFalseTotal
if ($option_type{$option} eq 's') { } 14 18 32
elsif ($option_type{$option} eq 'i' or $option_type{$option} eq 'f') { } 18 0 18
771 {
772 14 $$option = join($multiple, @$$option);
773 }
774 ▶ elsif ($option_type{$option} eq 'i' or
Condition66%2/3
$option_type{$option} eq "i" or $option_type{$option} eq "f"
l!l&&r!l&&!r
990
MC/DC0%0/2
$option_type{$option} eq "i" or $option_type{$option} eq "f"
$option_type{$option} eq "i" $option_type{$option} eq "f"
Truth table66%2/3
A or B
A= $option_type{$option} eq "i"B= $option_type{$option} eq "f"
ABresult
1X1
011
000
775 $option_type{$option} eq 'f')
776 {
777 18 my $sum = 0;
778 18 $sum += $_ foreach @$$option;
779 18 $$option = $sum;
780 }
781 else
782 {
783 die 'internal inconsistency: $option_type{$option} is ',
784 0 $option_type{$option};
785 }
786 }
787 }
788 # support for multiple options, array flavour:
789 else
790 {
791 3 foreach my $option (@option_vars)
792 {
793 24 ▶ next unless $option_type{$option} eq '';
Branch: 1 branch
BranchTrueFalseTotal
unless $option_type{$option} eq "" 21 3 24
794 next # paranoia check, this should never occur!
795 3 ▶ if ref($$option) ne '';
Branch: 1 branch
BranchTrueFalseTotal
if ref $$option ne "" 0 3 3
796 3 ▶ next if $$option == 1;
Branch: 1 branch
BranchTrueFalseTotal
if $$option == 1 1 2 3
797 2 $_ = [ (1) x $$option ];
798 2 $$option = $_;
799 }
800 }
801 }
802  
803 # get defaults from environment, if applicable:
804 97 ▶ if (defined $env_prefix)
Branch: 1 branch
BranchTrueFalseTotal
if (defined $env_prefix) 31 66 97
805 {
806 # set default values, if not overwritten:
807 31 foreach (@option_vars)
808 {
809 241 ▶ next if defined $$_;
Branch: 1 branch
BranchTrueFalseTotal
if defined $$_ 143 98 241
810 98 my $env_var = $env_prefix.uc(substr($_, 4));
811 98 ▶ $$_ = $env{$env_var} if defined $env{$env_var};
Branch: 1 branch
BranchTrueFalseTotal
if defined $env{$env_var} 10 88 98
812 }
813 }
814  
815 # get defaults from constants:
816 97 foreach (keys %default_value)
817 {
818 5 ▶ next if defined $$_;
Branch: 1 branch
BranchTrueFalseTotal
if defined $$_ 1 4 5
819 4 $$_ = $default_value{$_};
820 }
821  
822 # declare main option variables and export local option variables to it:
823 97 *{$package.'::optUsage'} = \$optUsage;
824 {
825 14 ▶ no warnings "once"; # disable "GMH::opt_ ... used only once" warning
Subroutine BEGIN: called CC=1 SCAR=0.0
826 97 foreach (@option_vars)
827 {
828 # single element arrays become scalars instead:
829 308 ▶ if (ref($$_) eq 'ARRAY' and 1 == @$$_)
Branch: 1 branch
BranchTrueFalseTotal
if (ref $$_ eq 'ARRAY' and 1 == @$$_) { } 11 297 308
Condition100%3/3
ref $$_ eq "ARRAY" and 1 == @$$_
!ll&&!rl&&r
2781911
MC/DC100%2/2
ref $$_ eq "ARRAY" and 1 == @$$_
ref $$_ eq "ARRAY" 1 == @$$_
Truth table100%3/3
A and B
A= ref $$_ eq "ARRAY"B= 1 == @$$_
ABresult
0X0
100
111
830 {
831 11 *{$package.'::'.$_} = \$$_->[0];
832 }
833 else
834 {
835 297 *{$package.'::'.$_} = \$$_;
836 }
837 }
838 }
839  
840 # print debug info, if $opt_debug is used:
841 97 ▶ if ($$debug_opt_name)
Branch: 1 branch
BranchTrueFalseTotal
if ($$debug_opt_name) 5 92 97
842 {
843 5 print STDERR $indent_opt1, "\n";
844 5 foreach (@option_vars)
845 {
846 31 ▶ print(STDERR
Branch: 3 branches
BranchTrueFalseTotal
!defined($$_) ? : 14 17 31
ref $$_ eq 'ARRAY' ? : 2 15 17
$$_ =~ /^-?\d+(?:\.\d+)?$/ ? : 11 4 15
847 $indent_opt2, '$', $_, ':',
848 (' ' x ( $max_length - length($_) + 1 )),
849 (! defined $$_ ? 'undef' :
850 ref($$_) eq 'ARRAY'
851 ? '('.join(', ', @$$_).')'
852 : $$_ =~ m/^-?\d+(?:\.\d+)?$/ ? $$_ : '"'.$$_.'"'),
853 "\n");
854 }
855 5 ▶ print STDERR "parameter:\n" if @ARGV;
Branch: 1 branch
BranchTrueFalseTotal
if @ARGV 2 3 5
856 print STDERR $indent_opt2,
857 ($_ =~ m/^-?\d+(?:\.\d+)?$/ ? $_ : '"'.$_.'"'), "\n"
858 5 ▶ foreach (@ARGV);
Branch: 1 branch
BranchTrueFalseTotal
$_ =~ /^-?\d+(?:\.\d+)?$/ ? : 3 3 6
859 }
860 }
861 14 1;
862  
863 #******************************************************************
864  
865 __END__
↑ Summary