7 use Scalar::Util 'blessed';
12 our $VERSION = '0.77';
13 $VERSION = eval $VERSION;
14 our $AUTHORITY = 'cpan:STEVAN';
20 use Moose::Meta::Role;
21 use Moose::Util::TypeConstraints;
24 croak "Roles do not currently support 'extends'";
28 Moose::Util::apply_all_roles( Moose::Meta::Role->initialize(shift), @_ );
32 my $meta = Moose::Meta::Role->initialize(shift);
33 croak "Must specify at least one method" unless @_;
34 $meta->add_required_methods(@_);
38 my $meta = Moose::Meta::Role->initialize(shift);
39 croak "Must specify at least one role" unless @_;
40 $meta->add_excluded_roles(@_);
44 my $meta = Moose::Meta::Role->initialize(shift);
46 croak 'Usage: has \'name\' => ( key => value, ... )' if @_ == 1;
48 my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ];
49 $meta->add_attribute( $_, %options ) for @$attrs;
53 my $meta = Moose::Meta::Role->initialize(shift);
57 croak "Roles do not currently support "
59 . " references for before method modifiers"
61 $meta->add_before_method_modifier( $_, $code );
66 my $meta = Moose::Meta::Role->initialize(shift);
70 croak "Roles do not currently support "
72 . " references for after method modifiers"
74 $meta->add_after_method_modifier( $_, $code );
79 my $meta = Moose::Meta::Role->initialize(shift);
82 croak "Roles do not currently support "
84 . " references for around method modifiers"
86 $meta->add_around_method_modifier( $_, $code );
90 # see Moose.pm for discussion
92 return unless $Moose::SUPER_BODY;
93 $Moose::SUPER_BODY->(@Moose::SUPER_ARGS);
97 my $meta = Moose::Meta::Role->initialize(shift);
98 my ( $name, $code ) = @_;
99 $meta->add_override_method_modifier( $name, $code );
103 croak "Roles cannot support 'inner'";
107 croak "Roles cannot support 'augment'";
110 Moose::Exporter->setup_import_methods(
112 qw( with requires excludes has before after around override make_immutable )
115 qw( extends super inner augment ),
117 \&Scalar::Util::blessed,
125 my $role = $args{for_class};
129 Moose->throw_error("Cannot call init_meta without specifying a for_class");
132 my $metaclass = $args{metaclass} || "Moose::Meta::Role";
134 # make a subtype for each Moose class
135 role_type $role unless find_type_constraint($role);
137 # FIXME copy from Moose.pm
139 if ($role->can('meta')) {
140 $meta = $role->meta();
142 unless ( blessed($meta) && $meta->isa('Moose::Meta::Role') ) {
144 Moose->throw_error("You already have a &meta function, but it does not return a Moose::Meta::Role");
148 $meta = $metaclass->initialize($role);
152 # re-initialize so it inherits properly
153 $metaclass->initialize( ref($_[0]) || $_[0] );
169 Moose::Role - The Moose Role
174 use Moose::Role; # automatically turns on strict and warnings
179 my ($self, $other) = @_;
180 !$self->equal($other);
183 # ... then in your classes
186 use Moose; # automatically turns on strict and warnings
191 my ($self, $other) = @_;
192 $self->as_float == $other->as_float;
197 Role support in Moose is pretty solid at this point. However, the best
198 documentation is still the the test suite. It is fairly safe to assume Perl 6
199 style behavior and then either refer to the test suite, or ask questions on
200 #moose if something doesn't quite do what you expect.
202 We are planning writing some more documentation in the near future, but nothing
205 =head1 EXPORTED FUNCTIONS
207 Moose::Role currently supports all of the functions that L<Moose> exports, but
208 differs slightly in how some items are handled (see L<CAVEATS> below for
211 Moose::Role also offers two role-specific keyword exports:
215 =item B<requires (@method_names)>
217 Roles can require that certain methods are implemented by any class which
220 =item B<excludes (@role_names)>
222 Roles can C<exclude> other roles, in effect saying "I can never be combined
223 with these C<@role_names>". This is a feature which should not be used
230 Moose::Role offers a way to remove the keywords it exports, through the
231 C<unimport> method. You simply have to say C<no Moose::Role> at the bottom of
232 your code for this to work.
234 =head2 B<< Moose::Role->init_meta(for_class => $role, metaclass => $metaclass) >>
236 The C<init_meta> method sets up the metaclass object for the role
237 specified by C<for_class>. It also injects a a C<meta> accessor into
238 the role so you can get at this object.
240 The default metaclass is L<Moose::Meta::Role>. You can specify an
241 alternate metaclass with the C<metaclass> parameter.
245 When you use Moose::Role, you can specify which metaclass to use:
247 use Moose::Role -metaclass => 'My::Meta::Role';
249 You can also specify traits which will be applied to your role metaclass:
251 use Moose::Role -traits => 'My::Trait';
253 This is very similar to the attribute traits feature. When you do
254 this, your class's C<meta> object will have the specified traits
255 applied to it. See L<Moose/TRAIT NAME RESOLUTION> for more details.
259 Role support has only a few caveats:
265 Roles cannot use the C<extends> keyword; it will throw an exception for now.
266 The same is true of the C<augment> and C<inner> keywords (not sure those
267 really make sense for roles). All other Moose keywords will be I<deferred>
268 so that they can be applied to the consuming class.
272 Role composition does its best to B<not> be order-sensitive when it comes to
273 conflict resolution and requirements detection. However, it is order-sensitive
274 when it comes to method modifiers. All before/around/after modifiers are
275 included whenever a role is composed into a class, and then applied in the order
276 in which the roles are used. This also means that there is no conflict for
277 before/around/after modifiers.
279 In most cases, this will be a non-issue; however, it is something to keep in
280 mind when using method modifiers in a role. You should never assume any
287 All complex software has bugs lurking in it, and this module is no
288 exception. If you find a bug please either email me, or add the bug
293 Stevan Little E<lt>stevan@iinteractive.comE<gt>
295 Christian Hansen E<lt>chansen@cpan.orgE<gt>
297 =head1 COPYRIGHT AND LICENSE
299 Copyright 2006-2009 by Infinity Interactive, Inc.
301 L<http://www.iinteractive.com>
303 This library is free software; you can redistribute it and/or modify
304 it under the same terms as Perl itself.