4 use Scalar::Util 'blessed';
10 $VERSION = eval $VERSION;
11 our $AUTHORITY = 'cpan:STEVAN';
17 use Moose::Meta::Role;
18 use Moose::Util::TypeConstraints;
21 croak "Roles do not currently support 'extends'";
25 Moose::Util::apply_all_roles( Moose::Meta::Role->initialize(shift), @_ );
29 my $meta = Moose::Meta::Role->initialize(shift);
30 croak "Must specify at least one method" unless @_;
31 $meta->add_required_methods(@_);
35 my $meta = Moose::Meta::Role->initialize(shift);
36 croak "Must specify at least one role" unless @_;
37 $meta->add_excluded_roles(@_);
41 my $meta = Moose::Meta::Role->initialize(shift);
43 croak 'Usage: has \'name\' => ( key => value, ... )' if @_ == 1;
45 my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ];
46 $meta->add_attribute( $_, %options ) for @$attrs;
50 my $meta = Moose::Meta::Role->initialize(shift);
54 croak "Roles do not currently support "
56 . " references for before method modifiers"
58 $meta->add_before_method_modifier( $_, $code );
63 my $meta = Moose::Meta::Role->initialize(shift);
67 croak "Roles do not currently support "
69 . " references for after method modifiers"
71 $meta->add_after_method_modifier( $_, $code );
76 my $meta = Moose::Meta::Role->initialize(shift);
79 croak "Roles do not currently support "
81 . " references for around method modifiers"
83 $meta->add_around_method_modifier( $_, $code );
87 # see Moose.pm for discussion
89 return unless $Moose::SUPER_BODY;
90 $Moose::SUPER_BODY->(@Moose::SUPER_ARGS);
94 my $meta = Moose::Meta::Role->initialize(shift);
95 my ( $name, $code ) = @_;
96 $meta->add_override_method_modifier( $name, $code );
100 croak "Roles cannot support 'inner'";
104 croak "Roles cannot support 'augment'";
107 Moose::Exporter->setup_import_methods(
109 qw( with requires excludes has before after around override make_immutable )
112 qw( extends super inner augment ),
114 \&Scalar::Util::blessed,
122 my $role = $args{for_class};
126 Moose->throw_error("Cannot call init_meta without specifying a for_class");
129 my $metaclass = $args{metaclass} || "Moose::Meta::Role";
131 # make a subtype for each Moose class
132 role_type $role unless find_type_constraint($role);
134 # FIXME copy from Moose.pm
136 if ($role->can('meta')) {
137 $meta = $role->meta();
139 unless ( blessed($meta) && $meta->isa('Moose::Meta::Role') ) {
141 Moose->throw_error("You already have a &meta function, but it does not return a Moose::Meta::Role");
145 $meta = $metaclass->initialize($role);
149 # re-initialize so it inherits properly
150 $metaclass->initialize( ref($_[0]) || $_[0] );
166 Moose::Role - The Moose Role
171 use Moose::Role; # automatically turns on strict and warnings
176 my ($self, $other) = @_;
177 !$self->equal($other);
180 # ... then in your classes
183 use Moose; # automatically turns on strict and warnings
188 my ($self, $other) = @_;
189 $self->as_float == $other->as_float;
194 Role support in Moose is pretty solid at this point. However, the best
195 documentation is still the the test suite. It is fairly safe to assume Perl 6
196 style behavior and then either refer to the test suite, or ask questions on
197 #moose if something doesn't quite do what you expect.
199 We are planning writing some more documentation in the near future, but nothing
202 =head1 EXPORTED FUNCTIONS
204 Moose::Role currently supports all of the functions that L<Moose> exports, but
205 differs slightly in how some items are handled (see L<CAVEATS> below for
208 Moose::Role also offers two role-specific keyword exports:
212 =item B<requires (@method_names)>
214 Roles can require that certain methods are implemented by any class which
217 =item B<excludes (@role_names)>
219 Roles can C<exclude> other roles, in effect saying "I can never be combined
220 with these C<@role_names>". This is a feature which should not be used
227 Moose::Role offers a way to remove the keywords it exports, through the
228 C<unimport> method. You simply have to say C<no Moose::Role> at the bottom of
229 your code for this to work.
231 =head2 B<< Moose::Role->init_meta(for_class => $role, metaclass => $metaclass) >>
233 The C<init_meta> method sets up the metaclass object for the role
234 specified by C<for_class>. It also injects a a C<meta> accessor into
235 the role so you can get at this object.
237 The default metaclass is L<Moose::Meta::Role>. You can specify an
238 alternate metaclass with the C<metaclass> parameter.
242 When you use Moose::Role, you can specify which metaclass to use:
244 use Moose::Role -metaclass => 'My::Meta::Role';
246 You can also specify traits which will be applied to your role metaclass:
248 use Moose::Role -traits => 'My::Trait';
250 This is very similar to the attribute traits feature. When you do
251 this, your class's C<meta> object will have the specified traits
252 applied to it. See L<Moose/TRAIT NAME RESOLUTION> for more details.
256 Role support has only a few caveats:
262 Roles cannot use the C<extends> keyword; it will throw an exception for now.
263 The same is true of the C<augment> and C<inner> keywords (not sure those
264 really make sense for roles). All other Moose keywords will be I<deferred>
265 so that they can be applied to the consuming class.
269 Role composition does its best to B<not> be order-sensitive when it comes to
270 conflict resolution and requirements detection. However, it is order-sensitive
271 when it comes to method modifiers. All before/around/after modifiers are
272 included whenever a role is composed into a class, and then applied in the order
273 in which the roles are used. This also means that there is no conflict for
274 before/around/after modifiers.
276 In most cases, this will be a non-issue; however, it is something to keep in
277 mind when using method modifiers in a role. You should never assume any
284 All complex software has bugs lurking in it, and this module is no
285 exception. If you find a bug please either email me, or add the bug
290 Stevan Little E<lt>stevan@iinteractive.comE<gt>
292 Christian Hansen E<lt>chansen@cpan.orgE<gt>
294 =head1 COPYRIGHT AND LICENSE
296 Copyright 2006-2009 by Infinity Interactive, Inc.
298 L<http://www.iinteractive.com>
300 This library is free software; you can redistribute it and/or modify
301 it under the same terms as Perl itself.