1MooseX::Method::SignatuUrseesr(3C)ontributed Perl DocumeMnotoasteiXo:n:Method::Signatures(3)
2
3
4
6 MooseX::Method::Signatures - Method declarations with type constraints
7 and no source filter
8
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
47 Provides a proper method keyword, like "sub" but specifically for
48 making methods and validating their arguments against Moose type
49 constraints.
50
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
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
240 MooseX::Declare
241
242 Method::Signatures::Simple
243
244 Method::Signatures
245
246 Perl6::Subs
247
248 Devel::Declare
249
250 Parse::Method::Signatures
251
252 Moose
253
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
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)