EX/Long.pm

filter: Statementstmt 97.9% 146 / 149 Branchbran 77.2% 34 / 44 Conditioncond 77.2% 17 / 22 MC/DCmcdc 42.8% 6 / 14 Subroutinesub 91.4% 32 / 35 Podpod 36.3% 4 / 11 totaltotal 86.9% 239 / 275 CC 32 SCAR 12.1
CC
32
Cov
92%
env_no_user_settings
6.0
new
6.0
__ANON__
6.0
CRAP 3.3
« EX/Util.pm ↑ Summary EX.pm »
1 package Getopt::EX::Long;
2  
3 6 our $VERSION = "3.05";
4  
5 6 ▶use v5.14;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 6 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 6 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 {
10 6 ▶ no warnings 'once';
Subroutine BEGIN: called CC=1 SCAR=0.0
11 6 *REQUIRE_ORDER = \$Getopt::Long::REQUIRE_ORDER;
12 6 *PERMUTE = \$Getopt::Long::PERMUTE;
13 6 *RETURN_IN_ORDER = \$Getopt::Long::RETURN_IN_ORDER;
14  
15 6 *Configure = \&Getopt::Long::Configure;
16 6 *HelpMessage = \&Getopt::Long::HelpMessage;
17 6 *VersionMessage = \&Getopt::Long::VersionMessage;
18 }
19  
20 6 ▶use Exporter 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
21 6 our @EXPORT = qw(&GetOptions $REQUIRE_ORDER $PERMUTE $RETURN_IN_ORDER);
22 6 our @EXPORT_OK = ( '&GetOptionsFromArray',
23 # '&GetOptionsFromString',
24 '&Configure',
25 '&HelpMessage',
26 '&VersionMessage',
27 '&ExConfigure',
28 '&ExReset',
29 );
30 6 ▶use parent qw(Getopt::Long);
Subroutine BEGIN: called CC=1 SCAR=0.0
31  
32 6 ▶use Data::Dumper;
Subroutine BEGIN: called CC=1 SCAR=0.0
33 6 ▶use Getopt::Long();
Subroutine BEGIN: called CC=1 SCAR=0.0
34 6 ▶use Getopt::EX::Loader;
Subroutine BEGIN: called CC=1 SCAR=0.0
35 6 ▶use Getopt::EX::Func qw(parse_func);
Subroutine BEGIN: called CC=1 SCAR=0.0
36  
37 6 my %DefaultConfigOption = ( AUTO_DEFAULT => 1, USER_SETTINGS => 1 );
38 6 my @ValidOptions = (qw(AUTO_DEFAULT USER_SETTINGS), @Getopt::EX::Loader::OPTIONS);
39  
40 # The config options and the loader belong to a program, whose name
41 # ($0) determines the rc file and the base class. They are kept for
42 # each program name, so that programs called as functions in one
43 # process (Command::Run nofork, for example) do not share them.
44 6 my %ConfigOption;
45 my %Loader;
46 6 my $loader_pid = $$; # Set at module load time for fork detection
47  
48 4 ▶sub ExReset {
Subroutine ExReset: called CC=1 SCAR=0.0
Pod documented
49 4 %ConfigOption = ();
50 4 %Loader = ();
51 4 $loader_pid = $$;
52 }
53  
54 # Name of the program: the basename of $0 or the given path
55 45 ▶sub prog_name {
Subroutine prog_name: called CC=3 SCAR=11.1
Pod undocumented
56 45 ▶ my $path = @_ ? shift : $0;
Branch: 1 branch
BranchTrueFalseTotal
@_ ? : 7 38 45
57 45 ▶ $path =~ m{([^/]+)$} ? $1 : $path;
Branch: 1 branch
BranchTrueFalseTotal
$path =~ m[([^/]+)$]u ? : 45 0 45
58 }
59  
60 # True when the environment says that the program should not read
61 # user settings: GETOPTEX_NO_USER_SETTINGS is 1 or * for all programs,
62 # or a list of program names separated by spaces or commas.
63 18 ▶sub env_no_user_settings {
Subroutine env_no_user_settings: called CC=6 SCAR=17.9
Pod undocumented
64 18 my $prog = shift;
65 18 ▶ my $env = $ENV{GETOPTEX_NO_USER_SETTINGS} // return 0;
Condition100%2/2
$ENV{"GETOPTEX_NO_USER_SETTINGS"} // (return 0)
l!l
513
MC/DC100%1/1
$ENV{"GETOPTEX_NO_USER_SETTINGS"} // (return 0)
$ENV{"GETOPTEX_NO_USER_SETTINGS"}
Truth table100%2/2
A
A= $ENV{"GETOPTEX_NO_USER_SETTINGS"}
Aresult
11
00
66 5 ▶ return 0 if $env eq '' or $env eq '0';
Branch: 1 branch
BranchTrueFalseTotal
if $env eq "" or $env eq 0 2 3 5
Condition100%3/3
$env eq "" or $env eq 0
l!l&&r!l&&!r
113
MC/DC100%2/2
$env eq "" or $env eq 0
$env eq "" $env eq 0
Truth table100%3/3
A or B
A= $env eq ""B= $env eq 0
ABresult
1X1
011
000
67 3 ▶ return 1 if $env eq '1' or $env eq '*';
Branch: 1 branch
BranchTrueFalseTotal
if $env eq 1 or $env eq "*" 1 2 3
Condition66%2/3
$env eq 1 or $env eq "*"
l!l&&r!l&&!r
102
MC/DC50%1/2
$env eq 1 or $env eq "*"
$env eq 1 $env eq "*"
Truth table66%2/3
A or B
A= $env eq 1B= $env eq "*"
ABresult
1X1
011
000
68 2 scalar grep { $_ eq $prog } split /[\s,]+/, $env;
69 }
70  
71 # Config options of the current program, or of the named one
72 29 ▶sub config_option {
Subroutine config_option: called CC=4 SCAR=13.9
Pod documented
73 29 my $prog = prog_name(@_);
74 29 ▶ ExReset() if $loader_pid != $$;
Branch: 1 branch
BranchTrueFalseTotal
if $loader_pid != $$ 0 29 29
75 29 ▶ $ConfigOption{$prog} //= {
Branch: 1 branch
BranchTrueFalseTotal
env_no_user_settings($prog) ? : 2 16 18
Condition100%2/2
$ConfigOption{$prog} //= {%DefaultConfigOption, env_no_user_settings($prog) ? ("USER_SETTINGS", 0) : ()}
l!l
1118
MC/DC100%1/1
$ConfigOption{$prog} //= {%DefaultConfigOption, env_no_user_settings($prog) ? ("USER_SETTINGS", 0) : ()}
$ConfigOption{$prog}
Truth table100%2/2
A
A= $ConfigOption{$prog}
Aresult
11
00
76 %DefaultConfigOption,
77 env_no_user_settings($prog) ? (USER_SETTINGS => 0) : (),
78 };
79 }
80  
81 # Options for Getopt::EX::Loader->new from the config options. RCFILE
82 # is dropped when the program does not read user settings.
83 15 ▶sub loader_options {
Subroutine loader_options: called CC=3 SCAR=11.0
Pod undocumented
84 15 my $config = shift;
85 my %opt = map {
86 15 ▶ exists $config->{$_} ? ( $_ => $config->{$_} ) : ()
Branch: 1 branch
BranchTrueFalseTotal
exists $config->{$_} ? : 29 76 105
87 } @Getopt::EX::Loader::OPTIONS;
88 15 ▶ delete $opt{RCFILE} unless $config->{USER_SETTINGS};
Branch: 1 branch
BranchTrueFalseTotal
unless $config->{"USER_SETTINGS"} 6 9 15
89 15 %opt;
90 }
91  
92 16 ▶sub GetOptions {
Subroutine GetOptions: called CC=1 SCAR=0.0
Pod documented
93 16 unshift @_, \@ARGV;
94 16 goto &GetOptionsFromArray;
95 }
96  
97 16 ▶sub GetOptionsFromArray {
Subroutine GetOptionsFromArray: called CC=4 SCAR=14.3
Pod undocumented
98 16 my $argv = $_[0];
99  
100 16 my $config = config_option();
101  
102 16 ▶ set_default($config) if $config->{AUTO_DEFAULT};
Branch: 1 branch
BranchTrueFalseTotal
if $config->{"AUTO_DEFAULT"} 16 0 16
103  
104 16 ▶ my $loader = $Loader{prog_name()} //= Getopt::EX::Loader->new(loader_options($config));
Condition66%2/3
$Loader{prog_name()} //= "Getopt::EX::Loader"->new(loader_options($config))
l!l&&r!l&&!r
1150
MC/DC0%0/2
$Loader{prog_name()} //= "Getopt::EX::Loader"->new(loader_options($config))
$Loader{prog_name()} "Getopt::EX::Loader"->new(loader_options($config))
Truth table66%2/3
A //= B
A= $Loader{prog_name()}B= "Getopt::EX::Loader"->new(loader_options($config))
ABresult
1X1
011
000
105  
106 16 $loader->deal_with($argv);
107  
108 16 my @builtins = do {
109 16 ▶ if (ref $_[1] eq 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $_[1] eq 'HASH') { } 1 15 16
110 1 $loader->hashed_builtins($_[1]);
111 } else {
112 15 $loader->builtins;
113 }
114 };
115 16 push @_, @builtins;
116  
117 # Suppress "Duplicate specification" warnings from Getopt::Long
118 0 ▶ local $SIG{__WARN__} = sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
119 0 ▶ warn @_ unless $_[0] =~ /^Duplicate specification/;
Branch: 1 branch
BranchTrueFalseTotal
unless $_[0] =~ /^Duplicate specification/u 0 0 0
120 16 };
121 16 Getopt::Long::GetOptionsFromArray(@_);
122 }
123  
124 0 ▶sub GetOptionsFromString {
Subroutine GetOptionsFromString: not called CC=1 SCAR=6.9
Pod undocumented
125 0 die "GetOptionsFromString is not supported, yet.\n";
126 }
127  
128 6 ▶sub ExConfigure {
Subroutine ExConfigure: called CC=5 SCAR=16.3
Pod documented
129 6 my %opt = @_;
130 6 ▶ my $config = config_option(delete $opt{PROGRAM} // $0);
Condition66%2/3
delete $opt{"PROGRAM"} // $0
l!l&&r!l&&!r
240
MC/DC0%0/2
delete $opt{"PROGRAM"} // $0
delete $opt{"PROGRAM"} $0
Truth table66%2/3
A // B
A= delete $opt{"PROGRAM"}B= $0
ABresult
1X1
011
000
131 6 for my $name (@ValidOptions) {
132 54 ▶ if (exists $opt{$name}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $opt{$name}) 7 47 54
133 7 $config->{$name} = delete $opt{$name};
134 }
135 }
136 6 ▶ warn "Unknown option: ", Dumper \%opt if %opt;
Branch: 1 branch
BranchTrueFalseTotal
if %opt 0 6 6
137 }
138  
139 16 ▶sub set_default {
Subroutine set_default: called CC=1 SCAR=0.0
Pod undocumented
140 16 my $config = shift;
141 6 ▶ use List::Util qw(pairmap);
Subroutine BEGIN: called CC=1 SCAR=0.0
142 16 ▶ pairmap { $config->{$a} //= $b } get_default();
Subroutine __ANON__: called CC=2 SCAR=7.1
Condition66%2/3
$config->{$a} //= $b
l!l&&r!l&&!r
3280
MC/DC0%0/2
$config->{$a} //= $b
$config->{$a} $b
Truth table66%2/3
A //= B
A= $config->{$a}B= $b
ABresult
1X1
011
000
143 }
144  
145 18 ▶sub get_default {
Subroutine get_default: called CC=4 SCAR=14.0
Pod undocumented
146 18 my @list;
147  
148 18 ▶ my $prog = ($0 =~ /([^\/]+)$/) ? $1 : return ();
Branch: 1 branch
BranchTrueFalseTotal
$0 =~ m[([^/]+)$]u ? : 18 0 18
149  
150 18 ▶ if (defined (my $home = $ENV{HOME})) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $home = $ENV{"HOME"})) 18 0 18
151 18 ▶ if (-f (my $rc = "$home/.${prog}rc")) {
Branch: 1 branch
BranchTrueFalseTotal
if (-f (my $rc = "$home/.${prog}rc")) 16 2 18
152 16 push @list, RCFILE => $rc;
153 }
154 }
155  
156 18 push @list, BASECLASS => "App::$prog";
157  
158 18 @list;
159 }
160  
161 6 1;
162  
163 ############################################################
164  
165 package Getopt::EX::Long::Parser;
166  
167 6 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
168 6 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
169  
170 6 ▶use List::Util qw(first);
Subroutine BEGIN: called CC=1 SCAR=0.0
171 6 ▶use Data::Dumper;
Subroutine BEGIN: called CC=1 SCAR=0.0
172  
173 6 ▶use Getopt::Long(); # Load first to make Getopt::Long::Parser available
Subroutine BEGIN: called CC=1 SCAR=0.0
174 6 ▶use parent -norequire, qw(Getopt::Long::Parser);
Subroutine BEGIN: called CC=1 SCAR=0.0
175  
176 6 ▶use Getopt::EX::Loader;
Subroutine BEGIN: called CC=1 SCAR=0.0
177  
178 3 ▶sub new {
Subroutine new: called CC=6 SCAR=17.9
179 3 my $class = shift;
180  
181 3 my @exconfig;
182 3 ▶ while (defined (my $i = first { $_[$_] eq 'exconfig' } keys @_)) {
Subroutine __ANON__: called CC=1 SCAR=0.0
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $i = &first(sub { $_[$_] eq "exconfig"; } , keys @_))) 1 3 4
183 1 push @exconfig, @{ (splice @_, $i, 2)[1] };
184 }
185 3 my $config = Getopt::EX::Long::config_option();
186 3 ▶ if (@exconfig == 0 and $config->{AUTO_DEFAULT}) {
Branch: 1 branch
BranchTrueFalseTotal
if (@exconfig == 0 and $config->{"AUTO_DEFAULT"}) 2 1 3
Condition66%2/3
@exconfig == 0 and $config->{"AUTO_DEFAULT"}
!ll&&!rl&&r
102
MC/DC50%1/2
@exconfig == 0 and $config->{"AUTO_DEFAULT"}
@exconfig == 0 $config->{"AUTO_DEFAULT"}
Truth table66%2/3
A and B
A= @exconfig == 0B= $config->{"AUTO_DEFAULT"}
ABresult
0X0
100
111
187 2 @exconfig = Getopt::EX::Long::get_default();
188 }
189 3 my %exconfig = @exconfig;
190 3 ▶ if (exists $exconfig{USER_SETTINGS}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $exconfig{"USER_SETTINGS"}) 1 2 3
191 1 $config->{USER_SETTINGS} = delete $exconfig{USER_SETTINGS};
192 }
193 3 ▶ delete $exconfig{RCFILE} unless $config->{USER_SETTINGS};
Branch: 1 branch
BranchTrueFalseTotal
unless $config->{"USER_SETTINGS"} 2 1 3
194 3 @exconfig = %exconfig;
195  
196 3 my $obj = $class->SUPER::new(@_);
197  
198 3 my $loader = $obj->{exloader} = Getopt::EX::Loader->new(@exconfig);
199  
200 3 $obj;
201 }
202  
203 3 ▶sub getoptionsfromarray {
Subroutine getoptionsfromarray: called CC=2 SCAR=7.1
204 3 my $obj = shift;
205 3 my $argv = $_[0];
206 3 my $loader = $obj->{exloader};
207  
208 3 $loader->deal_with($argv);
209  
210 3 my @builtins = do {
211 3 ▶ if (ref $_[1] eq 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $_[1] eq 'HASH') { } 1 2 3
212 1 $loader->hashed_builtins($_[1]);
213 } else {
214 2 $loader->builtins;
215 }
216 };
217 3 push @_, @builtins;
218  
219 # Suppress "Duplicate specification" warnings from Getopt::Long
220 0 ▶ local $SIG{__WARN__} = sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
221 0 ▶ warn @_ unless $_[0] =~ /^Duplicate specification/;
Branch: 1 branch
BranchTrueFalseTotal
unless $_[0] =~ /^Duplicate specification/u 0 0 0
222 3 };
223 3 $obj->SUPER::getoptionsfromarray(@_);
224 }
225  
226 6 1;
227  
228 =head1 NAME
229  
230 Getopt::EX::Long - Getopt::Long compatible extended module
231  
232 =head1 SYNOPSIS
233  
234 use Getopt::EX::Long;
235 GetOptions("file=s" => \my $file);
236  
237 or using the object-oriented interface:
238  
239 use Getopt::EX::Long;
240 my $parser = Getopt::EX::Long::Parser->new(
241 config => [ qw(posix_default no_ignore_case) ],
242 exconfig => [ BASECLASS => 'App::example' ],
243 );
244 $parser->getoptions("file=s" => \my $file);
245  
246 =head1 DESCRIPTION
247  
248 L<Getopt::EX::Long> is almost fully compatible with L<Getopt::Long>.
249 You can replace the module declaration, and it should work the same as
250 before (see L</INCOMPATIBILITY>).
251  
252 In addition to standard L<Getopt::Long> functionality, users can
253 define their own option aliases and write dynamically loaded extension
254 modules. If the command name is I<example>, the file
255  
256 ~/.examplerc
257  
258 is loaded by default. In this rc file, users can define option
259 aliases with macro processing. This is useful when the command takes
260 complex arguments.
261  
262 Special options starting with B<-M> load the corresponding Perl
263 module. The module is assumed to be under a specific base class. For
264 example:
265  
266 % example -Mfoo
267  
268 loads the C<App::example::foo> module by default.
269  
270 Since extension modules are normal Perl modules, users can write any
271 code they need. If the module is specified with an initial function
272 call, that function is called when the module is loaded:
273  
274 % example -Mfoo::bar(buz=100)
275  
276 This loads module B<foo> and calls function I<bar> with the parameter
277 I<buz> set to 100.
278  
279 If the module includes a C<__DATA__> section, it is interpreted as an
280 rc file. Combined with the startup function call, this allows module
281 behavior to be controlled through user-defined options.
282  
283 For details about rc files and module specification, see
284 L<Getopt::EX::Module>.
285  
286 =head1 CONFIG OPTIONS
287  
288 Config options are set by B<ExConfigure> or the B<exconfig>
289 parameter for the B<Getopt::EX::Long::Parser::new> method.
290  
291 =over 4
292  
293 =item AUTO_DEFAULT
294  
295 Config options B<RCFILE> and B<BASECLASS> are automatically set based
296 on the name of the command executable. If you don't want this behavior,
297 set B<AUTO_DEFAULT> to 0.
298  
299 =item USER_SETTINGS
300  
301 Whether to read the startup rc file of the program, F<~/.>I<prog>F<rc>
302 or the file given by B<RCFILE>. Defaults to 1. When set to 0, the
303 rc file is not read. Modules loaded with B<-M> and their default
304 options are not affected. The environment variable
305 B<GETOPTEX_NO_USER_SETTINGS> sets it to 0 from outside of the
306 program (see L</ENVIRONMENT>).
307  
308 A program which takes default options from somewhere else than the
309 rc file can skip them as well; see B<config_option>.
310  
311 =item PROGRAM
312  
313 Not a config option itself, but names the program whose config
314 options are set by this B<ExConfigure> call. Default is the current
315 program, the basename of C<$0>.
316  
317 This is for a program which calls another program as a function in
318 the same process, as L<Command::Run> does in its nofork mode: the
319 callee reads its own rc file, because its config options are kept
320 apart from those of the caller (see L</PROGRAM STATE>). The rc file
321 holds the settings of the user for the callee run from the command
322 line, and the output of the caller should not depend on them. The
323 caller turns them off for the callee by name, before the first
324 B<GetOptions> call of the callee:
325  
326 ExConfigure(PROGRAM => 'ansicolumn', USER_SETTINGS => 0);
327  
328 =back
329  
330 Other options including B<RCFILE> and B<BASECLASS> are passed to
331 B<Getopt::EX::Loader>. Read its documentation for details.
332  
333 =head1 FUNCTIONS
334  
335 =over 4
336  
337 =item B<ExConfigure>
338  
339 Set config options. See L</CONFIG OPTIONS>.
340  
341 =item B<ExReset>
342  
343 Reset the internal loader and configuration to their default state.
344 This is useful when you need to reinitialize the module state, for
345 example after forking a child process.
346  
347 Note that B<ExConfigure> and B<GetOptionsFromArray> automatically
348 detect forked processes and reset internally, so explicit calls to
349 B<ExReset> are usually unnecessary.
350  
351 =item B<config_option> [ I<program> ]
352  
353 Return the hash reference to the config options of the current
354 program, or of the named one.
355  
356 Some programs take default options from an environment variable as
357 well, as B<greple> does with C<GREPLEOPTS>. This module does not
358 handle such variables, but the program can read C<USER_SETTINGS>
359 through this function and skip them when it is 0, along with the rc
360 file:
361  
362 if (Getopt::EX::Long::config_option()->{USER_SETTINGS}) {
363 unshift @ARGV, shellwords($ENV{GREPLEOPTS} // '');
364 }
365  
366 =back
367  
368 =head1 ENVIRONMENT
369  
370 =over 4
371  
372 =item GETOPTEX_NO_USER_SETTINGS
373  
374 Set B<USER_SETTINGS> to 0 for the programs named in it, separated by
375 spaces or commas, or for every program when it is C<1> or C<*>, as
376 far as the programs read their rc file through this module. Use it
377 to run programs without the settings of the user, in tests or in a
378 container, and to reach programs which are started as separate
379 processes. It is read when the config options of a program are first
380 used, so it has to be set before that.
381  
382 =back
383  
384 =head1 PROGRAM STATE
385  
386 The config options and the loader (which holds the rc file and the
387 modules loaded) belong to the program, whose name C<$0> determines the
388 default rc file and base class. They are kept for each program
389 name, the basename of C<$0>: when C<$0> is changed, as
390 L<Command::Run> does to call a program as a function without forking,
391 B<ExConfigure> and B<GetOptions> work on the state of that program,
392 and the rc file of one program is not applied to another.
393  
394 The state of a program is created when it is first used, and the
395 loader is created at its first B<GetOptions> call and kept. Config
396 options given for a program afterwards, with B<PROGRAM> or through the
397 environment, do not change the loader which has already read the rc
398 file. When the process is forked, the state is reset in the child, so
399 a caller should set the config options of the callee right before
400 calling it.
401  
402 =head1 INCOMPATIBILITY
403  
404 The subroutine B<GetOptionsFromString> is not supported.
405  
406 =head1 SEE ALSO
407  
408 L<Getopt::EX>,
409 L<Getopt::EX::Module>,
410 L<Getopt::EX::Loader>
« EX/Util.pm ↑ Summary EX.pm »