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