EX/Func.pm

filter: Statementstmt 83.3% 60 / 72 Branchbran 65.0% 13 / 20 Conditioncond 75.0% 9 / 12 MC/DCmcdc 42.8% 3 / 7 Subroutinesub 75.0% 12 / 16 Podpod 0.0% 0 / 7 totaltotal 72.3% 97 / 134 CC 17 SCAR 18.3
CC
17
Cov
79%
parse_func
12.5
arg2kvlist
6.0
callable
6.0
CRAP 6.3
« EX/LabeledParam.pm ↑ Summary EX/Colormap.pm »
1 package Getopt::EX::Func;
2  
3 12 our $VERSION = "3.05";
4  
5 12 ▶use v5.14;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 12 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 12 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 12 ▶use Exporter 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
10 12 our @EXPORT = qw();
11 12 our @EXPORT_OK = qw(parse_func callable arg2kvlist);
12 12 our %EXPORT_TAGS = ( all => [ @EXPORT_OK ] );
13  
14 12 ▶use Data::Dumper;
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 12 ▶use Scalar::Util qw(blessed);
Subroutine BEGIN: called CC=1 SCAR=0.0
17 0 ▶sub callable {
Subroutine callable: not called CC=2 SCAR=17.9
Pod undocumented
18 0 my $target = shift;
19 0 ▶ blessed $target and $target->can('call');
Branch: 1 branch
BranchTrueFalseTotal
builtin::blessed($target) and $target->can("call") 0 0 0
20 }
21  
22 8 ▶sub new {
Subroutine new: called CC=1 SCAR=0.0
Pod undocumented
23 8 my $class = shift;
24 8 my $obj = bless [ @_ ], $class;
25 }
26  
27 0 ▶sub append {
Subroutine append: not called CC=1 SCAR=6.9
Pod undocumented
28 0 my $obj = shift;
29 0 push @$obj, @_;
30 }
31  
32 8 ▶sub call {
Subroutine call: called CC=1 SCAR=0.0
Pod undocumented
33 8 my $obj = shift;
34 8 unshift @_, @$obj;
35 8 my $name = shift;
36  
37 12 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
38 8 goto &$name;
39 }
40  
41 ##
42 ## Create a closure that calls the named function with preset arguments.
43 ## Used internally when parse_func is called with the 'pointer' option.
44 ## The 'package main' may be unnecessary since $name is fully qualified,
45 ## but is kept for safety in case of future changes.
46 ##
47 0 ▶sub closure {
Subroutine closure: not called CC=1 SCAR=2.2
Pod undocumented
48 0 my $name = shift;
49 0 my @argv = @_;
50 0 ▶ sub {
Subroutine __ANON__: not called CC=1 SCAR=0.6
51 package main;
52 12 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
53 0 unshift @_, @argv;
54 0 goto &$name;
55 }
56 0 }
57  
58 ##
59 ## sub { ... }
60 ## funcname(arg1,arg2,arg3=val3)
61 ## funcname=arg1,arg2,arg3=val3
62 ##
63  
64 ##
65 ## Regex to match balanced parentheses, including nested ones.
66 ## Uses recursive subpattern (?-1) to match inner parentheses.
67 ## Possessive quantifiers (++ and *+) prevent backtracking for efficiency.
68 ##
69 12 my $paren_re = qr/( \( (?: [^()]++ | (?-1) )*+ \) )/x;
70  
71 ##
72 ## Key name pattern for function arguments.
73 ## Should be \w+ but currently allows more characters for historical reasons.
74 ##
75 12 my $key_re = qr/[^,=*\/]+/;
76  
77 8 ▶sub parse_func {
Subroutine parse_func: called CC=11 SCAR=25.3
Pod undocumented
78 8 ▶ my $opt = ref $_[0] eq 'HASH' ? shift : {};
Branch: 1 branch
BranchTrueFalseTotal
ref $_[0] eq 'HASH' ? : 7 1 8
79 8 local $_ = shift;
80 8 my $noinline = $opt->{noinline};
81 8 my $pointer = $opt->{pointer};
82 8 my $caller = caller;
83 8 ▶ my $pkg = $opt->{PACKAGE} || $caller;
Condition66%2/3
$opt->{'PACKAGE'} || $caller
l!l&&r!l&&!r
710
MC/DC0%0/2
$opt->{'PACKAGE'} || $caller
$opt->{'PACKAGE'} $caller
Truth table66%2/3
A || B
A= $opt->{'PACKAGE'}B= $caller
ABresult
1X1
011
000
84  
85 8 my @func;
86  
87 8 ▶ if (not $noinline and /^sub\s*{/) {
Branch: 2 branches
BranchTrueFalseTotal
if (not $noinline and /^sub\s*{/u) { } 2 6 8
elsif (/^ &? (?<name> [\w:]+ ) (?<arg> $paren_re | =.* )? $/ux) { } 6 0 6
Condition66%2/3
not $noinline and /^sub\s*{/u
!ll&&!rl&&r
062
MC/DC50%1/2
not $noinline and /^sub\s*{/u
not $noinline /^sub\s*{/u
Truth table66%2/3
not(A) and B
A= not $noinlineB= /^sub\s*{/u
ABresult
0X0
100
111
88 2 my $sub = eval "package $pkg; $_";
89 2 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 2 2
90 0 warn "Error in function -- $_ --.\n";
91 0 die $@;
92 }
93 2 ▶ croak "Unexpected result from eval.\n" if ref $sub ne 'CODE';
Branch: 1 branch
BranchTrueFalseTotal
if ref $sub ne "CODE" 0 2 2
94 2 @func = ($sub);
95 }
96 elsif (m{^ &? (?<name> [\w:]+ ) (?<arg> $paren_re | =.* )? $}x) {
97 6 my $name = $+{name};
98 6 ▶ my $arg = $+{arg} // '';
Condition50%1/2
$+{"arg"} // ""
l!l
06
MC/DC0%0/1
$+{"arg"} // ""
$+{"arg"}
Truth table50%1/2
A
A= $+{"arg"}
Aresult
11
00
99 6 $arg =~ s/^ (?| \( (.*) \) | = (.*) ) $/$1/x;
100 6 ▶ $name =~ s/^/$pkg\::/ unless $name =~ /::/;
Branch: 1 branch
BranchTrueFalseTotal
unless $name =~ /::/u 5 1 6
101 6 @func = ($name, arg2kvlist($arg));
102 }
103 else {
104 0 return undef;
105 }
106  
107 8 ▶ __PACKAGE__->new( $pointer ? closure(@func) : @func );
Branch: 1 branch
BranchTrueFalseTotal
$pointer ? : 0 8 8
108 }
109  
110 ##
111 ## convert "key1,key2,key3=val3" to (key1=>1, key2=>1, key3=>"val3")
112 ##
113 ## *= takes the rest of the string as a value
114 ## e.g., "key1,key2*=a,b,c" => (key1=>1, key2=>"a,b,c")
115 ##
116 ## /= uses the next character as a delimiter
117 ## e.g., "key1,key2/=/a,b,c/,next" => (key1=>1, key2=>"a,b,c", next=>1)
118 ##
119 24 ▶sub arg2kvlist {
Subroutine arg2kvlist: called CC=6 SCAR=17.9
Pod undocumented
120 24 my @kv;
121 24 for (@_) {
122 24 ▶ while (/\G \s* (?<key>(?>${key_re}))
Branch: 1 branch
BranchTrueFalseTotal
if (m[\G \s* (?<key>(?>$key_re)) (?: \*= (?<value>.*) | /= (?<delim>.) (?<value>.*?) \g{delim} (?=,|\z) ,* | (?: = (?<value> (?:[^,()]++ | $paren_re)*+ ) )? ,* ) ]cgsux) 34 24 58
123 (?: \*= (?<value>.*)
124 | \/= (?<delim>.) (?<value>.*?) \g{delim} (?=,|\z) ,*
125 | (?: = (?<value> (?:[^,()]++ | ${paren_re})*+ ) )? ,* )
126 /xgcs) {
127 34 ▶ push @kv, ( $+{key}, $+{value} // 1 );
Condition100%2/2
$+{"value"} // 1
l!l
2311
MC/DC100%1/1
$+{"value"} // 1
$+{"value"}
Truth table100%2/2
A
A= $+{"value"}
Aresult
11
00
128 }
129 24 ▶ (pos() // 0) == length or die "parse error in \"$_\".\n";
Branch: 1 branch
BranchTrueFalseTotal
(pos $_ // 0) == length $_ or die qq[parse error in "$_".\n] 24 0 24
Condition100%2/2
pos $_ // 0
l!l
186
MC/DC100%1/1
pos $_ // 0
pos $_
Truth table100%2/2
A
A= pos $_
Aresult
11
00
130 }
131 24 @kv;
132 }
133  
134 12 1;
135  
136 =head1 NAME
137  
138 Getopt::EX::Func - Function call interface
139  
140  
141 =head1 SYNOPSIS
142  
143 use Getopt::EX::Func qw(parse_func);
144  
145 my $func = parse_func("func_name(key=value,flag)");
146  
147 $func->call;
148  
149 =head1 DESCRIPTION
150  
151 This module provides a way to create function call objects used in the
152 L<Getopt::EX> module set.
153  
154 For example, suppose your script has a B<--begin> option that
155 specifies a function to call at the beginning of execution. You can
156 implement it like this:
157  
158 use Getopt::EX::Func qw(parse_func);
159  
160 GetOptions("begin:s" => \$opt_begin);
161  
162 my $func = parse_func($opt_begin);
163  
164 $func->call;
165  
166 The user can then invoke the script as:
167  
168 % example -Mfoo --begin 'repeat(debug,msg=hello,count=2)'
169  
170 The function C<repeat> should be declared in module C<foo> or in a
171 startup rc file such as F<~/.examplerc>. It can be implemented like
172 this:
173  
174 our @EXPORT = qw(repeat);
175 sub repeat {
176 my %opt = @_;
177 print Dumper \%opt if $opt{debug};
178 say $opt{msg} for 1 .. $opt{count};
179 }
180  
181 =head1 FUNCTION SPEC
182  
183 The C<parse_func> function accepts the following string formats.
184  
185 A function name can optionally be prefixed with C<&>, and parameters
186 can be specified in two equivalent forms using parentheses or C<=>:
187  
188 func(key=value,key2=value2)
189 func=key=value,key2=value2
190 &func(key=value)
191  
192 So the following two commands are equivalent:
193  
194 % example --begin 'repeat(debug,msg=hello,count=2)'
195 % example --begin 'repeat=debug,msg=hello,count=2'
196  
197 Both will call the function as:
198  
199 repeat( debug => 1, msg => 'hello', count => '2' );
200  
201 Arguments are passed as I<key> =E<gt> I<value> pairs. Parameters
202 without a value (C<debug> in this example) are assigned the value 1.
203 Key names should only contain word characters (C<\w>: alphanumeric and
204 underscore). Currently, any characters except C<,>, C<=>, C<*>, and
205 C</> are accepted for historical reasons, but this may change in the
206 future.
207  
208 Commas normally separate parameters. If a value needs to contain
209 commas, there are two ways to handle this:
210  
211 =over 4
212  
213 =item Parentheses
214  
215 Commas inside parentheses are preserved:
216  
217 func(pattern=(a,b,c),debug)
218  
219 This calls:
220  
221 func( pattern => '(a,b,c)', debug => 1 );
222  
223 Note that the parentheses are included in the value.
224  
225 =item Asterisk-Equals
226  
227 Use C<*=> instead of C<=> to capture the entire remaining string as
228 the value:
229  
230 func(debug,pattern*=a,b,c)
231  
232 This calls:
233  
234 func( debug => 1, pattern => 'a,b,c' );
235  
236 Since C<*=> consumes the rest of the string, no parameters can follow
237 it.
238  
239 =item Slash-Equals with Delimiter
240  
241 Use C</=> followed by a delimiter character to quote a value. The
242 first character after C</=> becomes the delimiter, and the value
243 continues until the same delimiter appears again:
244  
245 func(debug,pattern/=/a,b,c/,verbose)
246  
247 This calls:
248  
249 func( debug => 1, pattern => 'a,b,c', verbose => 1 );
250  
251 The delimiter can be any character. Choose one that does not appear
252 in the value:
253  
254 func(pattern/=/a,b,c/) # / as delimiter
255 func(path/=|/usr/local/bin|) # | as delimiter for paths
256 func(text/=:hello:world:) # : as delimiter
257  
258 For scripting, control characters like BEL (C<\x07>) or US (C<\x1f>,
259 Unit Separator) can be used as delimiters to avoid conflicts with any
260 printable characters:
261  
262 $delim = "\x07"; # BEL
263 $delim = "\x1f"; # US (Unit Separator)
264 $arg = "data/=${delim}any/chars=here,${delim}";
265  
266 =back
267  
268 An anonymous subroutine can also be specified inline:
269  
270 % example --begin 'sub{ say "wahoo!!" }'
271  
272 The function is evaluated under C<use v5.14>, so features like C<say>
273 are available.
« EX/LabeledParam.pm ↑ Summary EX/Colormap.pm »