document Moose types

[p5sagit/Function-Parameters.git] / lib / Function / Parameters / Info.pm

diff --git a/lib/Function/Parameters/Info.pm b/lib/Function/Parameters/Info.pm
index 8604eeb..6755fee 100644 (file)
--- a/lib/Function/Parameters/Info.pm
+++ b/lib/Function/Parameters/Info.pm
@@ -8,6 +8,18 @@ use Moo;
 
 our $VERSION = '0.01';
 
+{
+       package Function::Parameters::Param;
+
+       use Moo;
+       use overload
+               fallback => 1,
+               '""' => sub { $_[0]->name },
+       ;
+
+       has $_ => (is => 'ro') for qw(name type);
+}
+
 my @pn_ro = glob '{positional,named}_{required,optional}';
 
 for my $attr (qw[keyword invocant slurpy], map "_$_", @pn_ro) {
@@ -75,33 +87,33 @@ L<C<Function::Parameters::info>|Function::Parameters/Introspection> returns
 objects of this class to describe parameter lists of functions. The following
 methods are available:
 
-=head2 C<< $info->invocant >>
+=head2 $info->invocant
 
 Returns the name of the variable into which the first argument is
-L<C<shift>|perlfunc/shift>ed into automatically, or C<undef> if no such thing
+L<C<shift>|perlfunc/shift>ed automatically, or C<undef> if no such thing
 exists. This will usually return C<'$self'> for methods.
 
-=head2 C<< $info->positional_required >>
+=head2 $info->positional_required
 
 Returns a list of the names of the required positional parameters (or a count
 in scalar context).
 
-=head2 C<< $info->positional_optional >>
+=head2 $info->positional_optional
 
 Returns a list of the names of the optional positional parameters (or a count
 in scalar context).
 
-=head2 C<< $info->named_required >>
+=head2 $info->named_required
 
 Returns a list of the names of the required named parameters (or a count
 in scalar context).
 
-=head2 C<< $info->named_optional >>
+=head2 $info->named_optional
 
 Returns a list of the names of the optional named parameters (or a count
 in scalar context).
 
-=head2 C<< $info->slurpy >>
+=head2 $info->slurpy
 
 Returns the name of the final array or hash that gobbles up all remaining
 arguments, or C<undef> if no such thing exists.
@@ -110,19 +122,31 @@ As a special case, functions defined without an explicit parameter list (i.e.
 without C<( )>) will return C<'@_'> here because they accept any number of
 arguments.
 
-=head2 C<< $info->args_min >>
+=head2 $info->args_min
 
 Returns the minimum number of arguments this function requires. This is
 computed as follows: Invocant and required positional parameters count 1 each.
 Optional parameters don't count. Required named parameters count 2 each (key +
 value). Slurpy parameters don't count either because they accept empty lists.
 
-=head2 C<< $info->args_max >>
+=head2 $info->args_max
 
 Returns the maximum number of arguments this function accepts. This is computed
 as follows: If there is any named or slurpy parameter, the result is C<Inf>.
 Otherwise the result is the sum of all invocant and positional parameters.
 
+=head2 Experimental feature: Types
+
+All the methods described above actually return parameter objects wherever the
+description says "name". These objects have two methods: C<name>, which
+returns the name of the parameter (as a plain string), and C<type>, which
+returns the corresponding type constraint object (or undef if there was no type
+specified).
+
+This should be invisible if you don't use types because the objects also
+L<overload|overload> stringification to call C<name>. That is, if you treat
+parameter objects like strings, they behave like strings (i.e. their names).
+
 =head1 SEE ALSO
 
 L<Function::Parameters>