lib/Function/Parameters/Info.pm

   1 package Function::Parameters::Info;
   2
   3 use v5.14.0;
   4
   5 use warnings;
   6
   7 use Moo;
   8
   9 our $VERSION = '0.01';
  10
  11 my @pn_ro = glob '{positional,named}_{required,optional}';
  12
  13 for my $attr (qw[keyword invocant slurpy], map "_$_", @pn_ro) {
  14         has $attr => (
  15                 is => 'ro',
  16         );
  17 }
  18
  19 for my $gen (join "\n", map "sub $_ { \@{\$_[0]->_$_} }", @pn_ro) {
  20         eval "$gen\n1" or die $@;
  21 }
  22
  23 sub args_min {
  24         my $self = shift;
  25         my $r = 0;
  26         $r++ if defined $self->invocant;
  27         $r += $self->positional_required;
  28         $r += $self->named_required * 2;
  29         $r
  30 }
  31
  32 sub args_max {
  33         my $self = shift;
  34         return 0 + 'Inf' if defined $self->slurpy || $self->named_required || $self->named_optional;
  35         my $r = 0;
  36         $r++ if defined $self->invocant;
  37         $r += $self->positional_required;
  38         $r += $self->positional_optional;
  39         $r
  40 }
  41
  42 'ok'
  43
  44 __END__
  45
  46 =encoding UTF-8
  47
  48 =head1 NAME
  49
  50 Function::Parameters::Info - Information about parameter lists
  51
  52 =head1 SYNOPSIS
  53
  54   use Function::Parameters;
  55
  56   fun foo($x, $y, :$hello, :$world = undef) {}
  57
  58   my $info = Function::Parameters::info \&foo;
  59   my $p0 = $info->invocant;             # undef
  60   my @p1 = $info->positional_required;  # ('$x', '$y')
  61   my @p2 = $info->positional_optional;  # ()
  62   my @p3 = $info->named_required;       # ('$hello')
  63   my @p4 = $info->named_optional;       # ('$world')
  64   my $p5 = $info->slurpy;               # undef
  65   my $min = $info->args_min;  # 4
  66   my $max = $info->args_max;  # inf
  67
  68   my $invocant = Function::Parameters::info(method () { 42 })->invocant;  # '$self'
  69
  70   my $slurpy = Function::Parameters::info(fun {})->slurpy;  # '@_'
  71
  72 =head1 DESCRIPTION
  73
  74 L<C<Function::Parameters::info>|Function::Parameters/Introspection> returns
  75 objects of this class to describe parameter lists of functions. The following
  76 methods are available:
  77
  78 =head2 C<< $info->invocant >>
  79
  80 Returns the name of the variable into which the first argument is
  81 L<C<shift>|perlfunc/shift>ed into automatically, or C<undef> if no such thing
  82 exists. This will usually return C<'$self'> for methods.
  83
  84 =head2 C<< $info->positional_required >>
  85
  86 Returns a list of the names of the required positional parameters (or a count
  87 in scalar context).
  88
  89 =head2 C<< $info->positional_optional >>
  90
  91 Returns a list of the names of the optional positional parameters (or a count
  92 in scalar context).
  93
  94 =head2 C<< $info->named_required >>
  95
  96 Returns a list of the names of the required named parameters (or a count
  97 in scalar context).
  98
  99 =head2 C<< $info->named_optional >>
 100
 101 Returns a list of the names of the optional named parameters (or a count
 102 in scalar context).
 103
 104 =head2 C<< $info->slurpy >>
 105
 106 Returns the name of the final array or hash that gobbles up all remaining
 107 arguments, or C<undef> if no such thing exists.
 108
 109 As a special case, functions defined without an explicit parameter list (i.e.
 110 without C<( )>) will return C<'@_'> here because they accept any number of
 111 arguments.
 112
 113 =head2 C<< $info->args_min >>
 114
 115 Returns the minimum number of arguments this function requires. This is
 116 computed as follows: Invocant and required positional parameters count 1 each.
 117 Optional parameters don't count. Required named parameters count 2 each (key +
 118 value). Slurpy parameters don't count either because they accept empty lists.
 119
 120 =head2 C<< $info->args_max >>
 121
 122 Returns the maximum number of arguments this function accepts. This is computed
 123 as follows: If there is any named or slurpy parameter, the result is C<Inf>.
 124 Otherwise the result is the sum of all invocant and positional parameters.
 125
 126 =head1 SEE ALSO
 127
 128 L<Function::Parameters>
 129
 130 =head1 AUTHOR
 131
 132 Lukas Mai, C<< <l.mai at web.de> >>
 133
 134 =head1 COPYRIGHT & LICENSE
 135
 136 Copyright 2012 Lukas Mai.
 137
 138 This program is free software; you can redistribute it and/or modify it
 139 under the terms of either: the GNU General Public License as published
 140 by the Free Software Foundation; or the Artistic License.
 141
 142 See http://dev.perl.org/licenses/ for more information.
 143
 144 =cut