blib/lib/Params/Named.pm

filter: Statementstmt 100% 30 / 30 Branchbran 100% 10 / 10 Conditioncond 72.2% 13 / 18 MC/DCmcdc 30.0% 3 / 10 Subroutinesub 100% 6 / 6 Podpod 50.0% 1 / 2 totaltotal 82.8% 63 / 76 CC 13 SCAR 19.4
CC
13
Cov
91%
_set_param
10.5
MAPARGS
4.0
BEGIN
1.0
CRAP 7.0
↑ Summary
1 package Params::Named;
2  
3 3 $VERSION = '1.0.2';
4  
5 3 require Exporter;
6 3 @ISA = 'Exporter';
7 3 @EXPORT = 'MAPARGS';
8  
9 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 3 ▶use Carp qw/croak carp/;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 3 ▶use PadWalker 'var_name';
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 2 ▶sub VAR { return {qw/SCALAR $ ARRAY @ HASH % REF $/}->{ref $_[0]}.$_[1]; }
Subroutine VAR: called CC=1 SCAR=0.0
Pod undocumented
15  
16 14 ▶sub _set_param {
Subroutine _set_param: called CC=10 SCAR=23.5
17 14 my($p, $v, $n) = @_; # param, value, name
18 14 ▶ return $$p = $v
Branch: 1 branch
BranchTrueFalseTotal
if ref $p eq "SCALAR" and (ref $v || ref \$v) eq "SCALAR" or ref $v eq "REF" 11 3 14
Condition88%8/9
ref $p eq "SCALAR" and (ref $v || ref \$v) eq "SCALAR" or ref $v eq "REF"
l!l&&r!l&&!r
1013
ref $p eq "SCALAR" and (ref $v || ref \$v) eq "SCALAR"
!ll&&!rl&&r
2210
ref $v || ref \$v
l!l&&r!l&&!r
2100
MC/DC25%1/4
ref $p eq "SCALAR" and (ref $v || ref \$v) eq "SCALAR" or ref $v eq "REF"
ref $p eq "SCALAR" ref $v ref \$v ref $v eq "REF"
Truth table33%2/6
A and B || C or D
A= ref $p eq "SCALAR"B= ref $vC= ref \$vD= ref $v eq "REF"
ABCDresult
11XX1
101X1
0XX11
10011
0XX00
10000
19 if ref $p eq 'SCALAR'
20 && (ref $v || ref \$v) eq 'SCALAR' || (ref $v eq 'REF');
21 3 ▶ return @$p = @$v
Branch: 1 branch
BranchTrueFalseTotal
if ref $p eq "ARRAY" and ref $v eq "ARRAY" 1 2 3
Condition66%2/3
ref $p eq "ARRAY" and ref $v eq "ARRAY"
!ll&&!rl&&r
201
MC/DC50%1/2
ref $p eq "ARRAY" and ref $v eq "ARRAY"
ref $p eq "ARRAY" ref $v eq "ARRAY"
Truth table66%2/3
A and B
A= ref $p eq "ARRAY"B= ref $v eq "ARRAY"
ABresult
0X0
100
111
22 if ref $p eq 'ARRAY' && ref $v eq 'ARRAY';
23 2 ▶ return %$p = %$v
Branch: 1 branch
BranchTrueFalseTotal
if ref $p eq "HASH" and ref $v eq "HASH" 1 1 2
Condition66%2/3
ref $p eq "HASH" and ref $v eq "HASH"
!ll&&!rl&&r
101
MC/DC50%1/2
ref $p eq "HASH" and ref $v eq "HASH"
ref $p eq "HASH" ref $v eq "HASH"
Truth table66%2/3
A and B
A= ref $p eq "HASH"B= ref $v eq "HASH"
ABresult
0X0
100
111
24 if ref $p eq 'HASH' && ref $v eq 'HASH';
25  
26 1 ▶ croak sprintf "The parameter '%s' doesn't match argument type '%s'",
Condition33%1/3
ref $v || ref \$v
l!l&&r!l&&!r
100
MC/DC0%0/2
ref $v || ref \$v
ref $v ref \$v
Truth table33%1/3
A || B
A= ref $vB= ref \$v
ABresult
1X1
011
000
27 VAR($p,$n), ( ref $v || ref \$v );
28 }
29  
30 ## Map named arguments to variables of those names.
31 7 ▶sub MAPARGS {
Subroutine MAPARGS: called CC=4 SCAR=13.9
Pod documented
32 7 my %args = do { package DB; () = caller 1; @DB::args };
33 ## Map the lexicals of the caller to the caller's arguments.
34 my %vmap = map {
35 7 ▶ my $arg = ref $_ ? $_ : \$_;
Branch: 1 branch
BranchTrueFalseTotal
ref $_ ? : 9 6 15
36 15 my $prm = substr(var_name(1, $arg), 1);
37 15 ▶ exists $args{$prm}
Branch: 1 branch
BranchTrueFalseTotal
exists $args{$prm} ? : 14 1 15
38 ? ($prm => $arg)
39 1 : (() = carp "Parameter '${\VAR($arg,$prm)}' not mapped to an argument")
40 } @_;
41  
42 ## Now assign the caller's arguments to the caller's lexicals.
43 _set_param $vmap{$_} => $args{$_}, $_
44 7 for keys %vmap;
45  
46 6 return \%vmap;
47 }
48  
49 3 1;
50  
51 =pod
52  
53 =head1 NAME
54  
55 Params::Named - Map incoming arguments to parameters of the same name.
56  
57 =head1 SYNOPSIS
58  
59 use Params::Named;
60 use IO::All;
61  
62 sub storeurl {
63 my $self = shift;
64 MAPARGS \my($src, $dest);
65 return io($src) > io($dest);
66 }
67 $obj->storeurl(src => $url, dest => $fh);
68  
69 =head1 DESCRIPTION
70  
71 This module does just one thing - it maps named arguments to a subroutine's
72 lexical parameter variables or, more specifically, any lexical variables
73 passed into C<MAPARGS>. Named parameters are exactly the same as a flattened
74 hash in that they provide a list of C<< key => value >> pairs. So for each
75 key that matches a lexical variable passed to C<MAPARGS> the corresponding
76 value will be mapped to that variable. Here is a short example to demonstrate
77 C<MAPARGS> in action:
78  
79 use Params::Named;
80 sub mapittome {
81 MAPARGS \my($this, @that, %other);
82 print "This is: '$this'\n";
83 print "That is: ", join(', ', @that), "\n";
84 print "The other: ", join(', ',
85 map "$_ => $other{$_}", keys %other), "\n";
86 }
87  
88 mapittome this => 'a simple string',
89 that => [qw/a list of items/],
90 other => {qw/a hash containing pairs/};
91 ## Or if you've got a hash.
92 my %args = (
93 this => 'using a hash',
94 that => [qw/is very cool/],
95 other => {qw/is it not cool?/},
96 );
97 mapittome %args;
98  
99 The example above illustrates the mapping of C<mapittome>'s arguments to
100 its parameters. It will work on scalars, arrays and hashes, the 3 types
101 of lexical values.
102  
103 =head1 FUNCTIONS
104  
105 =over 4
106  
107 =item MAPARGS
108  
109 Given a list of variables map those variables to named arguments from the
110 caller's argument. Taking advantage of one of Perl's more under-utilized
111 features, passing in a list of references as created by applying the
112 reference operator to a list will allow the mapping of compound variables
113 (without the reference lexically declared arrays and hashes flatten to an
114 empty list). Argument types must match their corresponding parameter types
115 e.g C<< foo => \@things >> should map to a parameter declared as an array
116 e.g C<MAPARGS \my(@foo)>.
117  
118 The arguments passed to C<MAPARGS> don't need to be referenced if they are
119 simple scalars, but do need to be referenced if either an array or hash is
120 used.
121  
122 =back
123  
124 =head1 EXPORTS
125  
126 C<MAPARGS>
127  
128 =head1 DIAGNOSTICS
129  
130 =over 4
131  
132 =item C<Parameter '%s' not mapped to an argument>
133  
134 This warning is issued because a parameter couldn't be mapped to an argument
135 i.e if C<< foo1 => 'bar' >> is accidentally passed to subroutine who's
136 parameter is C<$fool>.
137  
138 =item C<The parameter '%s' doesn't match argument type '%s'>
139  
140 A given parameter doesn't match it's corresponding argument's type e.g
141  
142 sub it'llbreak { MAPARGS \my($foo, @bar); ... }
143 ## This will croak() because @bar's argument isn't an array reference.
144 it'llbreak foo => 'this', bar => 'that';
145  
146 So either the parameter or the argument needs to be updated to reflect
147 the desired behaviour.
148  
149 =back
150  
151 =head1 SEE. ALSO
152  
153 L<Sub::Parameters>, L<Sub::Signatures>, L<Params::Smart>
154  
155 =head1 THANKS
156  
157 Robin Houston for bug spotting, code refactoring, idea bouncing and releasing
158 a new version of L<PadWalker> (is there anything he can't do?).
159
160 =head1 AUTHOR
161  
162 Dan Brook C<< <cpan@broquaint.com> >>
163  
164 =head1 COPYRIGHT
165  
166 Copyright (c) 2005, Dan Brook. All Rights Reserved. This module is free
167 software. It may be used, redistributed and/or modified under the same
168 terms as Perl itself.
169  
170 =cut
↑ Summary