File Coverage

blib/lib/Function/Parameters/Info.pm
Criterion Covered Total %
statement 127 127 100.0
branch 48 90 53.3
condition 7 12 58.3
subroutine 21 21 100.0
pod 9 12 75.0
total 212 262 80.9


line stmt bran cond sub pod time code
1             package Function::Parameters::Info 2.002006;
2              
3 4     4   54 use v5.14.0;
  4         32  
4 4     4   22 use warnings;
  4         6  
  4         347  
5              
6 4     4   25 use Function::Parameters;
  4         7  
  4         30  
7 4     4   29 use Carp ();
  4         9  
  4         466  
8              
9             {
10             package Function::Parameters::Param;
11              
12             use overload
13 40 50   40   8995 fallback => 1,
14 4         49 '""' => method (@) { $self->{name} },
  40         64  
  40         56  
  40         805  
15 4     4   27 ;
  4         9  
16              
17 42 50 33 42   105 method new($class: :$name, :$type) {
  42 50       173  
  42 50       67  
  42 50       121  
  42 50       107  
  42         138  
  42         94  
  42         52  
18 42         225 bless { @_ }, $class
19             }
20              
21 8 50   8   1354 method name() { $self->{name} }
  8 50       22  
  8         14  
  8         13  
  8         103  
22 8 50   8   30 method type() { $self->{type} }
  8 50       23  
  8         14  
  8         12  
  8         36  
23             }
24              
25             method new($class:
26             :$keyword,
27             :$nshift,
28             :$_positional_required,
29             :$_positional_optional,
30             :$_named_required,
31             :$_named_optional,
32             :$slurpy,
33 16 50 33 16 0 46 ) {
  16 50       81  
  16 50       26  
  16 50       84  
  16 50       61  
  16 50       42  
  16 50       43  
  16 50       52  
  16 50       43  
  16 50       40  
  16         37  
  16         43  
  16         22  
34 16         115 bless {@_}, $class
35             }
36              
37 11 50   11 0 82 method keyword() { $self->{keyword} }
  11 50       28  
  11         18  
  11         17  
  11         54  
38 55 50   55 0 114 method nshift () { $self->{nshift} }
  55 50       95  
  55         69  
  55         65  
  55         113  
39 21 50   21 1 59 method slurpy () { $self->{slurpy} }
  21 50       44  
  21         33  
  21         29  
  21         96  
40 22 50   22 1 67 method positional_optional() { @{$self->{_positional_optional}} }
  22 50       50  
  22         34  
  22         27  
  22         31  
  22         101  
41 38 50   38 1 96 method named_required () { @{$self->{_named_required}} }
  38 50       83  
  38         62  
  38         51  
  38         45  
  38         207  
42 22 50   22 1 74 method named_optional () { @{$self->{_named_optional}} }
  22 50       49  
  22         34  
  22         30  
  22         31  
  22         94  
43              
44 22 50   22 1 73 method positional_required() {
  22 50       49  
  22         32  
  22         25  
45 22         41 my @p = @{$self->{_positional_required}};
  22         59  
46 22         63 splice @p, 0, $self->nshift;
47             @p
48 22         114 }
49              
50 12 50   12 1 52 method args_min() {
  12 50       34  
  12         24  
  12         16  
51 12         20 my $r = 0;
52 12         18 $r += @{$self->{_positional_required}};
  12         28  
53 12         49 $r += $self->named_required * 2;
54 12         45 $r
55             }
56              
57 12 50   12 1 54 method args_max() {
  12 50       34  
  12         23  
  12         17  
58 12 100 100     32 return 0 + 'Inf' if defined $self->slurpy || $self->named_required || $self->named_optional;
      66        
59 4         9 my $r = 0;
60 4         8 $r += @{$self->{_positional_required}};
  4         9  
61 4         11 $r += $self->positional_optional;
62 4         20 $r
63             }
64              
65 12 50   12 1 289 method invocant() {
  12 50       39  
  12         18  
  12         17  
66 12         32 my $nshift = $self->nshift;
67             return undef
68 12 100       50 if $nshift == 0;
69 6 100       26 return $self->{_positional_required}[0]
70             if $nshift == 1;
71 3         497 Carp::croak "Can't return a single invocant; this function has $nshift";
72             }
73              
74 21 50   21 1 84 method invocants() {
  21 50       54  
  21         33  
  21         29  
75 21         28 my @p = @{$self->{_positional_required}};
  21         52  
76 21         60 splice @p, $self->nshift;
77             @p
78 21         98 }
79              
80             'ok'
81              
82             __END__
83              
84             =encoding UTF-8
85              
86             =head1 NAME
87              
88             Function::Parameters::Info - Information about parameter lists
89              
90             =head1 SYNOPSIS
91              
92             use Function::Parameters;
93              
94             fun foo($x, $y, :$hello, :$world = undef) {}
95              
96             my $info = Function::Parameters::info \&foo;
97             my @p0 = $info->invocants; # ()
98             my @p1 = $info->positional_required; # ('$x', '$y')
99             my @p2 = $info->positional_optional; # ()
100             my @p3 = $info->named_required; # ('$hello')
101             my @p4 = $info->named_optional; # ('$world')
102             my $p5 = $info->slurpy; # undef
103             my $min = $info->args_min; # 4
104             my $max = $info->args_max; # inf
105              
106             my @invocants = Function::Parameters::info(method () { 42 })->invocants;
107             # ('$self')
108              
109             my $slurpy = Function::Parameters::info(fun (@) {})->slurpy; # '@'
110              
111             =head1 DESCRIPTION
112              
113             L<C<Function::Parameters::info>|Function::Parameters/Introspection> returns
114             objects of this class to describe parameter lists of functions. See below for
115             L</Parameter Objects>. The following methods are available:
116              
117             =head3 $info->invocants
118              
119             Returns a list of parameter objects for the variables into which initial
120             arguments are L<C<shift>|perlfunc/shift ARRAY>ed automatically (or a count in
121             scalar context). This will usually return C<()> for normal functions and
122             C<('$self')> for methods.
123              
124             =head3 $info->positional_required
125              
126             Returns a list of parameter objects for the required positional parameters (or
127             a count in scalar context).
128              
129             =head3 $info->positional_optional
130              
131             Returns a list of parameter objects for the optional positional parameters (or
132             a count in scalar context).
133              
134             =head3 $info->named_required
135              
136             Returns a list of parameter objects for the required named parameters (or a
137             count in scalar context).
138              
139             =head3 $info->named_optional
140              
141             Returns a list of parameter objects for the optional named parameters (or a
142             count in scalar context).
143              
144             =head3 $info->slurpy
145              
146             Returns a parameter object for the final array or hash that gobbles up all remaining
147             arguments, or C<undef> if no such thing exists.
148              
149             =head3 $info->args_min
150              
151             Returns the minimum number of arguments this function requires. This is
152             computed as follows: Invocants and required positional parameters count 1 each.
153             Optional parameters don't count. Required named parameters count 2 each (key +
154             value). Slurpy parameters don't count either because they accept empty lists.
155              
156             =head3 $info->args_max
157              
158             Returns the maximum number of arguments this function accepts. This is computed
159             as follows: If there are any named or slurpy parameters, the result is C<Inf>.
160             Otherwise the result is the number of all invocants and positional parameters.
161              
162             =head3 $info->invocant
163              
164             Similar to L</$info-E<gt>invocants> above: Returns C<undef> if the number of
165             invocants is 0, a parameter object for the invocant if there is exactly 1, and
166             throws an exception otherwise.
167              
168             =head3 Parameter Objects
169              
170             Many of the methods described above return parameter objects. These objects
171             have two methods: C<name>, which returns the name of the parameter (as a plain
172             string), and C<type>, which returns the corresponding type constraint object
173             (or undef if there was no type specified).
174              
175             This should be invisible if you don't care about types because the objects also
176             L<overload|overload> stringification to call C<name>. That is, if you treat
177             parameter objects like strings, they behave like strings (i.e. their names).
178              
179             =head1 SEE ALSO
180              
181             L<Function::Parameters>
182              
183             =head1 AUTHOR
184              
185             Lukas Mai, C<< <l.mai at web.de> >>
186              
187             =head1 COPYRIGHT & LICENSE
188              
189             Copyright 2013, 2016 Lukas Mai.
190              
191             This program is free software; you can redistribute it and/or modify it
192             under the terms of either: the GNU General Public License as published
193             by the Free Software Foundation; or the Artistic License.
194              
195             See http://dev.perl.org/licenses/ for more information.
196              
197             =cut