File Coverage

blib/lib/MooseX/Declare/Syntax/MooseSetup.pm
Criterion Covered Total %
statement 29 29 100.0
branch n/a
condition n/a
subroutine 12 12 100.0
pod 3 3 100.0
total 44 44 100.0


line stmt bran cond sub pod time code
1             package MooseX::Declare::Syntax::MooseSetup;
2             # ABSTRACT: Common Moose namespaces declarations
3             $MooseX::Declare::Syntax::MooseSetup::VERSION = '0.39';
4 24     24   44628 use Moose::Role;
  24         121611  
  24         159  
5              
6 24     24   164479 use Moose::Util qw( find_meta );
  24         68  
  24         225  
7 24     24   5341 use Sub::Install qw( install_sub );
  24         52  
  24         226  
8              
9 24     24   2591 use aliased 'MooseX::Declare::Syntax::Keyword::MethodModifier';
  24         366  
  24         276  
10 24     24   3012 use aliased 'MooseX::Declare::Syntax::Keyword::Method';
  24         57  
  24         173  
11 24     24   3072 use aliased 'MooseX::Declare::Syntax::Keyword::With', 'WithKeyword';
  24         57  
  24         197  
12 24     24   2737 use aliased 'MooseX::Declare::Syntax::Keyword::Clean', 'CleanKeyword';
  24         56  
  24         226  
13              
14 24     24   2787 use namespace::clean -except => 'meta';
  24         57  
  24         209  
15              
16             #pod =head1 DESCRIPTION
17             #pod
18             #pod This role is basically an extension to
19             #pod L<NamespaceHandling|MooseX::Declare::Syntax::NamespaceHandling>. It adds all
20             #pod the common parts for L<Moose> namespace definitions. Examples of this role
21             #pod can be found in the L<class|MooseX::Declare::Syntax::Keyword::Class> and
22             #pod L<role|MooseX::Declare::Syntax::Keyword::Role> keywords.
23             #pod
24             #pod =head1 CONSUMES
25             #pod
26             #pod =for :list
27             #pod * L<MooseX::Declare::Syntax::NamespaceHandling>
28             #pod * L<MooseX::Declare::Syntax::EmptyBlockIfMissing>
29             #pod
30             #pod =cut
31              
32             with qw(
33             MooseX::Declare::Syntax::NamespaceHandling
34             MooseX::Declare::Syntax::EmptyBlockIfMissing
35             );
36              
37             #pod =method auto_make_immutable
38             #pod
39             #pod Bool Object->auto_make_immutable ()
40             #pod
41             #pod Since L<Moose::Role>s can't be made immutable (this is not a bug or a
42             #pod missing feature, it would make no sense), this always returns false.
43             #pod
44             #pod =cut
45              
46 14     14 1 100 sub auto_make_immutable { 0 }
47              
48             #pod =method imported_moose_symbols
49             #pod
50             #pod List Object->imported_moose_symbols ()
51             #pod
52             #pod This will return C<confess> and C<blessed> by default to provide as
53             #pod additional imports to the namespace.
54             #pod
55             #pod =cut
56              
57 61     61 1 4068 sub imported_moose_symbols { qw( confess blessed ) }
58              
59             #pod =method import_symbols_from
60             #pod
61             #pod Str Object->import_symbols_from ()
62             #pod
63             #pod The namespace from which the additional imports will be imported. This
64             #pod will return C<Moose> by default.
65             #pod
66             #pod =cut
67              
68 47     47 1 304 sub import_symbols_from { 'Moose' }
69              
70             #pod =head1 MODIFIED METHODS
71             #pod
72             #pod =head2 default_inner
73             #pod
74             #pod ArrayRef default_inner ()
75             #pod
76             #pod This will provide the following default inner-handlers to the namspace:
77             #pod
78             #pod =for :list
79             #pod * method
80             #pod A simple L<Method|MooseX::Declare::Syntax::Keyword::Method> handler.
81             #pod * around
82             #pod This is a L<MethodModifier|MooseX::Declare::Syntax::Keyword::MethodModifier>
83             #pod handler that will start the signature of the generated method with
84             #pod C<$orig: $self> to provide the original method in C<$orig>.
85             #pod * after
86             #pod * before
87             #pod * override
88             #pod * augment
89             #pod These four handlers are L<MethodModifier|MooseX::Declare::Syntax::Keyword::MethodModifier>
90             #pod instances.
91             #pod * clean
92             #pod This is an instance of the L<Clean|MooseX::Declare::Syntax::Keyword::Clean> keyword
93             #pod handler.
94             #pod
95             #pod The original method will never be called and all arguments are ignored at the
96             #pod moment.
97             #pod
98             #pod =cut
99              
100             around default_inner => sub {
101             return [
102             WithKeyword->new(identifier => 'with'),
103             Method->new(identifier => 'method'),
104             MethodModifier->new(
105             identifier => 'around',
106             modifier_type => 'around',
107             prototype_injections => {
108             declarator => 'around',
109             injections => [ 'CodeRef $orig' ],
110             },
111             ),
112             map { MethodModifier->new(identifier => $_, modifier_type => $_) }
113             qw( after before override augment ),
114             ];
115             };
116              
117             #pod =head2 setup_inner_for
118             #pod
119             #pod Object->setup_inner_for (ClassName $class)
120             #pod
121             #pod This will install a C<with> function that will push its arguments onto a global
122             #pod storage array holding the roles of the current namespace.
123             #pod
124             #pod =cut
125              
126             after setup_inner_for => sub {
127             my ($self, $setup_class, %args) = @_;
128             my $keyword = CleanKeyword->new(identifier => 'clean');
129             $keyword->setup_for($setup_class, %args);
130             };
131              
132             #pod =head2 add_namespace_customizations
133             #pod
134             #pod Object->add_namespace_customizations (Object $context, Str $package, HashRef $options)
135             #pod
136             #pod After all other customizations, this will first add code to import the
137             #pod L</imported_moose_symbols> from the package returned in L</import_symbols_from> to
138             #pod the L<preamble|MooseX::Declare::Context/preamble_code_parts>.
139             #pod
140             #pod Then it will add a code part that will immutabilize the class to the
141             #pod L<cleanup|MooseX::Declare::Context/cleanup_code_parts> code if the
142             #pod L</auto_make_immutable> method returned a true value and C<< $options->{is}{mutable} >>
143             #pod does not exist.
144             #pod
145             #pod =cut
146              
147             after add_namespace_customizations => sub {
148             my ($self, $ctx, $package) = @_;
149              
150             # add Moose initializations to preamble
151             $ctx->add_preamble_code_parts(
152             sprintf 'use %s qw( %s )', $self->import_symbols_from($ctx), join ' ', $self->imported_moose_symbols($ctx),
153             );
154              
155             # make class immutable unless specified otherwise
156             $ctx->add_cleanup_code_parts(
157             "${package}->meta->make_immutable",
158             ) if $self->auto_make_immutable
159             and not exists $ctx->options->{is}{mutable};
160             };
161              
162             #pod =head2 handle_post_parsing
163             #pod
164             #pod CodeRef Object->handle_post_parsing (Object $context, Str $package, Str|Object $name)
165             #pod
166             #pod Generates a callback that sets up the roles in the global role storage for the current
167             #pod namespace. The C<$name> parameter will be the specified name (in contrast to C<$package>
168             #pod which will always be the fully qualified name) or the anonymous metaclass instance if
169             #pod none was specified.
170             #pod
171             #pod =cut
172              
173             after handle_post_parsing => sub {
174             my ($self, $ctx, $package, $class) = @_;
175 3     3   13412 $ctx->shadow(sub (&) { shift->(); return $class; });
  3         26707  
176             };
177              
178              
179             #pod =head1 SEE ALSO
180             #pod
181             #pod =for :list
182             #pod * L<MooseX::Declare>
183             #pod * L<Moose>
184             #pod
185             #pod =cut
186              
187             1;
188              
189             __END__
190              
191             =pod
192              
193             =encoding UTF-8
194              
195             =head1 NAME
196              
197             MooseX::Declare::Syntax::MooseSetup - Common Moose namespaces declarations
198              
199             =head1 VERSION
200              
201             version 0.39
202              
203             =head1 DESCRIPTION
204              
205             This role is basically an extension to
206             L<NamespaceHandling|MooseX::Declare::Syntax::NamespaceHandling>. It adds all
207             the common parts for L<Moose> namespace definitions. Examples of this role
208             can be found in the L<class|MooseX::Declare::Syntax::Keyword::Class> and
209             L<role|MooseX::Declare::Syntax::Keyword::Role> keywords.
210              
211             =head1 METHODS
212              
213             =head2 auto_make_immutable
214              
215             Bool Object->auto_make_immutable ()
216              
217             Since L<Moose::Role>s can't be made immutable (this is not a bug or a
218             missing feature, it would make no sense), this always returns false.
219              
220             =head2 imported_moose_symbols
221              
222             List Object->imported_moose_symbols ()
223              
224             This will return C<confess> and C<blessed> by default to provide as
225             additional imports to the namespace.
226              
227             =head2 import_symbols_from
228              
229             Str Object->import_symbols_from ()
230              
231             The namespace from which the additional imports will be imported. This
232             will return C<Moose> by default.
233              
234             =head1 CONSUMES
235              
236             =over 4
237              
238             =item *
239              
240             L<MooseX::Declare::Syntax::NamespaceHandling>
241              
242             =item *
243              
244             L<MooseX::Declare::Syntax::EmptyBlockIfMissing>
245              
246             =back
247              
248             =head1 MODIFIED METHODS
249              
250             =head2 default_inner
251              
252             ArrayRef default_inner ()
253              
254             This will provide the following default inner-handlers to the namspace:
255              
256             =over 4
257              
258             =item *
259              
260             method
261              
262             A simple L<Method|MooseX::Declare::Syntax::Keyword::Method> handler.
263              
264             =item *
265              
266             around
267              
268             This is a L<MethodModifier|MooseX::Declare::Syntax::Keyword::MethodModifier>
269             handler that will start the signature of the generated method with
270             C<$orig: $self> to provide the original method in C<$orig>.
271              
272             =item *
273              
274             after
275              
276             =item *
277              
278             before
279              
280             =item *
281              
282             override
283              
284             =item *
285              
286             augment
287              
288             These four handlers are L<MethodModifier|MooseX::Declare::Syntax::Keyword::MethodModifier>
289             instances.
290              
291             =item *
292              
293             clean
294              
295             This is an instance of the L<Clean|MooseX::Declare::Syntax::Keyword::Clean> keyword
296             handler.
297              
298             =back
299              
300             The original method will never be called and all arguments are ignored at the
301             moment.
302              
303             =head2 setup_inner_for
304              
305             Object->setup_inner_for (ClassName $class)
306              
307             This will install a C<with> function that will push its arguments onto a global
308             storage array holding the roles of the current namespace.
309              
310             =head2 add_namespace_customizations
311              
312             Object->add_namespace_customizations (Object $context, Str $package, HashRef $options)
313              
314             After all other customizations, this will first add code to import the
315             L</imported_moose_symbols> from the package returned in L</import_symbols_from> to
316             the L<preamble|MooseX::Declare::Context/preamble_code_parts>.
317              
318             Then it will add a code part that will immutabilize the class to the
319             L<cleanup|MooseX::Declare::Context/cleanup_code_parts> code if the
320             L</auto_make_immutable> method returned a true value and C<< $options->{is}{mutable} >>
321             does not exist.
322              
323             =head2 handle_post_parsing
324              
325             CodeRef Object->handle_post_parsing (Object $context, Str $package, Str|Object $name)
326              
327             Generates a callback that sets up the roles in the global role storage for the current
328             namespace. The C<$name> parameter will be the specified name (in contrast to C<$package>
329             which will always be the fully qualified name) or the anonymous metaclass instance if
330             none was specified.
331              
332             =head1 SEE ALSO
333              
334             =over 4
335              
336             =item *
337              
338             L<MooseX::Declare>
339              
340             =item *
341              
342             L<Moose>
343              
344             =back
345              
346             =head1 AUTHOR
347              
348             Florian Ragwitz <rafl@debian.org>
349              
350             =head1 COPYRIGHT AND LICENSE
351              
352             This software is copyright (c) 2008 by Florian Ragwitz.
353              
354             This is free software; you can redistribute it and/or modify it under
355             the same terms as the Perl 5 programming language system itself.
356              
357             =cut