NAME
    Parse::Method::Signatures - Perl6 like method signature parser

DESCRIPTION
    Inspired by Perl6::Signature but streamlined to just support the subset
    deemed useful for TryCatch and MooseX::Method::Signatures.

TODO
    *   Document the parameter return types.

    *   Probably lots of other things

METHODS
    There are only two public methods to this module, both of which should
    be called as class methods. Both methods accept either a single
    (non-ref) scalar as the value for the "input" attribute, or normal new
    style arguments (hash or hash-ref).

  signature
     my $sig = Parse::Method::Signatures->signature( '(Str $foo)' )

    Attempts to parse the (bracketed) method signature. Returns a value or
    croaks on error.

  param
      my $param = Parse::Method::Signatures->param( 'Str $foo where { length($_) < 10 }')

    Attempts to parse the specification for a single parameter. Returns
    value or croaks on error.

ATTRIBUTES
    All the attributes on this class are read-only.

  input
    Type: Str

    The string to parse.

  offset
    Type: Int

    Offset into "input" at which to start parsing. Useful for using with
    Devel::Declare linestring

  signature_class
    Default: Parse::Method::Signatures::Sig

    Type: Str (loaded on demand class name)

  param_class
    Default: Parse::Method::Signatures::Param

    Type: Str (loaded on demand class name)

  type_constraint_class
    Default: Parse::Method::Signatures::TypeConstraint

    Type: Str (loaded on demand class name)

    Class that is used to turn the parsed type constraint into an actual
    Moose::Meta::TypeConstraint object.

  from_namespace
    Type: ClassName

    Let this module know which package it is parsing signatures form. This
    is entirely optional, and the only effect is has is on parsing type
    constraints.

    If this attribute is set it is passed to "type_constraint_class" which
    can use it to introspect the package (commmonly for MooseX::Types
    exported types). See "find_registered_constraint" in
    Parse::Method::Signature::TypeConstraints for more details.

  type_constraint_callback
    Type: CodeRef

    Passed to the constructor of "type_constraint_class". Default
    implementation of this callback asks Moose for a type constrain matching
    the name passed in. If you have more complex requirements, such as
    parsing types created by MooseX::Types then you will want a callback
    similar to this:

     # my $target_package defined elsewhere.
     my $tc_cb = sub {
       my ($pms_tc, $name) = @_;
       my $code = $target_package->can($name);
       $code ? eval { $code->() } 
             : $pms_tc->find_registered_constraint($name);
     }

    Note that the above example is better provided by providing the
    "from_namespace" attribute.

CAVEATS
    Like Perl6::Signature, the parsing of certain constructs is currently
    only a 'best effort' - specifically default values and where code blocks
    might not successfully for certain complex cases. Patches/Failing tests
    welcome.

    Additionally, default value specifications are not evaluated which means
    that no such lexical or similar errors will not be produced by this
    module. Constant folding will also not be performed.

    There are certain constructs that are simply too much hassle to avoid
    when the work around is simple. Currently the only cases that are known
    to parse wrong are when using anonymous variables (i.e. just sigils) in
    unpacked arrays. Take the following example:

     method foo (ArrayRef [$, $], $some_value_we_care_about) {

    In this case the $] is treated as one of perl's magic variables
    (specifically, the patch level of the Perl interpreter) rather than a
    "$" followed by a "]" as was almost certainly intended. The work around
    for this is simple: introduce a space between the charcters:

     method foo (ArrayRef [ $, $ ], $some_value_we_care_about) {

    The same applies

AUTHOR
    Ash Berlin <ash@cpan.org>.

    Thanks to Florian Ragwitz <rafl@debian.org>.

    Many thanks to Piers Cawley to showing me the way to refactor my
    spaghetti code into something more manageable.

SEE ALSO
    Devel::Declare which is used by most modules that use this (currently by
    all modules known to the author.)

    <http://github.com/ashb/trycatch/tree>.

LICENSE
    Licensed under the same terms as Perl itself.

    This distribution copyright 2008-2009, Ash Berlin <ash@cpan.org>

