From: Lukas Mai <l.mai@web.de>
Date: Wed, 14 Nov 2012 13:56:34 +0000 (+0100)
Subject: document Moose types
X-Git-Tag: v1.00_02~6
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2FFunction-Parameters.git;a=commitdiff_plain;h=0175ff9a8975c8f41006fe3cb4ccd5a44b4758dc

document Moose types
---

diff --git a/lib/Function/Parameters.pm b/lib/Function/Parameters.pm
index 4c040d1..916bc50 100644
--- a/lib/Function/Parameters.pm
+++ b/lib/Function/Parameters.pm
@@ -659,6 +659,44 @@ affects the file that is currently being compiled.
    # or Function::Parameters->import(@custom_import_args);
  }
 
+=head2 Experimental feature: Types
+
+An experimental feature is now available: You can annotate parameters with
+L<Moose types|Moose::Manual::Types>. That is, before each parameter you can put
+a type specification consisting of identifiers (C<Foo>), unions (C<... | ...>),
+and parametric types (C<...[...]>). Example:
+
+  fun foo(Int $n, ArrayRef[String | CodeRef] $cb) { ... }
+
+If you do this, L<Moose> will be loaded automatically (if that hasn't happened
+yet). These specifications are parsed and validated using
+L<C<Moose::Util::TypeConstraints::find_or_parse_type_constraint>|Moose::Util::TypeConstraints/find_or_parse_type_constraint>.
+
+If you are in "lax" mode, nothing further happens and the types are ignored. If
+you are in "strict" mode, C<Function::Parameters> generates code to make sure
+any values passed in conform to the type (via
+L<< C<< $constraint->check($value) >>|Moose::Meta::TypeConstraint/$constraint->check($value) >>.
+
+In addition, these type constraints are inspectable through the
+L<Function::Parameters::Info> object returned by
+L<C<Function::Parameters::info>|/Introspection>.
+
+=head2 Experimental experimental feature: Type expressions
+
+An even more experimental feature is the ability to specify arbitrary
+expressions as types. The syntax for this is like the literal types described
+above, but with an expression wrapped in parentheses (C<( EXPR )>). Example:
+
+  fun foo(('Int') $n, ($othertype) $x) { ... }
+
+Every type expression must return either a string (which is resolved as for
+literal types), or a L<type constraint object|Moose::Meta::TypeConstraint>
+(providing C<check> and C<get_message> methods).
+
+Note that these expressions are evaluated (once) at parse time (similar to
+C<BEGIN> blocks), so make sure that any variables you use are set and any
+functions you call are defined at parse time.
+
 =head2 How it works
 
 The module is actually written in L<C|perlxs> and uses
@@ -676,6 +714,39 @@ generated code corresponds to:
   # ... turns into ...
   sub bar :method { my $self = shift; my ($x, $y, @z) = @_; sub bar; ... }
 
+=head1 SUPPORT AND DOCUMENTATION
+
+After installing, you can find documentation for this module with the
+perldoc command.
+
+    perldoc Function::Parameters
+
+You can also look for information at:
+
+=over
+
+=item MetaCPAN
+
+L<https://metacpan.org/module/Function%3A%3AParameters>
+
+=item RT, CPAN's request tracker
+
+L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Function-Parameters>
+
+=item AnnoCPAN, Annotated CPAN documentation
+
+L<http://annocpan.org/dist/Function-Parameters>
+
+=item CPAN Ratings
+
+L<http://cpanratings.perl.org/d/Function-Parameters>
+
+=item Search CPAN
+
+L<http://search.cpan.org/dist/Function-Parameters/>
+
+=back
+
 =head1 SEE ALSO
 
 L<Function::Parameters::Info>
diff --git a/lib/Function/Parameters/Info.pm b/lib/Function/Parameters/Info.pm
index 4b9e4b4..6755fee 100644
--- a/lib/Function/Parameters/Info.pm
+++ b/lib/Function/Parameters/Info.pm
@@ -135,6 +135,18 @@ 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>