| 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
Condition88%8/9
ref $p eq "SCALAR" and (ref $v || ref \$v) eq "SCALAR" or ref $v eq "REF"
ref $p eq "SCALAR" and (ref $v || ref \$v) eq "SCALAR"
ref $v || ref \$v
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"
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
Condition66%2/3
ref $p eq "ARRAY" and ref $v eq "ARRAY"
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"
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 22 | if ref $p eq 'ARRAY' && ref $v eq 'ARRAY'; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 23 | 2 | ▶ | return %$p = %$v | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
ref $p eq "HASH" and ref $v eq "HASH"
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"
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
MC/DC0%0/2
ref $v || ref \$v
ref $v
ref \$v
Truth table33%1/3
A || B
A= ref $vB= ref \$v
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 36 | 15 | my $prm = substr(var_name(1, $arg), 1); | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 37 | 15 | ▶ | exists $args{$prm} | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||