10 use Scalar::Util 'blessed';
11 use Mouse::Util qw(load_class is_class_loaded);
13 use Mouse::Meta::Attribute;
14 use Mouse::Meta::Module; # class_of()
15 use Mouse::Meta::Class;
17 use Mouse::Util::TypeConstraints;
19 our @EXPORT = qw(extends has before after around override super blessed confess with);
21 our %is_removable = map{ $_ => undef } @EXPORT;
22 delete $is_removable{blessed};
23 delete $is_removable{confess};
25 sub extends { Mouse::Meta::Class->initialize(scalar caller)->superclasses(@_) }
28 my $meta = Mouse::Meta::Class->initialize(scalar caller);
29 $meta->add_attribute(@_);
33 my $meta = Mouse::Meta::Class->initialize(scalar caller);
38 $meta->add_before_method_modifier($_ => $code);
43 my $meta = Mouse::Meta::Class->initialize(scalar caller);
48 $meta->add_after_method_modifier($_ => $code);
53 my $meta = Mouse::Meta::Class->initialize(scalar caller);
58 $meta->add_around_method_modifier($_ => $code);
63 Mouse::Util::apply_all_roles(scalar(caller), @_);
71 # This check avoids a recursion loop - see
72 # t/100_bugs/020_super_recursion.t
73 return if defined $SUPER_PACKAGE && $SUPER_PACKAGE ne caller();
74 return unless $SUPER_BODY; $SUPER_BODY->(@SUPER_ARGS);
78 my $meta = Mouse::Meta::Class->initialize(caller);
79 my $pkg = $meta->name;
84 my $body = $pkg->can($name)
85 or confess "You cannot override '$name' because it has no super method";
87 $meta->add_method($name => sub {
88 local $SUPER_PACKAGE = $pkg;
89 local @SUPER_ARGS = @_;
90 local $SUPER_BODY = $body;
97 # This used to be called as a function. This hack preserves
98 # backwards compatibility.
99 if ( $_[0] ne __PACKAGE__ ) {
100 return __PACKAGE__->init_meta(
110 my $class = $args{for_class}
112 "Cannot call init_meta without specifying a for_class");
113 my $base_class = $args{base_class} || 'Mouse::Object';
114 my $metaclass = $args{metaclass} || 'Mouse::Meta::Class';
116 Carp::croak("The Metaclass $metaclass must be a subclass of Mouse::Meta::Class.")
117 unless $metaclass->isa('Mouse::Meta::Class');
119 # make a subtype for each Mouse class
121 unless find_type_constraint($class);
123 my $meta = $metaclass->initialize($class);
124 $meta->superclasses($base_class)
125 unless $meta->superclasses;
127 $meta->add_method(meta => sub{
128 return Mouse::Meta::Class->initialize(ref($_[0]) || $_[0]);
142 if (ref($_[0]) && ref($_[0]) eq 'HASH') {
148 my $level = delete $opts->{into_level};
149 $level = 0 unless defined $level;
150 my $caller = caller($level);
152 # we should never export to main
153 if ($caller eq 'main') {
154 warn qq{$class does not export its sugar to the 'main' package.\n};
159 for_class => $caller,
163 __PACKAGE__->export_to_level( $level+1, $class, @_);
165 # shortcut for the common case of no type character
167 for my $keyword (@EXPORT) {
168 *{ $caller . '::' . $keyword } = *{__PACKAGE__ . '::' . $keyword};
181 for my $keyword (@EXPORT) {
183 if(exists $is_removable{$keyword}
184 && ($code = $caller->can($keyword))
185 && (Mouse::Util::get_code_info($code))[0] eq __PACKAGE__){
187 delete $stash->{$keyword};
198 Mouse - Moose minus the antlers
203 use Mouse; # automatically turns on strict and warnings
205 has 'x' => (is => 'rw', isa => 'Int');
206 has 'y' => (is => 'rw', isa => 'Int');
219 has 'z' => (is => 'rw', isa => 'Int');
221 after 'clear' => sub {
228 L<Moose> is wonderful. B<Use Moose instead of Mouse.>
230 Unfortunately, Moose has a compile-time penalty. Though significant progress
231 has been made over the years, the compile time penalty is a non-starter for
232 some very specific applications. If you are writing a command-line application
233 or CGI script where startup time is essential, you may not be able to use
234 Moose. We recommend that you instead use L<HTTP::Engine> and FastCGI for the
237 Mouse aims to alleviate this by providing a subset of Moose's functionality,
240 We're also going as light on dependencies as possible.
241 L<Class::Method::Modifiers::Fast> or L<Class::Method::Modifiers> is required
242 if you want support for L</before>, L</after>, and L</around>.
246 Compatibility with Moose has been the utmost concern. Fewer than 1% of the
247 tests fail when run against Moose instead of Mouse. Mouse code coverage is also
248 over 96%. Even the error messages are taken from Moose. The Mouse code just
249 runs the test suite 4x faster.
251 The idea is that, if you need the extra power, you should be able to run
252 C<s/Mouse/Moose/g> on your codebase and have nothing break. To that end,
253 we have written L<Any::Moose> which will act as Mouse unless Moose is loaded,
254 in which case it will act as Moose. Since Mouse is a little sloppier than
255 Moose, if you run into weird errors, it would be worth running:
257 ANY_MOOSE=Moose perl your-script.pl
259 to see if the bug is caused by Mouse. Moose's diagnostics and validation are
264 Please don't copy MooseX code to MouseX. If you need extensions, you really
265 should upgrade to Moose. We don't need two parallel sets of extensions!
267 If you really must write a Mouse extension, please contact the Moose mailing
268 list or #moose on IRC beforehand.
272 The original author of this module has mostly stepped down from maintaining
273 Mouse. See L<http://www.nntp.perl.org/group/perl.moose/2009/04/msg653.html>.
274 If you would like to help maintain this module, please get in touch with us.
278 =head2 meta -> Mouse::Meta::Class
280 Returns this class' metaclass instance.
282 =head2 extends superclasses
284 Sets this class' superclasses.
286 =head2 before (method|methods) => Code
288 Installs a "before" method modifier. See L<Moose/before> or
289 L<Class::Method::Modifiers/before>.
291 Use of this feature requires L<Class::Method::Modifiers>!
293 =head2 after (method|methods) => Code
295 Installs an "after" method modifier. See L<Moose/after> or
296 L<Class::Method::Modifiers/after>.
298 Use of this feature requires L<Class::Method::Modifiers>!
300 =head2 around (method|methods) => Code
302 Installs an "around" method modifier. See L<Moose/around> or
303 L<Class::Method::Modifiers/around>.
305 Use of this feature requires L<Class::Method::Modifiers>!
307 =head2 has (name|names) => parameters
309 Adds an attribute (or if passed an arrayref of names, multiple attributes) to
316 If specified, inlines a read-only/read-write accessor with the same name as
319 =item isa => TypeConstraint
321 Provides type checking in the constructor and accessor. The following types are
322 supported. Any unknown type is taken to be a class check (e.g. isa =>
323 'DateTime' would accept only L<DateTime> objects).
325 Any Item Bool Undef Defined Value Num Int Str ClassName
326 Ref ScalarRef ArrayRef HashRef CodeRef RegexpRef GlobRef
329 For more documentation on type constraints, see L<Mouse::Util::TypeConstraints>.
332 =item required => 0|1
334 Whether this attribute is required to have a value. If the attribute is lazy or
335 has a builder, then providing a value for the attribute in the constructor is
338 =item init_arg => Str | Undef
340 Allows you to use a different key name in the constructor. If undef, the
341 attribue can't be passed to the constructor.
343 =item default => Value | CodeRef
345 Sets the default value of the attribute. If the default is a coderef, it will
346 be invoked to get the default value. Due to quirks of Perl, any bare reference
347 is forbidden, you must wrap the reference in a coderef. Otherwise, all
348 instances will share the same reference.
352 If specified, the default is calculated on demand instead of in the
355 =item predicate => Str
357 Lets you specify a method name for installing a predicate method, which checks
358 that the attribute has a value. It will not invoke a lazy default or builder
363 Lets you specify a method name for installing a clearer method, which clears
364 the attribute's value from the instance. On the next read, lazy or builder will
367 =item handles => HashRef|ArrayRef
369 Lets you specify methods to delegate to the attribute. ArrayRef forwards the
370 given method names to method calls on the attribute. HashRef maps local method
371 names to remote method names called on the attribute. Other forms of
372 L</handles>, such as regular expression and coderef, are not yet supported.
374 =item weak_ref => 0|1
376 Lets you automatically weaken any reference stored in the attribute.
378 Use of this feature requires L<Scalar::Util>!
380 =item trigger => CodeRef
382 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.
384 Mouse 0.05 supported more complex triggers, but this behavior is now removed.
388 Defines a method name to be called to provide the default value of the
389 attribute. C<< builder => 'build_foo' >> is mostly equivalent to
390 C<< default => sub { $_[0]->build_foo } >>.
392 =item auto_deref => 0|1
394 Allows you to automatically dereference ArrayRef and HashRef attributes in list
395 context. In scalar context, the reference is returned (NOT the list length or
396 bucket status). You must specify an appropriate type constraint to use
399 =item lazy_build => 0|1
401 Automatically define lazy => 1 as well as builder => "_build_$attr", clearer =>
402 "clear_$attr', predicate => 'has_$attr' unless they are already defined.
406 =head2 confess error -> BOOM
408 L<Carp/confess> for your convenience.
410 =head2 blessed value -> ClassName | undef
412 L<Scalar::Util/blessed> for your convenience.
418 Importing Mouse will default your class' superclass list to L<Mouse::Object>.
419 You may use L</extends> to replace the superclass list.
423 Please unimport Mouse (C<no Mouse>) so that if someone calls one of the
424 keywords (such as L</extends>) it will break loudly instead breaking subtly.
428 =head2 load_class Class::Name
430 This will load a given C<Class::Name> (or die if it's not loadable).
431 This function can be used in place of tricks like
432 C<eval "use $module"> or using C<require>.
434 =head2 is_class_loaded Class::Name -> Bool
436 Returns whether this class is actually loaded or not. It uses a heuristic which
437 involves checking for the existence of C<$VERSION>, C<@ISA>, and any
438 locally-defined method.
440 =head1 SOURCE CODE ACCESS
442 We have a public git repo:
444 git clone git://jules.scsys.co.uk/gitmo/Mouse.git
448 Shawn M Moore, C<< <sartak at gmail.com> >>
450 Yuval Kogman, C<< <nothingmuch at woobling.org> >>
458 with plenty of code borrowed from L<Class::MOP> and L<Moose>
462 There is a known issue with Mouse on 5.6.2 regarding the @ISA tests. Until
463 this is resolve the minimum version of Perl for Mouse is set to 5.8.0. Patches
464 to resolve these tests are more than welcome.
466 Please report any bugs through RT: email
467 C<bug-mouse at rt.cpan.org>, or browse
468 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Mouse>.
470 =head1 COPYRIGHT AND LICENSE
472 Copyright 2008-2009 Infinity Interactive, Inc.
474 http://www.iinteractive.com/
476 This program is free software; you can redistribute it and/or modify it
477 under the same terms as Perl itself.