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 support 'extends' (you can use 'with' to specialize a role)";
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;
49 sub _add_method_modifier {
51 my $meta = Moose::Meta::Role->initialize(shift);
55 croak "Roles do not currently support "
57 . " references for $type method modifiers"
59 my $add_method = "add_${type}_method_modifier";
60 $meta->$add_method( $_, $code );
64 sub before { _add_method_modifier('before', @_) }
66 sub after { _add_method_modifier('after', @_) }
68 sub around { _add_method_modifier('around', @_) }
70 # see Moose.pm for discussion
72 return unless $Moose::SUPER_BODY;
73 $Moose::SUPER_BODY->(@Moose::SUPER_ARGS);
77 my $meta = Moose::Meta::Role->initialize(shift);
78 my ( $name, $code ) = @_;
79 $meta->add_override_method_modifier( $name, $code );
83 croak "Roles cannot support 'inner'";
87 croak "Roles cannot support 'augment'";
90 Moose::Exporter->setup_import_methods(
92 qw( with requires excludes has before after around override make_immutable )
95 qw( extends super inner augment ),
97 \&Scalar::Util::blessed,
105 my $role = $args{for_class};
109 Moose->throw_error("Cannot call init_meta without specifying a for_class");
112 my $metaclass = $args{metaclass} || "Moose::Meta::Role";
114 # make a subtype for each Moose class
115 role_type $role unless find_type_constraint($role);
117 # FIXME copy from Moose.pm
119 if ($role->can('meta')) {
120 $meta = $role->meta();
122 unless ( blessed($meta) && $meta->isa('Moose::Meta::Role') ) {
124 Moose->throw_error("You already have a &meta function, but it does not return a Moose::Meta::Role");
128 $meta = $metaclass->initialize($role);
132 # re-initialize so it inherits properly
133 $metaclass->initialize( ref($_[0]) || $_[0] );
149 Moose::Role - The Moose Role
154 use Moose::Role; # automatically turns on strict and warnings
159 my ($self, $other) = @_;
160 !$self->equal($other);
163 # ... then in your classes
166 use Moose; # automatically turns on strict and warnings
171 my ($self, $other) = @_;
172 $self->as_float == $other->as_float;
177 The concept of roles is documented in L<Moose::Manual::Role>. This document
178 serves as API documentation.
180 =head1 EXPORTED FUNCTIONS
182 Moose::Role currently supports all of the functions that L<Moose> exports, but
183 differs slightly in how some items are handled (see L<CAVEATS> below for
186 Moose::Role also offers two role-specific keyword exports:
190 =item B<requires (@method_names)>
192 Roles can require that certain methods are implemented by any class which
195 =item B<excludes (@role_names)>
197 Roles can C<exclude> other roles, in effect saying "I can never be combined
198 with these C<@role_names>". This is a feature which should not be used
205 Moose::Role offers a way to remove the keywords it exports, through the
206 C<unimport> method. You simply have to say C<no Moose::Role> at the bottom of
207 your code for this to work.
209 =head2 B<< Moose::Role->init_meta(for_class => $role, metaclass => $metaclass) >>
211 The C<init_meta> method sets up the metaclass object for the role
212 specified by C<for_class>. It also injects a a C<meta> accessor into
213 the role so you can get at this object.
215 The default metaclass is L<Moose::Meta::Role>. You can specify an
216 alternate metaclass with the C<metaclass> parameter.
220 When you use Moose::Role, you can specify which metaclass to use:
222 use Moose::Role -metaclass => 'My::Meta::Role';
224 You can also specify traits which will be applied to your role metaclass:
226 use Moose::Role -traits => 'My::Trait';
228 This is very similar to the attribute traits feature. When you do
229 this, your class's C<meta> object will have the specified traits
230 applied to it. See L<Moose/TRAIT NAME RESOLUTION> for more details.
234 Role support has only a few caveats:
240 Roles cannot use the C<extends> keyword; it will throw an exception for now.
241 The same is true of the C<augment> and C<inner> keywords (not sure those
242 really make sense for roles). All other Moose keywords will be I<deferred>
243 so that they can be applied to the consuming class.
247 Role composition does its best to B<not> be order-sensitive when it comes to
248 conflict resolution and requirements detection. However, it is order-sensitive
249 when it comes to method modifiers. All before/around/after modifiers are
250 included whenever a role is composed into a class, and then applied in the order
251 in which the roles are used. This also means that there is no conflict for
252 before/around/after modifiers.
254 In most cases, this will be a non-issue; however, it is something to keep in
255 mind when using method modifiers in a role. You should never assume any
262 All complex software has bugs lurking in it, and this module is no
263 exception. If you find a bug please either email me, or add the bug
268 Stevan Little E<lt>stevan@iinteractive.comE<gt>
270 Christian Hansen E<lt>chansen@cpan.orgE<gt>
272 =head1 COPYRIGHT AND LICENSE
274 Copyright 2006-2009 by Infinity Interactive, Inc.
276 L<http://www.iinteractive.com>
278 This library is free software; you can redistribute it and/or modify
279 it under the same terms as Perl itself.