MooseX::Method::Signatures(3pm)

1MooseX::Method::SignatuUrseesr(3C)ontributed Perl DocumeMnotoasteiXo:n:Method::Signatures(3)
2
3
4

NAME

6       MooseX::Method::Signatures - Method declarations with type constraints
7       and no source filter
8

SYNOPSIS

10           package Foo;
11
12           use Moose;
13           use MooseX::Method::Signatures;
14
15           method morning (Str $name) {
16               $self->say("Good morning ${name}!");
17           }
18
19           method hello (Str :$who, Int :$age where { $_ > 0 }) {
20               $self->say("Hello ${who}, I am ${age} years old!");
21           }
22
23           method greet (Str $name, Bool :$excited = 0) {
24               if ($excited) {
25                   $self->say("GREETINGS ${name}!");
26               }
27               else {
28                   $self->say("Hi ${name}!");
29               }
30           }
31
32           $foo->morning('Resi');                          # This works.
33
34           $foo->hello(who => 'world', age => 42);         # This too.
35
36           $foo->greet('Resi', excited => 1);              # And this as well.
37
38           $foo->hello(who => 'world', age => 'fortytwo'); # This doesn't.
39
40           $foo->hello(who => 'world', age => -23);        # This neither.
41
42           $foo->morning;                                  # Won't work.
43
44           $foo->greet;                                    # Will fail.
45

DESCRIPTION

47       Provides a proper method keyword, like "sub" but specifically for
48       making methods and validating their arguments against Moose type
49       constraints.
50

SIGNATURE SYNTAX

52       The signature syntax is heavily based on Perl 6. However not the full
53       Perl 6 signature syntax is supported yet and some of it never will be.
54
55   Type Constraints
56           method foo (             $affe) # no type checking
57           method bar (Animal       $affe) # $affe->isa('Animal')
58           method baz (Animal|Human $affe) # $affe->isa('Animal') || $affe->isa('Human')
59
60   Positional vs. Named
61           method foo ( $a,  $b,  $c) # positional
62           method bar (:$a, :$b, :$c) # named
63           method baz ( $a,  $b, :$c) # combined
64
65   Required vs. Optional
66           method foo ($a , $b!, :$c!, :$d!) # required
67           method bar ($a?, $b?, :$c , :$d?) # optional
68
69   Defaults
70           method foo ($a = 42) # defaults to 42
71
72   Constraints
73           method foo ($foo where { $_ % 2 == 0 }) # only even
74
75   Invocant
76           method foo (        $moo) # invocant is called $self and is required
77           method bar ($self:  $moo) # same, but explicit
78           method baz ($class: $moo) # invocant is called $class
79
80   Labels
81           method foo (:     $affe ) # called as $obj->foo(affe => $value)
82           method bar (:apan($affe)) # called as $obj->foo(apan => $value)
83
84   Traits
85           method foo (Affe $bar does trait)
86           method foo (Affe $bar is trait)
87
88       The only currently supported trait is "coerce", which will attempt to
89       coerce the value provided if it doesn't satisfy the requirements of the
90       type constraint.
91
92   Placeholders
93           method foo ($bar, $, $baz)
94
95       Sometimes you don't care about some params you're being called with.
96       Just put the bare sigil instead of a full variable name into the
97       signature to avoid an extra lexical variable to be created.
98
99   Complex Example
100           method foo ( SomeClass $thing where { $_->can('stuff') }:
101                        Str  $bar  = "apan",
102                        Int :$baz! = 42 where { $_ % 2 == 0 } where { $_ > 10 } )
103
104           # the invocant is called $thing, must be an instance of SomeClass and
105                  has to implement a 'stuff' method
106           # $bar is positional, required, must be a string and defaults to "apan"
107           # $baz is named, required, must be an integer, defaults to 42 and needs
108           #      to be even and greater than 10
109

BUGS, CAVEATS AND NOTES

111       This module is as stable now, but this is not to say that it is
112       entirely bug free. If you notice any odd behaviour (messages not being
113       as good as they could for example) then please raise a bug.
114
115   Fancy signatures
116       Parse::Method::Signatures is used to parse the signatures. However,
117       some signatures that can be parsed by it aren't supported by this
118       module (yet).
119
120   No source filter
121       While this module does rely on the hairy black magic of Devel::Declare
122       it does not depend on a source filter. As such, it doesn't try to parse
123       and rewrite your source code and there should be no weird side effects.
124
125       Devel::Declare only effects compilation. After that, it's a normal
126       subroutine.  As such, for all that hairy magic, this module is
127       surprisingly stable.
128
129   What about regular subroutines?
130       Devel::Declare cannot yet change the way "sub" behaves. However, the
131       signatures module can. Right now it only provides very basic
132       signatures, but it's extendable enough that plugging
133       MooseX::Method::Signatures signatures into that should be quite
134       possible.
135
136   What about the return value?
137       Type constraints for return values can be declared using
138
139         method foo (Int $x, Str $y) returns (Bool) { ... }
140
141       however, this feature only works with scalar return values and is still
142       considered to be experimental.
143
144   Interaction with Moose::Role
145       Methods not seen by a role's "requires"
146
147       Because the processing of the MooseX::Method::Signatures "method" and
148       the Moose "with" keywords are both done at runtime, it can happen that
149       a role will require a method before it is declared (which will cause
150       Moose to complain very loudly and abort the program).
151
152       For example, the following will not work:
153
154           # in file Canine.pm
155
156           package Canine;
157
158           use Moose;
159           use MooseX::Method::Signatures;
160
161           with 'Watchdog';
162
163           method bark { print "Woof!\n"; }
164
165           1;
166
167
168           # in file Watchdog.pm
169
170           package Watchdog;
171
172           use Moose::Role;
173
174           requires 'bark';  # will assert! evaluated before 'method' is processed
175
176           sub warn_intruder {
177               my $self = shift;
178               my $intruder = shift;
179
180               $self->bark until $intruder->gone;
181           }
182
183           1;
184
185       A workaround for this problem is to use "with" only after the methods
186       have been defined.  To take our previous example, Canine could be
187       reworked thus:
188
189           package Canine;
190
191           use Moose;
192           use MooseX::Method::Signatures;
193
194           method bark { print "Woof!\n"; }
195
196           with 'Watchdog';
197
198           1;
199
200       A better solution is to use MooseX::Declare instead of plain
201       MooseX::Method::Signatures. It defers application of roles until the
202       end of the class definition. With it, our example would becomes:
203
204           # in file Canine.pm
205
206           use MooseX::Declare;
207
208           class Canine with Watchdog {
209               method bark { print "Woof!\n"; }
210           }
211
212           1;
213
214           # in file Watchdog.pm
215
216           use MooseX::Declare;
217
218           role Watchdog {
219               requires 'bark';
220
221               method warn_intruder ( $intruder ) {
222                   $self->bark until $intruder->gone;
223               }
224           }
225
226           1;
227
228       Subroutine redefined warnings
229
230       When composing a Moose::Role into a class that uses
231       MooseX::Method::Signatures, you may get a "Subroutine redefined"
232       warning. This happens when both the role and the class define a
233       method/subroutine of the same name. (The way roles work, the one
234       defined in the class takes precedence.) To eliminate this warning, make
235       sure that your "with" declaration happens after any method/subroutine
236       declarations that may have the same name as a method/subroutine within
237       a role.
238

AUTHORS

255       ·   Florian Ragwitz <rafl@debian.org>
256
257       ·   Ash Berlin <ash@cpan.org>
258
259       ·   Cory Watson <gphat@cpan.org>
260
261       ·   Daniel Ruoso <daniel@ruoso.com>
262
263       ·   Dave Rolsky <autarch@urth.org>
264
265       ·   Hakim Cassimally <hakim.cassimally@gmail.com>
266
267       ·   Jonathan Scott Duff <duff@pobox.com>
268
269       ·   Justin Hunter <justin.d.hunter@gmail.com>
270
271       ·   Kent Fredric <kentfredric@gmail.com>
272
273       ·   Maik Hentsche <maik.hentsche@amd.com>
274
275       ·   Matt Kraai <kraai@ftbfs.org>
276
277       ·   Rhesa Rozendaal <rhesa@cpan.org>
278
279       ·   Ricardo SIGNES <rjbs@cpan.org>
280
281       ·   Steffen Schwigon <ss5@renormalist.net>
282
283       ·   Yanick Champoux <yanick@babyl.dyndns.org>
284
285       ·   Nicholas Perez <nperez@cpan.org>
286

COPYRIGHT AND LICENSE

288       This software is copyright (c) 2010 by Florian Ragwitz.
289
290       This is free software; you can redistribute it and/or modify it under
291       the same terms as the Perl 5 programming language system itself.
292
293
294
295perl v5.12.1                      2010-07-19     MooseX::Method::Signatures(3)