Parse::Method::Signatures(3pm)

1Parse::Method::SignaturUesse(r3)Contributed Perl DocumenPtaartsieo:n:Method::Signatures(3)
2
3
4

NAME

6       Parse::Method::Signatures - Perl6 like method signature parser
7

DESCRIPTION

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

TODO

13       ·   Document the parameter return types.
14
15       ·   Probably lots of other things
16

METHODS

18       There are only two public methods to this module, both of which should
19       be called as class methods. Both methods accept  either a single (non-
20       ref) scalar as the value for the "input" attribute, or normal new style
21       arguments (hash or hash-ref).
22
23   signature
24        my $sig = Parse::Method::Signatures->signature( '(Str $foo)' )
25
26       Attempts to parse the (bracketed) method signature. Returns a value or
27       croaks on error.
28
29   param
30         my $param = Parse::Method::Signatures->param( 'Str $foo where { length($_) < 10 }')
31
32       Attempts to parse the specification for a single parameter. Returns
33       value or croaks on error.
34

ATTRIBUTES

36       All the attributes on this class are read-only.
37
38   input
39       Type: Str
40
41       The string to parse.
42
43   offset
44       Type: Int
45
46       Offset into "input" at which to start parsing. Useful for using with
47       Devel::Declare linestring
48
49   signature_class
50       Default: Parse::Method::Signatures::Sig
51
52       Type: Str (loaded on demand class name)
53
54   param_class
55       Default: Parse::Method::Signatures::Param
56
57       Type: Str (loaded on demand class name)
58
59   type_constraint_class
60       Default: Parse::Method::Signatures::TypeConstraint
61
62       Type: Str (loaded on demand class name)
63
64       Class that is used to turn the parsed type constraint into an actual
65       Moose::Meta::TypeConstraint object.
66
67   from_namespace
68       Type: ClassName
69
70       Let this module know which package it is parsing signatures form. This
71       is entirely optional, and the only effect is has is on parsing type
72       constraints.
73
74       If this attribute is set it is passed to "type_constraint_class" which
75       can use it to introspect the package (commonly for MooseX::Types
76       exported types). See "find_registered_constraint" in
77       Parse::Method::Signature::TypeConstraints for more details.
78
79   type_constraint_callback
80       Type: CodeRef
81
82       Passed to the constructor of "type_constraint_class". Default
83       implementation of this callback asks Moose for a type constrain
84       matching the name passed in.  If you have more complex requirements,
85       such as parsing types created by MooseX::Types then you will want a
86       callback similar to this:
87
88        # my $target_package defined elsewhere.
89        my $tc_cb = sub {
90          my ($pms_tc, $name) = @_;
91          my $code = $target_package->can($name);
92          $code ? eval { $code->() }
93                : $pms_tc->find_registered_constraint($name);
94        }
95
96       Note that the above example is better provided by providing the
97       "from_namespace" attribute.
98

CAVEATS

100       Like Perl6::Signature, the parsing of certain constructs is currently
101       only a 'best effort' - specifically default values and where code
102       blocks might not successfully for certain complex cases.
103       Patches/Failing tests welcome.
104
105       Additionally, default value specifications are not evaluated which
106       means that no such lexical or similar errors will not be produced by
107       this module.  Constant folding will also not be performed.
108
109       There are certain constructs that are simply too much hassle to avoid
110       when the work around is simple. Currently the only cases that are known
111       to parse wrong are when using anonymous variables (i.e. just sigils) in
112       unpacked arrays. Take the following example:
113
114        method foo (ArrayRef [$, $], $some_value_we_care_about) {
115
116       In this case the $] is treated as one of perl's magic variables
117       (specifically, the patch level of the Perl interpreter) rather than a
118       "$" followed by a "]" as was almost certainly intended. The work around
119       for this is simple: introduce a space between the characters:
120
121        method foo (ArrayRef [ $, $ ], $some_value_we_care_about) {
122
123       The same applies
124

AUTHOR

126       Ash Berlin <ash@cpan.org>.
127
128       Thanks to Florian Ragwitz <rafl@debian.org>.
129
130       Many thanks to Piers Cawley to showing me the way to refactor my
131       spaghetti code into something more manageable.
132

LICENSE

140       Licensed under the same terms as Perl itself.
141
142       This distribution copyright 2008-2009, Ash Berlin <ash@cpan.org>
143
144
145
146perl v5.30.0                      2019-07-26      Parse::Method::Signatures(3)