Checking in changes prior to tagging of version 0.45. Changelog diff is:
[gitmo/Mouse.git] / lib / Mouse.pm
CommitLineData
c3398f5b 1package Mouse;
eb88905f 2use 5.006_002;
3
bc69ee88 4use Mouse::Exporter; # enables strict and warnings
eb88905f 5
81fd550d 6our $VERSION = '0.45';
c3398f5b 7
8bdd9cfc 8use Carp qw(confess);
43523060 9use Scalar::Util qw(blessed);
6d28c5cf 10
01afd8ff 11use Mouse::Util qw(load_class is_class_loaded get_code_package not_supported);
c3398f5b 12
08f7a8db 13use Mouse::Meta::Module;
306290e8 14use Mouse::Meta::Class;
43165725 15use Mouse::Meta::Role;
6d28c5cf 16use Mouse::Meta::Attribute;
c3398f5b 17use Mouse::Object;
6d28c5cf 18use Mouse::Util::TypeConstraints ();
fea36fd2 19
20Mouse::Exporter->setup_import_methods(
21 as_is => [qw(
22 extends with
23 has
24 before after around
25 override super
26 augment inner
27 ),
28 \&Scalar::Util::blessed,
29 \&Carp::confess,
30 ],
2cb8b713 31);
eaad7dab 32
43523060 33
9ee0e57c 34sub extends {
35 Mouse::Meta::Class->initialize(scalar caller)->superclasses(@_);
36 return;
37}
38
39sub with {
40 Mouse::Util::apply_all_roles(scalar(caller), @_);
41 return;
42}
c3398f5b 43
eaad7dab 44sub has {
8bc2760b 45 my $meta = Mouse::Meta::Class->initialize(scalar caller);
1b9e472d 46 my $name = shift;
47
9ee0e57c 48 $meta->throw_error(q{Usage: has 'name' => ( key => value, ... )})
95ecd6f1 49 if @_ % 2; # odd number of arguments
50
9ee0e57c 51 if(ref $name){ # has [qw(foo bar)] => (...)
52 for (@{$name}){
53 $meta->add_attribute($_ => @_);
54 }
55 }
56 else{ # has foo => (...)
34c8209c 57 $meta->add_attribute($name => @_);
9ee0e57c 58 }
59 return;
eaad7dab 60}
61
62sub before {
8bc2760b 63 my $meta = Mouse::Meta::Class->initialize(scalar caller);
eaad7dab 64
65 my $code = pop;
66
67 for (@_) {
68 $meta->add_before_method_modifier($_ => $code);
69 }
9ee0e57c 70 return;
eaad7dab 71}
72
73sub after {
8bc2760b 74 my $meta = Mouse::Meta::Class->initialize(scalar caller);
eaad7dab 75
76 my $code = pop;
77
78 for (@_) {
79 $meta->add_after_method_modifier($_ => $code);
80 }
9ee0e57c 81 return;
eaad7dab 82}
83
84sub around {
8bc2760b 85 my $meta = Mouse::Meta::Class->initialize(scalar caller);
eaad7dab 86
87 my $code = pop;
88
89 for (@_) {
90 $meta->add_around_method_modifier($_ => $code);
91 }
9ee0e57c 92 return;
eaad7dab 93}
94
e6007308 95our $SUPER_PACKAGE;
96our $SUPER_BODY;
97our @SUPER_ARGS;
98
99sub super {
100 # This check avoids a recursion loop - see
101 # t/100_bugs/020_super_recursion.t
85bd3f44 102 return if defined $SUPER_PACKAGE && $SUPER_PACKAGE ne caller();
103 return if !defined $SUPER_BODY;
104 $SUPER_BODY->(@SUPER_ARGS);
e6007308 105}
106
107sub override {
85bd3f44 108 # my($name, $method) = @_;
109 Mouse::Meta::Class->initialize(scalar caller)->add_override_method_modifier(@_);
e6007308 110}
111
768804c0 112our %INNER_BODY;
113our %INNER_ARGS;
114
115sub inner {
116 my $pkg = caller();
117 if ( my $body = $INNER_BODY{$pkg} ) {
118 my $args = $INNER_ARGS{$pkg};
119 local $INNER_ARGS{$pkg};
120 local $INNER_BODY{$pkg};
121 return $body->(@{$args});
122 }
123 else {
124 return;
125 }
126}
127
128sub augment {
129 #my($name, $method) = @_;
130 Mouse::Meta::Class->initialize(scalar caller)->add_augment_method_modifier(@_);
9ee0e57c 131 return;
768804c0 132}
2cb8b713 133
0d6e12be 134sub init_meta {
0d6e12be 135 shift;
136 my %args = @_;
137
138 my $class = $args{for_class}
382b7340 139 or confess("Cannot call init_meta without specifying a for_class");
c9a3c0ed 140
0d6e12be 141 my $base_class = $args{base_class} || 'Mouse::Object';
142 my $metaclass = $args{metaclass} || 'Mouse::Meta::Class';
143
0d6e12be 144 my $meta = $metaclass->initialize($class);
0d6e12be 145
3a63a2e7 146 $meta->add_method(meta => sub{
382b7340 147 return $metaclass->initialize(ref($_[0]) || $_[0]);
3a63a2e7 148 });
149
382b7340 150 $meta->superclasses($base_class)
7efbc77d 151 unless $meta->superclasses;
0d6e12be 152
c9a3c0ed 153 # make a class type for each Mouse class
154 Mouse::Util::TypeConstraints::class_type($class)
155 unless Mouse::Util::TypeConstraints::find_type_constraint($class);
156
0d6e12be 157 return $meta;
158}
159
c3398f5b 1601;
c3398f5b 161__END__
162
163=head1 NAME
164
0fff36e6 165Mouse - Moose minus the antlers
c3398f5b 166
2efecf0c 167=head1 VERSION
168
81fd550d 169This document describes Mouse version 0.45
2efecf0c 170
c3398f5b 171=head1 SYNOPSIS
172
173 package Point;
6caea456 174 use Mouse; # automatically turns on strict and warnings
175
176 has 'x' => (is => 'rw', isa => 'Int');
177 has 'y' => (is => 'rw', isa => 'Int');
178
179 sub clear {
180 my $self = shift;
181 $self->x(0);
182 $self->y(0);
183 }
184
185 package Point3D;
c3398f5b 186 use Mouse;
187
6caea456 188 extends 'Point';
c3398f5b 189
6caea456 190 has 'z' => (is => 'rw', isa => 'Int');
191
8517d2ff 192 after 'clear' => sub {
193 my $self = shift;
194 $self->z(0);
195 };
c3398f5b 196
197=head1 DESCRIPTION
198
6614c108 199L<Moose> is wonderful. B<Use Moose instead of Mouse.>
c3398f5b 200
16913e71 201Unfortunately, Moose has a compile-time penalty. Though significant progress
202has been made over the years, the compile time penalty is a non-starter for
203some very specific applications. If you are writing a command-line application
204or CGI script where startup time is essential, you may not be able to use
205Moose. We recommend that you instead use L<HTTP::Engine> and FastCGI for the
206latter, if possible.
0fff36e6 207
6614c108 208Mouse aims to alleviate this by providing a subset of Moose's functionality,
209faster.
0fff36e6 210
4f74e488 211We're also going as light on dependencies as possible. Mouse currently has
212B<no dependencies> except for testing modules.
d1c1b994 213
1820fffe 214=head2 MOOSE COMPATIBILITY
0fff36e6 215
216Compatibility with Moose has been the utmost concern. Fewer than 1% of the
217tests fail when run against Moose instead of Mouse. Mouse code coverage is also
7e3ed32e 218over 96%. Even the error messages are taken from Moose. The Mouse code just
219runs the test suite 4x faster.
0fff36e6 220
221The idea is that, if you need the extra power, you should be able to run
8e1a28a8 222C<s/Mouse/Moose/g> on your codebase and have nothing break. To that end,
6614c108 223we have written L<Any::Moose> which will act as Mouse unless Moose is loaded,
16913e71 224in which case it will act as Moose. Since Mouse is a little sloppier than
225Moose, if you run into weird errors, it would be worth running:
226
227 ANY_MOOSE=Moose perl your-script.pl
228
229to see if the bug is caused by Mouse. Moose's diagnostics and validation are
230also much better.
0fff36e6 231
4f74e488 232See also L<Mouse::Spec> for compatibility and incompatibility with Moose.
233
9090e5fe 234=head2 MouseX
235
236Please don't copy MooseX code to MouseX. If you need extensions, you really
237should upgrade to Moose. We don't need two parallel sets of extensions!
238
239If you really must write a Mouse extension, please contact the Moose mailing
240list or #moose on IRC beforehand.
241
0fff36e6 242=head1 KEYWORDS
c3398f5b 243
1820fffe 244=head2 C<< $object->meta -> Mouse::Meta::Class >>
c3398f5b 245
246Returns this class' metaclass instance.
247
1820fffe 248=head2 C<< extends superclasses >>
c3398f5b 249
250Sets this class' superclasses.
251
1820fffe 252=head2 C<< before (method|methods) => CodeRef >>
b7a74822 253
8b13ad67 254Installs a "before" method modifier. See L<Moose/before>.
6beb7db6 255
1820fffe 256=head2 C<< after (method|methods) => CodeRef >>
b7a74822 257
8b13ad67 258Installs an "after" method modifier. See L<Moose/after>.
ed940a7a 259
1820fffe 260=head2 C<< around (method|methods) => CodeRef >>
b7a74822 261
8b13ad67 262Installs an "around" method modifier. See L<Moose/around>.
ed940a7a 263
1820fffe 264=head2 C<< has (name|names) => parameters >>
c3398f5b 265
266Adds an attribute (or if passed an arrayref of names, multiple attributes) to
0fff36e6 267this class. Options:
268
269=over 4
270
1820fffe 271=item C<< is => ro|rw|bare >>
0fff36e6 272
b940eb46 273The I<is> option accepts either I<rw> (for read/write), I<ro> (for read
274only) or I<bare> (for nothing). These will create either a read/write accessor
275or a read-only accessor respectively, using the same name as the C<$name> of
0fff36e6 276the attribute.
277
b940eb46 278If you need more control over how your accessors are named, you can
279use the C<reader>, C<writer> and C<accessor> options, however if you
280use those, you won't need the I<is> option.
281
282=item C<< isa => TypeName | ClassName >>
0fff36e6 283
5893ee36 284Provides type checking in the constructor and accessor. The following types are
1820fffe 285supported. Any unknown type is taken to be a class check
286(e.g. C<< isa => 'DateTime' >> would accept only L<DateTime> objects).
5893ee36 287
288 Any Item Bool Undef Defined Value Num Int Str ClassName
289 Ref ScalarRef ArrayRef HashRef CodeRef RegexpRef GlobRef
290 FileHandle Object
291
292For more documentation on type constraints, see L<Mouse::Util::TypeConstraints>.
293
b940eb46 294=item C<< does => RoleName >>
295
296This will accept the name of a role which the value stored in this attribute
297is expected to have consumed.
298
299=item C<< coerce => Bool >>
300
301This will attempt to use coercion with the supplied type constraint to change
302the value passed into any accessors or constructors. You B<must> have supplied
303a type constraint in order for this to work. See L<Moose::Cookbook::Basics::Recipe5>
304for an example.
0fff36e6 305
1820fffe 306=item C<< required => Bool >>
0fff36e6 307
308Whether this attribute is required to have a value. If the attribute is lazy or
309has a builder, then providing a value for the attribute in the constructor is
310optional.
311
1820fffe 312=item C<< init_arg => Str | Undef >>
0fff36e6 313
ca63d17a 314Allows you to use a different key name in the constructor. If undef, the
1820fffe 315attribute can't be passed to the constructor.
0fff36e6 316
1820fffe 317=item C<< default => Value | CodeRef >>
0fff36e6 318
319Sets the default value of the attribute. If the default is a coderef, it will
320be invoked to get the default value. Due to quirks of Perl, any bare reference
321is forbidden, you must wrap the reference in a coderef. Otherwise, all
322instances will share the same reference.
323
1820fffe 324=item C<< lazy => Bool >>
0fff36e6 325
326If specified, the default is calculated on demand instead of in the
327constructor.
328
1820fffe 329=item C<< predicate => Str >>
0fff36e6 330
331Lets you specify a method name for installing a predicate method, which checks
332that the attribute has a value. It will not invoke a lazy default or builder
333method.
334
1820fffe 335=item C<< clearer => Str >>
0fff36e6 336
337Lets you specify a method name for installing a clearer method, which clears
338the attribute's value from the instance. On the next read, lazy or builder will
339be invoked.
340
b940eb46 341=item C<< handles => HashRef|ArrayRef|Regexp >>
0fff36e6 342
343Lets you specify methods to delegate to the attribute. ArrayRef forwards the
344given method names to method calls on the attribute. HashRef maps local method
345names to remote method names called on the attribute. Other forms of
b940eb46 346L</handles>, such as RoleName and CodeRef, are not yet supported.
0fff36e6 347
1820fffe 348=item C<< weak_ref => Bool >>
0fff36e6 349
350Lets you automatically weaken any reference stored in the attribute.
351
6beb7db6 352Use of this feature requires L<Scalar::Util>!
353
1820fffe 354=item C<< trigger => CodeRef >>
844fa049 355
356Any 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.
357
1820fffe 358=item C<< builder => Str >>
0fff36e6 359
360Defines a method name to be called to provide the default value of the
361attribute. C<< builder => 'build_foo' >> is mostly equivalent to
362C<< default => sub { $_[0]->build_foo } >>.
363
1820fffe 364=item C<< auto_deref => Bool >>
0fff36e6 365
366Allows you to automatically dereference ArrayRef and HashRef attributes in list
367context. In scalar context, the reference is returned (NOT the list length or
368bucket status). You must specify an appropriate type constraint to use
369auto_deref.
370
1820fffe 371=item C<< lazy_build => Bool >>
372
373Automatically define the following options:
5253d13d 374
1820fffe 375 has $attr => (
376 # ...
377 lazy => 1
378 builder => "_build_$attr",
379 clearer => "clear_$attr",
380 predicate => "has_$attr",
381 );
5253d13d 382
0fff36e6 383=back
c3398f5b 384
1820fffe 385=head2 C<< confess(message) -> BOOM >>
c3398f5b 386
387L<Carp/confess> for your convenience.
388
1820fffe 389=head2 C<< blessed(value) -> ClassName | undef >>
c3398f5b 390
391L<Scalar::Util/blessed> for your convenience.
392
393=head1 MISC
394
395=head2 import
396
6caea456 397Importing Mouse will default your class' superclass list to L<Mouse::Object>.
c3398f5b 398You may use L</extends> to replace the superclass list.
399
400=head2 unimport
401
0fff36e6 402Please unimport Mouse (C<no Mouse>) so that if someone calls one of the
403keywords (such as L</extends>) it will break loudly instead breaking subtly.
c3398f5b 404
1820fffe 405=head1 SOURCE CODE ACCESS
c3398f5b 406
1820fffe 407We have a public git repository:
c3398f5b 408
2a3e3aa6 409 git clone git://git.moose.perl.org/Mouse.git
c3398f5b 410
1820fffe 411=head1 DEPENDENCIES
262801ef 412
1820fffe 413Perl 5.6.2 or later.
262801ef 414
1820fffe 415=head1 SEE ALSO
e693975f 416
4f74e488 417L<Mouse::Spec>
418
1820fffe 419L<Moose>
e693975f 420
8b13ad67 421L<Moose::Manual>
422
423L<Moose::Cookbook>
424
1820fffe 425L<Class::MOP>
e693975f 426
c817e8f1 427=head1 AUTHORS
c3398f5b 428
1d859d42 429Shawn M Moore E<lt>sartak at gmail.comE<gt>
c3398f5b 430
1d859d42 431Yuval Kogman E<lt>nothingmuch at woobling.orgE<gt>
fc9f8988 432
c817e8f1 433tokuhirom
434
435Yappo
436
ea6dc3a5 437wu-lee
438
434ca269 439Goro Fuji (gfx) E<lt>gfuji at cpan.orgE<gt>
ba55dea1 440
0fff36e6 441with plenty of code borrowed from L<Class::MOP> and L<Moose>
442
c3398f5b 443=head1 BUGS
444
1820fffe 445All complex software has bugs lurking in it, and this module is no exception.
446Please report any bugs to C<bug-mouse at rt.cpan.org>, or through the web
447interface at L<http://rt.cpan.org/Public/Dist/Display.html?Name=Mouse>
c3398f5b 448
449=head1 COPYRIGHT AND LICENSE
450
3ef6ae56 451Copyright 2008-2009 Infinity Interactive, Inc.
452
453http://www.iinteractive.com/
c3398f5b 454
455This program is free software; you can redistribute it and/or modify it
456under the same terms as Perl itself.
457
458=cut
459