7 use Scalar::Util 'blessed';
9 use Sub::Name 'subname';
13 our $VERSION = '0.07';
14 our $AUTHORITY = 'cpan:STEVAN';
18 use Moose::Meta::Role;
19 use Moose::Util::TypeConstraints;
22 my ( $CALLER, %METAS );
27 return $METAS{$role} if exists $METAS{$role};
29 # make a subtype for each Moose class
32 => where { $_->does($role) }
33 => optimize_as { blessed($_[0]) && $_[0]->can('does') && $_[0]->does($role) }
34 unless find_type_constraint($role);
37 if ($role->can('meta')) {
38 $meta = $role->meta();
39 (blessed($meta) && $meta->isa('Moose::Meta::Role'))
40 || confess "You already have a &meta function, but it does not return a Moose::Meta::Role";
43 $meta = Moose::Meta::Role->initialize($role);
44 $meta->Moose::Meta::Class::add_method('meta' => sub { $meta })
47 return $METAS{$role} = $meta;
53 my $meta = _find_meta();
54 return subname 'Moose::Role::extends' => sub {
55 confess "Moose::Role does not currently support 'extends'"
59 my $meta = _find_meta();
60 return subname 'Moose::Role::with' => sub (@) {
62 confess "Must specify at least one role" unless @roles;
63 Class::MOP::load_class($_) for @roles;
64 ($_->can('meta') && $_->meta->isa('Moose::Meta::Role'))
65 || confess "You can only consume roles, $_ is not a Moose role"
67 if (scalar @roles == 1) {
68 $roles[0]->meta->apply($meta);
71 Moose::Meta::Role->combine(
72 map { $_->meta } @roles
78 my $meta = _find_meta();
79 return subname 'Moose::Role::requires' => sub (@) {
80 confess "Must specify at least one method" unless @_;
81 $meta->add_required_methods(@_);
85 my $meta = _find_meta();
86 return subname 'Moose::Role::excludes' => sub (@) {
87 confess "Must specify at least one role" unless @_;
88 $meta->add_excluded_roles(@_);
92 my $meta = _find_meta();
93 return subname 'Moose::Role::has' => sub ($;%) {
94 my ($name, %options) = @_;
95 $meta->add_attribute($name, %options)
99 my $meta = _find_meta();
100 return subname 'Moose::Role::before' => sub (@&) {
102 $meta->add_before_method_modifier($_, $code) for @_;
106 my $meta = _find_meta();
107 return subname 'Moose::Role::after' => sub (@&) {
109 $meta->add_after_method_modifier($_, $code) for @_;
113 my $meta = _find_meta();
114 return subname 'Moose::Role::around' => sub (@&) {
116 $meta->add_around_method_modifier($_, $code) for @_;
122 $Moose::SUPER_SLOT{$CALLER} = \*{"${CALLER}::super"};
124 my $meta = _find_meta();
125 return subname 'Moose::Role::super' => sub {};
128 my $meta = _find_meta();
129 return subname 'Moose::Role::override' => sub ($&) {
130 my ($name, $code) = @_;
131 $meta->add_override_method_modifier($name, $code);
135 my $meta = _find_meta();
136 return subname 'Moose::Role::inner' => sub {
137 confess "Moose::Role cannot support 'inner'";
141 my $meta = _find_meta();
142 return subname 'Moose::Role::augment' => sub {
143 confess "Moose::Role cannot support 'augment'";
147 return \&Carp::confess;
150 return \&Scalar::Util::blessed;
154 my $exporter = Sub::Exporter::build_exporter({
155 exports => \%exports,
167 # we should never export to main
168 return if $CALLER eq 'main';
183 Moose::Role - The Moose Role
188 use Moose::Role; # automatically turns on strict and warnings
193 my ($self, $other) = @_;
194 !$self->equal($other);
197 # ... then in your classes
200 use Moose; # automatically turns on strict and warnings
205 my ($self, $other) = @_;
206 $self->as_float == $other->as_float;
211 Role support in Moose is pretty solid at this point. However, the best
212 documentation is still the the test suite. It is fairly safe to assume Perl 6
213 style behavior and then either refer to the test suite, or ask questions on
214 #moose if something doesn't quite do what you expect.
216 We are planning writing some more documentation in the near future, but nothing
219 =head1 EXPORTED FUNCTIONS
221 Moose::Role currently supports all of the functions that L<Moose> exports, but
222 differs slightly in how some items are handled (see L<CAVEATS> below for
225 Moose::Role also offers two role-specific keyword exports:
229 =item B<requires (@method_names)>
231 Roles can require that certain methods are implemented by any class which
234 =item B<excludes (@role_names)>
236 Roles can C<exclude> other roles, in effect saying "I can never be combined
237 with these C<@role_names>". This is a feature which should not be used
244 Role support has only a few caveats:
250 Roles cannot use the C<extends> keyword; it will throw an exception for now.
251 The same is true of the C<augment> and C<inner> keywords (not sure those
252 really make sense for roles). All other Moose keywords will be I<deferred>
253 so that they can be applied to the consuming class.
257 Role composition does its best to B<not> be order-sensitive when it comes to
258 conflict resolution and requirements detection. However, it is order-sensitive
259 when it comes to method modifiers. All before/around/after modifiers are
260 included whenever a role is composed into a class, and then applied in the order
261 in which the roles are used. This also means that there is no conflict for
262 before/around/after modifiers.
264 In most cases, this will be a non-issue; however, it is something to keep in
265 mind when using method modifiers in a role. You should never assume any
270 The C<requires> keyword currently only works with actual methods. A method
271 modifier (before/around/after and override) will not count as a fufillment
272 of the requirement, and neither will an autogenerated accessor for an attribute.
274 It is likely that attribute accessors will eventually be allowed to fufill those
275 requirements, or we will introduce a C<requires_attr> keyword of some kind
276 instead. This decision has not yet been finalized.
282 All complex software has bugs lurking in it, and this module is no
283 exception. If you find a bug please either email me, or add the bug
288 Stevan Little E<lt>stevan@iinteractive.comE<gt>
290 Christian Hansen E<lt>chansen@cpan.orgE<gt>
292 =head1 COPYRIGHT AND LICENSE
294 Copyright 2006, 2007 by Infinity Interactive, Inc.
296 L<http://www.iinteractive.com>
298 This library is free software; you can redistribute it and/or modify
299 it under the same terms as Perl itself.