MooseX::Method::Signatures(3pm)

1MooseX::Method::SignatuUrseesr(3Cpomn)tributed Perl DocuMmoeonsteaXt:i:oMnethod::Signatures(3pm)
2
3
4

NAME

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

VERSION

10       version 0.49
11

SYNOPSIS

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

DESCRIPTION

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

DEPRECATION NOTICE

55       Warning: MooseX::Method::Signatures and MooseX::Declare are based on
56       Devel::Declare, a giant bag of crack originally implemented by mst with
57       the goal of upsetting the perl core developers so much by its very
58       existence that they implemented proper keyword handling in the core.
59
60       As of perl5 version 14, this goal has been achieved, and modules such
61       as Devel::CallParser, Function::Parameters, and Keyword::Simple provide
62       mechanisms to mangle perl syntax that don't require hallucinogenic
63       drugs to interpret the error messages they produce.
64
65       If you want to use declarative syntax in new code, please for the love
66       of kittens get yourself a recent perl and look at Moops and core
67       signatures instead.
68

SIGNATURE SYNTAX

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

CAVEATS AND NOTES

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

SUPPORT

273       Bugs may be submitted through the RT bug tracker
274       <https://rt.cpan.org/Public/Dist/Display.html?Name=MooseX-Method-
275       Signatures> (or bug-MooseX-Method-Signatures@rt.cpan.org <mailto:bug-
276       MooseX-Method-Signatures@rt.cpan.org>).
277
278       There is also a mailing list available for users of this distribution,
279       at <http://lists.perl.org/list/moose.html>.
280
281       There is also an irc channel available for users of this distribution,
282       at irc://irc.perl.org/#moose.
283
284       I am also usually active on irc, as 'ether' at "irc.perl.org".
285

AUTHOR

287       Florian Ragwitz <rafl@debian.org>
288

CONTRIBUTORS

290       •   Karen Etheridge <ether@cpan.org>
291
292       •   Ash Berlin <ash@cpan.org>
293
294       •   Daniel Ruoso <daniel@ruoso.com>
295
296       •   Justin Hunter <justin.d.hunter@gmail.com>
297
298       •   Nicholas Perez <nperez@cpan.org>
299
300       •   Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
301
302       •   Rhesa Rozendaal <rhesa@cpan.org>
303
304       •   Yanick Champoux <yanick@babyl.dyndns.org>
305
306       •   Cory Watson <gphat@cpan.org>
307
308       •   Kent Fredric <kentfredric@gmail.com>
309
310       •   Lukas Mai <l.mai@web.de>
311
312       •   Matt Kraai <kraai@ftbfs.org>
313
314       •   Jonathan Scott Duff <duff@pobox.com>
315
316       •   Jesse Luehrs <doy@tozt.net>
317
318       •   Hakim Cassimally <osfameron@cpan.org>
319
320       •   Dave Rolsky <autarch@urth.org>
321
322       •   Ricardo SIGNES <rjbs@cpan.org>
323
324       •   Sebastian Willert <willert@cpan.org>
325
326       •   Steffen Schwigon <ss5@renormalist.net>
327

COPYRIGHT AND LICENCE

329       This software is copyright (c) 2008 by Florian Ragwitz.
330
331       This is free software; you can redistribute it and/or modify it under
332       the same terms as the Perl 5 programming language system itself.
333
334
335
336perl v5.36.0                      2023-01-20   MooseX::Method::Signatures(3pm)