1MooseX::Extended::ManuaUls:e:rInCcolnutdreisb(u3t)ed PerMlooDsoecXu:m:eEnxttaetnidoend::Manual::Includes(3)
2
3
4

NAME

6       MooseX::Extended::Manual::Includes - An overview of MooseX::Extended
7       optional features
8

VERSION

10       version 0.35
11

"includes"

13       Some experimental features are useful, but might not be quite what you
14       want.
15
16       By default, MooseX::Extended tries to be relatively conservative.
17       However, you might want to turn it up to 11. There are optional,
18       EXPERIMENTAL features you can use for this. They're turned by the
19       "includes" flag.
20
21   "method"
22           package My::Names {
23               use MooseX::Extended types => [qw(compile NonEmptyStr Str )],
24                 includes                 => 'method';
25
26               param _name => ( isa => NonEmptyStr, init_arg => 'name' );
27               param title => ( isa => Str, required => 0, predicate => 1 );
28
29               method name() {
30                   my $title = $self->title; # $self is injected for you
31                   my $name  = $self->_name;
32                   return $title ? "$title $name" : $name;
33               }
34           }
35
36       Adds a "method" keyword and injects $self into the method body.
37       Requires Function::Parameters.
38
39       Note: this is equivalent to writing:
40
41           use Function::Parameters 'method';
42
43       The other features of Function::Parameters are not available by
44       default, but see "Fine-Tuning Your Includes" below.
45
46       This feature does not work with the optional "multi" keyword. Thus,  if
47       you do this:
48
49           use MooseX::Extended includes => [qw/multi method/];
50
51       You cannot do "multi method". You'll have to fall back to "multi sub".
52
53   "multi"
54           use MooseX::Extended includes => 'multi';
55
56           multi sub foo ($self, $x)      { ... }
57           multi sub foo ($self, $x, $y ) { ... }
58
59       Note: this is equivalent to writing:
60
61           use Syntax::Keyword::MultiSub;
62
63       Allows you to redeclare a method (or subroutine) and the dispatch will
64       use the number of arguments to determine which subroutine to use. Note
65       that "slurpy" arguments such as arrays or hashes will take precedence
66       over scalars if they are declared first:
67
68           multi sub foo ($self, @x) { ... }
69           multi sub foo ($self, $x) { ... } # will never be called
70
71       Thus, the following probably doesn't do what you want.
72
73           package Foo {
74               use MooseX::Extended includes => 'multi';
75
76               multi sub foo ($self, @bar) { return '@bar' }
77               multi sub foo ($self, $bar) { return '$bar' }
78           }
79
80           say +Foo->new->foo(1);
81           say +Foo->new->foo(1,2,3);
82
83       Both of the above will print the string @bar. The second definition of
84       "foo" is effectively lost.
85
86       You must declare slurpy methods last for them to work correctly:
87
88               multi sub foo ($self, $bar) { return '$bar' }
89               multi sub foo ($self, @bar) { return '@bar' }
90
91       See <https://rt.cpan.org/Ticket/Display.html?id=144171> for more
92       information.
93
94       Only available on Perl v5.26.0 or higher. Requires
95       Syntax::Keyword::MultiSub.
96
97       This feature does not work with the optional "method" keyword. Thus,
98       if you do this:
99
100           use MooseX::Extended includes => [qw/multi method/];
101
102       You cannot do "multi method". You'll have to fall back to "multi sub".
103
104   "async"
105           package My::Thing {
106               use MooseX::Extended
107                   types    => 'Str',
108                   includes => 'async';
109               use IO::Async::Loop;
110
111               field output => ( is => 'rw', isa => Str, default => '' );
112
113               async sub doit ( $self, @list ) {
114                   my $loop = IO::Async::Loop->new;
115                   $self->output('> ');
116                   foreach my $item (@list) {
117                       await $loop->delay_future( after => 0.01 );
118                       $self->output( $self->output . "$item " );
119                   }
120               }
121           }
122
123       Note: this is equivalent to writing:
124
125           use Future::AsyncAwait;
126
127       Allows you to write asynchronous code with "async" and "await".
128
129       Only available on Perl v5.26.0 or higher. Requires Future::AsyncAwait.
130
131   "try"
132           package My::Try {
133               use MooseX::Extended includes => 'try';
134
135               sub reciprocal ( $self, $num ) {
136                   try {
137                       return 1 / $num;
138                   }
139                   catch ($e) {
140                       croak "Could not calculate reciprocal of $num: $e";
141                   }
142               }
143           }
144
145       Note: this is equivalent to writing:
146
147           use Syntax::Keyword::Try;
148
149       Allows you to use try/catch blocks, via Syntax::Keyword::Try.
150
151       Only available on Perl v5.24.0 or higher. Requires
152       Syntax::Keyword::Try.
153
154       If you have Perl v5.35.8 or above, Syntax::Keyword::Try is not loaded
155       and instead we use the native "try" syntax available in Perl.
156

Fine-Tuning Your Includes

158       Some of the features rely on modules that are customizable via import
159       lists when you "use" them. Instead of accepting our defaults, you can
160       pass your own by passing a hashref to "includes". Each key must be the
161       name of a feature you can include and each value must be "undef" or an
162       array reference that will be expaned to an import list for the module:
163
164           package My::Import::List {
165               use MooseX::Extended types => 'is_PositiveOrZeroInt',
166                 includes                 => {
167                     method => [qw/method fun/],
168                     try    => undef,
169                 };
170               use List::Util 'sum';
171
172               method fac($n) { return _fac($n) }
173
174               fun _fac($n) {
175                   is_PositiveOrZeroInt($n) or die "Don't do that!";
176                   return 1 if $n < 2;
177                   return $n * _fac $n - 1;
178               }
179           }
180
181       The above would be equivalentt to writing:
182
183           use Function::Parameters qw(method fun);
184           use Syntax::Keyword::Try;
185
186       See the underlying module providing each feature to understand what
187       arguments you can pass to the import lists.
188

AUTHOR

190       Curtis "Ovid" Poe <curtis.poe@gmail.com>
191

193       This software is Copyright (c) 2022 by Curtis "Ovid" Poe.
194
195       This is free software, licensed under:
196
197         The Artistic License 2.0 (GPL Compatible)
198
199
200
201perl v5.38.0                      2023-06-M2o6oseX::Extended::Manual::Includes(3)
Impressum