Remove blessed from Mouse::Object because it's not used
[gitmo/Mouse.git] / lib / Mouse.pm
CommitLineData
9baf5d6b 1#!/usr/bin/env perl
c3398f5b 2package Mouse;
3use strict;
4use warnings;
5
5c557f4f 6our $VERSION = '0.07';
126765f0 7use 5.006;
c3398f5b 8
9use Sub::Exporter;
10use Carp 'confess';
11use Scalar::Util 'blessed';
12
306290e8 13use Mouse::Meta::Attribute;
14use Mouse::Meta::Class;
c3398f5b 15use Mouse::Object;
d60c78b9 16use Mouse::TypeRegistry;
c3398f5b 17
18do {
19 my $CALLER;
20
21 my %exports = (
22 meta => sub {
306290e8 23 my $meta = Mouse::Meta::Class->initialize($CALLER);
c3398f5b 24 return sub { $meta };
25 },
26
27 extends => sub {
28 my $caller = $CALLER;
29 return sub {
30 $caller->meta->superclasses(@_);
31 };
32 },
33
34 has => sub {
724c77c0 35 my $caller = $CALLER;
36
c3398f5b 37 return sub {
724c77c0 38 my $meta = $caller->meta;
39
c3398f5b 40 my $names = shift;
41 $names = [$names] if !ref($names);
42
43 for my $name (@$names) {
1bfebf5f 44 if ($name =~ s/^\+//) {
724c77c0 45 Mouse::Meta::Attribute->clone_parent($meta, $name, @_);
1bfebf5f 46 }
47 else {
724c77c0 48 Mouse::Meta::Attribute->create($meta, $name, @_);
1bfebf5f 49 }
c3398f5b 50 }
51 };
52 },
53
54 confess => sub {
b17094ce 55 return \&confess;
c3398f5b 56 },
57
58 blessed => sub {
b17094ce 59 return \&blessed;
c3398f5b 60 },
8517d2ff 61
62 before => sub {
50dc6ee5 63 my $caller = $CALLER;
64
65 return sub {
66 my $code = pop;
67 my $class = $caller->meta;
68
69 for (@_) {
70 $class->add_before_method_modifier($_ => $code);
71 }
72 };
8517d2ff 73 },
74
75 after => sub {
50dc6ee5 76 my $caller = $CALLER;
77
78 return sub {
79 my $code = pop;
80 my $class = $caller->meta;
81
82 for (@_) {
83 $class->add_after_method_modifier($_ => $code);
84 }
85 };
8517d2ff 86 },
87
88 around => sub {
50dc6ee5 89 my $caller = $CALLER;
90
91 return sub {
92 my $code = pop;
93 my $class = $caller->meta;
94
95 for (@_) {
96 $class->add_around_method_modifier($_ => $code);
97 }
98 };
8517d2ff 99 },
3ab0ee8f 100
101 with => sub {
102 my $caller = $CALLER;
103
104 return sub {
105 my $role = shift;
106 my $class = $caller->meta;
107
e5f31f1f 108 confess "Mouse::Role only supports 'with' on individual roles at a time" if @_;
e7dff5dc 109
3ab0ee8f 110 Mouse::load_class($role);
da0c885d 111 $role->meta->apply($class);
3ab0ee8f 112 };
113 },
c3398f5b 114 );
115
116 my $exporter = Sub::Exporter::build_exporter({
117 exports => \%exports,
118 groups => { default => [':all'] },
119 });
120
121 sub import {
122 $CALLER = caller;
123
124 strict->import;
125 warnings->import;
126
306290e8 127 my $meta = Mouse::Meta::Class->initialize($CALLER);
ca73a208 128 $meta->superclasses('Mouse::Object')
129 unless $meta->superclasses;
c3398f5b 130
131 goto $exporter;
132 }
133
134 sub unimport {
135 my $caller = caller;
136
137 no strict 'refs';
138 for my $keyword (keys %exports) {
139 next if $keyword eq 'meta'; # we don't delete this one
140 delete ${ $caller . '::' }{$keyword};
141 }
142 }
143};
144
145sub load_class {
146 my $class = shift;
262801ef 147
9694b71b 148 if (ref($class) || !defined($class) || !length($class)) {
149 my $display = defined($class) ? $class : 'undef';
150 confess "Invalid class name ($display)";
151 }
c3398f5b 152
2a674d23 153 return 1 if is_class_loaded($class);
154
c3398f5b 155 (my $file = "$class.pm") =~ s{::}{/}g;
156
157 eval { CORE::require($file) };
2a674d23 158 confess "Could not load class ($class) because : $@" if $@;
c3398f5b 159
160 return 1;
161}
162
2a674d23 163sub is_class_loaded {
164 my $class = shift;
165
7ecc2123 166 return 0 if ref($class) || !defined($class) || !length($class);
167
bf134049 168 # walk the symbol table tree to avoid autovififying
169 # \*{${main::}{"Foo::"}} == \*main::Foo::
170
171 my $pack = \*::;
172 foreach my $part (split('::', $class)) {
173 return 0 unless exists ${$$pack}{"${part}::"};
174 $pack = \*{${$$pack}{"${part}::"}};
2a674d23 175 }
bf134049 176
177 # check for $VERSION or @ISA
178 return 1 if exists ${$$pack}{VERSION}
179 && defined *{${$$pack}{VERSION}}{SCALAR};
180 return 1 if exists ${$$pack}{ISA}
181 && defined *{${$$pack}{ISA}}{ARRAY};
182
183 # check for any method
184 foreach ( keys %{$$pack} ) {
185 next if substr($_, -2, 2) eq '::';
186 return 1 if defined *{${$$pack}{$_}}{CODE};
187 }
188
189 # fail
2a674d23 190 return 0;
191}
192
c3398f5b 1931;
194
195__END__
196
197=head1 NAME
198
0fff36e6 199Mouse - Moose minus the antlers
c3398f5b 200
c3398f5b 201=head1 SYNOPSIS
202
203 package Point;
6caea456 204 use Mouse; # automatically turns on strict and warnings
205
206 has 'x' => (is => 'rw', isa => 'Int');
207 has 'y' => (is => 'rw', isa => 'Int');
208
209 sub clear {
210 my $self = shift;
211 $self->x(0);
212 $self->y(0);
213 }
214
215 package Point3D;
c3398f5b 216 use Mouse;
217
6caea456 218 extends 'Point';
c3398f5b 219
6caea456 220 has 'z' => (is => 'rw', isa => 'Int');
221
8517d2ff 222 after 'clear' => sub {
223 my $self = shift;
224 $self->z(0);
225 };
c3398f5b 226
227=head1 DESCRIPTION
228
0fff36e6 229L<Moose> is wonderful.
c3398f5b 230
0fff36e6 231Unfortunately, it's a little slow. Though significant progress has been made
232over the years, the compile time penalty is a non-starter for some
233applications.
234
235Mouse aims to alleviate this by providing a subset of Moose's
236functionality, faster. In particular, L<Moose/has> is missing only a few
237expert-level features.
238
239=head2 MOOSE COMPAT
240
241Compatibility with Moose has been the utmost concern. Fewer than 1% of the
242tests fail when run against Moose instead of Mouse. Mouse code coverage is also
faa5cb70 243over 97%. Even the error messages are taken from Moose. The Mouse code just
8e1a28a8 244runs the test suite 3x-4x faster.
0fff36e6 245
246The idea is that, if you need the extra power, you should be able to run
8e1a28a8 247C<s/Mouse/Moose/g> on your codebase and have nothing break. To that end,
248nothingmuch has written L<Squirrel> (part of this distribution) which will act
249as Mouse unless Moose is loaded, in which case it will act as Moose.
0fff36e6 250
251Mouse also has the blessings of Moose's author, stevan.
252
253=head2 MISSING FEATURES
254
0fff36e6 255=head3 Roles
256
faa5cb70 257We're working on fixing this one! stevan has suggested an implementation
258strategy. Mouse currently ignores methods, so that needs to be fixed next.
259Roles that consist entirely of attributes may be usable in this very version.
0fff36e6 260
261=head3 Complex types
262
263User-defined type constraints and parameterized types may be implemented. Type
264coercions probably not (patches welcome).
265
266=head3 Bootstrapped meta world
267
268Very handy for extensions to the MOP. Not pressing, but would be nice to have.
269
270=head3 Modification of attribute metaclass
271
272When you declare an attribute with L</has>, you get the inlined accessors
273installed immediately. Modifying the attribute metaclass, even if possible,
274does nothing.
275
276=head3 Lots more..
277
278MouseX?
279
280=head1 KEYWORDS
c3398f5b 281
306290e8 282=head2 meta -> Mouse::Meta::Class
c3398f5b 283
284Returns this class' metaclass instance.
285
286=head2 extends superclasses
287
288Sets this class' superclasses.
289
b7a74822 290=head2 before (method|methods) => Code
291
292Installs a "before" method modifier. See L<Moose/before> or
293L<Class::Method::Modifiers/before>.
294
295=head2 after (method|methods) => Code
296
297Installs an "after" method modifier. See L<Moose/after> or
298L<Class::Method::Modifiers/after>.
299
300=head2 around (method|methods) => Code
301
302Installs an "around" method modifier. See L<Moose/around> or
303L<Class::Method::Modifiers/around>.
304
c3398f5b 305=head2 has (name|names) => parameters
306
307Adds an attribute (or if passed an arrayref of names, multiple attributes) to
0fff36e6 308this class. Options:
309
310=over 4
311
312=item is => ro|rw
313
314If specified, inlines a read-only/read-write accessor with the same name as
315the attribute.
316
317=item isa => TypeConstraint
318
319Provides basic type checking in the constructor and accessor. Basic types such
320as C<Int>, C<ArrayRef>, C<Defined> are supported. Any unknown type is taken to
321be a class check (e.g. isa => 'DateTime' would accept only L<DateTime>
322objects).
323
324=item required => 0|1
325
326Whether this attribute is required to have a value. If the attribute is lazy or
327has a builder, then providing a value for the attribute in the constructor is
328optional.
329
330=item init_arg => Str
331
332Allows you to use a different key name in the constructor.
333
334=item default => Value | CodeRef
335
336Sets the default value of the attribute. If the default is a coderef, it will
337be invoked to get the default value. Due to quirks of Perl, any bare reference
338is forbidden, you must wrap the reference in a coderef. Otherwise, all
339instances will share the same reference.
340
341=item lazy => 0|1
342
343If specified, the default is calculated on demand instead of in the
344constructor.
345
346=item predicate => Str
347
348Lets you specify a method name for installing a predicate method, which checks
349that the attribute has a value. It will not invoke a lazy default or builder
350method.
351
352=item clearer => Str
353
354Lets you specify a method name for installing a clearer method, which clears
355the attribute's value from the instance. On the next read, lazy or builder will
356be invoked.
357
358=item handles => HashRef|ArrayRef
359
360Lets you specify methods to delegate to the attribute. ArrayRef forwards the
361given method names to method calls on the attribute. HashRef maps local method
362names to remote method names called on the attribute. Other forms of
363L</handles>, such as regular expression and coderef, are not yet supported.
364
365=item weak_ref => 0|1
366
367Lets you automatically weaken any reference stored in the attribute.
368
844fa049 369=item trigger => CodeRef
370
371Any 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.
372
373Mouse 0.05 supported more complex triggers, but this behavior is now deprecated.
0fff36e6 374
375=item builder => Str
376
377Defines a method name to be called to provide the default value of the
378attribute. C<< builder => 'build_foo' >> is mostly equivalent to
379C<< default => sub { $_[0]->build_foo } >>.
380
381=item auto_deref => 0|1
382
383Allows you to automatically dereference ArrayRef and HashRef attributes in list
384context. In scalar context, the reference is returned (NOT the list length or
385bucket status). You must specify an appropriate type constraint to use
386auto_deref.
387
388=back
c3398f5b 389
390=head2 confess error -> BOOM
391
392L<Carp/confess> for your convenience.
393
394=head2 blessed value -> ClassName | undef
395
396L<Scalar::Util/blessed> for your convenience.
397
398=head1 MISC
399
400=head2 import
401
6caea456 402Importing Mouse will default your class' superclass list to L<Mouse::Object>.
c3398f5b 403You may use L</extends> to replace the superclass list.
404
405=head2 unimport
406
0fff36e6 407Please unimport Mouse (C<no Mouse>) so that if someone calls one of the
408keywords (such as L</extends>) it will break loudly instead breaking subtly.
c3398f5b 409
410=head1 FUNCTIONS
411
412=head2 load_class Class::Name
413
6caea456 414This will load a given C<Class::Name> (or die if it's not loadable).
c3398f5b 415This function can be used in place of tricks like
416C<eval "use $module"> or using C<require>.
417
262801ef 418=head2 is_class_loaded Class::Name -> Bool
419
420Returns whether this class is actually loaded or not. It uses a heuristic which
421involves checking for the existence of C<$VERSION>, C<@ISA>, and any
422locally-defined method.
423
c3398f5b 424=head1 AUTHOR
425
426Shawn M Moore, C<< <sartak at gmail.com> >>
427
0fff36e6 428with plenty of code borrowed from L<Class::MOP> and L<Moose>
429
c3398f5b 430=head1 BUGS
431
432No known bugs.
433
434Please report any bugs through RT: email
435C<bug-mouse at rt.cpan.org>, or browse
436L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Mouse>.
437
438=head1 COPYRIGHT AND LICENSE
439
440Copyright 2008 Shawn M Moore.
441
442This program is free software; you can redistribute it and/or modify it
443under the same terms as Perl itself.
444
445=cut
446