11 if ($ENV{MOUSE_DEBUG}) {
19 use Scalar::Util 'blessed';
22 use Mouse::Meta::Attribute;
23 use Mouse::Meta::Class;
25 use Mouse::TypeRegistry;
27 our @EXPORT = qw(extends has before after around blessed confess with);
29 sub extends { Mouse::Meta::Class->initialize(caller)->superclasses(@_) }
32 my $meta = Mouse::Meta::Class->initialize(caller);
35 $names = [$names] if !ref($names);
37 for my $name (@$names) {
38 if ($name =~ s/^\+//) {
39 Mouse::Meta::Attribute->clone_parent($meta, $name, @_);
42 Mouse::Meta::Attribute->create($meta, $name, @_);
48 my $meta = Mouse::Meta::Class->initialize(caller);
53 $meta->add_before_method_modifier($_ => $code);
58 my $meta = Mouse::Meta::Class->initialize(caller);
63 $meta->add_after_method_modifier($_ => $code);
68 my $meta = Mouse::Meta::Class->initialize(caller);
73 $meta->add_around_method_modifier($_ => $code);
78 Mouse::Util::apply_all_roles((caller)[0], @_);
89 my $meta = Mouse::Meta::Class->initialize($caller);
90 $meta->superclasses('Mouse::Object')
91 unless $meta->superclasses;
94 no warnings 'redefine';
95 *{$caller.'::meta'} = sub { $meta };
98 __PACKAGE__->export_to_level( 1, $class, @_);
100 # shortcut for the common case of no type character
102 for my $keyword (@EXPORT) {
103 *{ $caller . '::' . $keyword } = *{__PACKAGE__ . '::' . $keyword};
112 for my $keyword (@EXPORT) {
113 delete ${ $caller . '::' }{$keyword};
120 if (ref($class) || !defined($class) || !length($class)) {
121 my $display = defined($class) ? $class : 'undef';
122 confess "Invalid class name ($display)";
125 return 1 if $class eq 'Mouse::Object';
126 return 1 if is_class_loaded($class);
128 (my $file = "$class.pm") =~ s{::}{/}g;
130 eval { CORE::require($file) };
131 confess "Could not load class ($class) because : $@" if $@;
136 sub is_class_loaded {
139 return 0 if ref($class) || !defined($class) || !length($class);
141 # walk the symbol table tree to avoid autovififying
142 # \*{${main::}{"Foo::"}} == \*main::Foo::
145 foreach my $part (split('::', $class)) {
146 return 0 unless exists ${$$pack}{"${part}::"};
147 $pack = \*{${$$pack}{"${part}::"}};
150 # check for $VERSION or @ISA
151 return 1 if exists ${$$pack}{VERSION}
152 && defined *{${$$pack}{VERSION}}{SCALAR};
153 return 1 if exists ${$$pack}{ISA}
154 && defined *{${$$pack}{ISA}}{ARRAY};
156 # check for any method
157 foreach ( keys %{$$pack} ) {
158 next if substr($_, -2, 2) eq '::';
159 return 1 if defined *{${$$pack}{$_}}{CODE};
172 Mouse - Moose minus the antlers
177 use Mouse; # automatically turns on strict and warnings
179 has 'x' => (is => 'rw', isa => 'Int');
180 has 'y' => (is => 'rw', isa => 'Int');
193 has 'z' => (is => 'rw', isa => 'Int');
195 after 'clear' => sub {
202 L<Moose> is wonderful.
204 Unfortunately, it's a little slow. Though significant progress has been made
205 over the years, the compile time penalty is a non-starter for some
208 Mouse aims to alleviate this by providing a subset of Moose's
209 functionality, faster. In particular, L<Moose/has> is missing only a few
210 expert-level features.
212 We're also going as light on dependencies as possible. Most functions we use
213 from L<Scalar::Util> are copied into this dist. L<Scalar::Util> is required if
214 you'd like weak references; there's simply no way to do it from pure Perl.
215 L<Class::Method::Modifiers> is required if you want support for L</before>,
216 L</after>, and L</around>.
220 Compatibility with Moose has been the utmost concern. Fewer than 1% of the
221 tests fail when run against Moose instead of Mouse. Mouse code coverage is also
222 over 96%. Even the error messages are taken from Moose. The Mouse code just
223 runs the test suite 4x faster.
225 The idea is that, if you need the extra power, you should be able to run
226 C<s/Mouse/Moose/g> on your codebase and have nothing break. To that end,
227 nothingmuch has written L<Squirrel> (part of this distribution) which will act
228 as Mouse unless Moose is loaded, in which case it will act as Moose.
230 Mouse also has the blessings of Moose's author, stevan.
232 =head2 MISSING FEATURES
236 We're working on fixing this one! stevan has suggested an implementation
237 strategy. Mouse currently ignores methods, so that needs to be fixed next.
238 Roles that consist entirely of attributes may be usable in this very version.
242 User-defined type constraints and parameterized types may be implemented. Type
243 coercions probably not (patches welcome).
245 =head3 Bootstrapped meta world
247 Very handy for extensions to the MOP. Not pressing, but would be nice to have.
249 =head3 Modification of attribute metaclass
251 When you declare an attribute with L</has>, you get the inlined accessors
252 installed immediately. Modifying the attribute metaclass, even if possible,
261 =head2 meta -> Mouse::Meta::Class
263 Returns this class' metaclass instance.
265 =head2 extends superclasses
267 Sets this class' superclasses.
269 =head2 before (method|methods) => Code
271 Installs a "before" method modifier. See L<Moose/before> or
272 L<Class::Method::Modifiers/before>.
274 Use of this feature requires L<Class::Method::Modifiers>!
276 =head2 after (method|methods) => Code
278 Installs an "after" method modifier. See L<Moose/after> or
279 L<Class::Method::Modifiers/after>.
281 Use of this feature requires L<Class::Method::Modifiers>!
283 =head2 around (method|methods) => Code
285 Installs an "around" method modifier. See L<Moose/around> or
286 L<Class::Method::Modifiers/around>.
288 Use of this feature requires L<Class::Method::Modifiers>!
290 =head2 has (name|names) => parameters
292 Adds an attribute (or if passed an arrayref of names, multiple attributes) to
299 If specified, inlines a read-only/read-write accessor with the same name as
302 =item isa => TypeConstraint
304 Provides basic type checking in the constructor and accessor. Basic types such
305 as C<Int>, C<ArrayRef>, C<Defined> are supported. Any unknown type is taken to
306 be a class check (e.g. isa => 'DateTime' would accept only L<DateTime>
309 =item required => 0|1
311 Whether this attribute is required to have a value. If the attribute is lazy or
312 has a builder, then providing a value for the attribute in the constructor is
315 =item init_arg => Str | Undef
317 Allows you to use a different key name in the constructor. If undef, the
318 attribue can't be passed to the constructor.
320 =item default => Value | CodeRef
322 Sets the default value of the attribute. If the default is a coderef, it will
323 be invoked to get the default value. Due to quirks of Perl, any bare reference
324 is forbidden, you must wrap the reference in a coderef. Otherwise, all
325 instances will share the same reference.
329 If specified, the default is calculated on demand instead of in the
332 =item predicate => Str
334 Lets you specify a method name for installing a predicate method, which checks
335 that the attribute has a value. It will not invoke a lazy default or builder
340 Lets you specify a method name for installing a clearer method, which clears
341 the attribute's value from the instance. On the next read, lazy or builder will
344 =item handles => HashRef|ArrayRef
346 Lets you specify methods to delegate to the attribute. ArrayRef forwards the
347 given method names to method calls on the attribute. HashRef maps local method
348 names to remote method names called on the attribute. Other forms of
349 L</handles>, such as regular expression and coderef, are not yet supported.
351 =item weak_ref => 0|1
353 Lets you automatically weaken any reference stored in the attribute.
355 Use of this feature requires L<Scalar::Util>!
357 =item trigger => CodeRef
359 Any time the attribute's value is set (either through the accessor or the constructor), the trigger is called on it. The trigger receives as arguments the instance, the new value, and the attribute instance.
361 Mouse 0.05 supported more complex triggers, but this behavior is now removed.
365 Defines a method name to be called to provide the default value of the
366 attribute. C<< builder => 'build_foo' >> is mostly equivalent to
367 C<< default => sub { $_[0]->build_foo } >>.
369 =item auto_deref => 0|1
371 Allows you to automatically dereference ArrayRef and HashRef attributes in list
372 context. In scalar context, the reference is returned (NOT the list length or
373 bucket status). You must specify an appropriate type constraint to use
376 =item lazy_build => 0|1
378 Automatically define lazy => 1 as well as builder => "_build_$attr", clearer =>
379 "clear_$attr', predicate => 'has_$attr' unless they are already defined.
383 =head2 confess error -> BOOM
385 L<Carp/confess> for your convenience.
387 =head2 blessed value -> ClassName | undef
389 L<Scalar::Util/blessed> for your convenience.
395 Importing Mouse will default your class' superclass list to L<Mouse::Object>.
396 You may use L</extends> to replace the superclass list.
400 Please unimport Mouse (C<no Mouse>) so that if someone calls one of the
401 keywords (such as L</extends>) it will break loudly instead breaking subtly.
405 =head2 load_class Class::Name
407 This will load a given C<Class::Name> (or die if it's not loadable).
408 This function can be used in place of tricks like
409 C<eval "use $module"> or using C<require>.
411 =head2 is_class_loaded Class::Name -> Bool
413 Returns whether this class is actually loaded or not. It uses a heuristic which
414 involves checking for the existence of C<$VERSION>, C<@ISA>, and any
415 locally-defined method.
419 Shawn M Moore, C<< <sartak at gmail.com> >>
421 Yuval Kogman, C<< <nothingmuch at woobling.org> >>
423 with plenty of code borrowed from L<Class::MOP> and L<Moose>
429 Please report any bugs through RT: email
430 C<bug-mouse at rt.cpan.org>, or browse
431 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Mouse>.
433 =head1 COPYRIGHT AND LICENSE
435 Copyright 2008 Shawn M Moore.
437 This program is free software; you can redistribute it and/or modify it
438 under the same terms as Perl itself.