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