clean up and add NAME sections
[gitmo/Moo.git] / lib / Moo.pm
1 package Moo;
2
3 use strictures 1;
4 use Moo::_Utils;
5
6 our $VERSION = '0.009001'; # 0.9.1
7 $VERSION = eval $VERSION;
8
9 our %MAKERS;
10
11 sub import {
12   my $target = caller;
13   my $class = shift;
14   strictures->import;
15   return if $MAKERS{$target}; # already exported into this package
16   *{_getglob("${target}::extends")} = sub {
17     _load_module($_) for @_;
18     *{_getglob("${target}::ISA")} = \@_;
19   };
20   *{_getglob("${target}::with")} = sub {
21     require Moo::Role;
22     die "Only one role supported at a time by with" if @_ > 1;
23     Moo::Role->apply_role_to_package($target, $_[0]);
24   };
25   $MAKERS{$target} = {};
26   *{_getglob("${target}::has")} = sub {
27     my ($name, %spec) = @_;
28     ($MAKERS{$target}{accessor} ||= do {
29       require Method::Generate::Accessor;
30       Method::Generate::Accessor->new
31     })->generate_method($target, $name, \%spec);
32     $class->_constructor_maker_for($target)
33           ->register_attribute_specs($name, \%spec);
34   };
35   foreach my $type (qw(before after around)) {
36     *{_getglob "${target}::${type}"} = sub {
37       require Class::Method::Modifiers;
38       _install_modifier($target, $type, @_);
39     };
40   }
41   {
42     no strict 'refs';
43     @{"${target}::ISA"} = do {
44       require Moo::Object; ('Moo::Object');
45     } unless @{"${target}::ISA"};
46   }
47 }
48
49 sub _constructor_maker_for {
50   my ($class, $target) = @_;
51   return unless $MAKERS{$target};
52   $MAKERS{$target}{constructor} ||= do {
53     require Method::Generate::Constructor;
54     Method::Generate::Constructor
55       ->new(
56         package => $target,
57         accessor_generator => do {
58           require Method::Generate::Accessor;
59           Method::Generate::Accessor->new;
60         }
61       )
62       ->install_delayed
63       ->register_attribute_specs(do {
64         my @spec;
65         # using the -last- entry in @ISA means that classes created by
66         # Role::Tiny as N roles + superclass will still get the attributes
67         # from the superclass
68         if (my $super = do { no strict 'refs'; ${"${target}::ISA"}[-1] }) {
69           if (my $con = $MAKERS{$super}{constructor}) {
70             @spec = %{$con->all_attribute_specs};
71           }
72         }
73         @spec;
74       });
75   }
76 }
77
78 1;
79
80 =pod
81
82 =head1 NAME
83
84 Moo - Minimalist Object Orientation (with Moose compatiblity)
85
86 =head1 SYNOPSIS
87
88  package Cat::Food;
89
90  use Moo;
91  use Sub::Quote;
92
93  sub feed_lion {
94    my $self = shift;
95    my $amount = shift || 1;
96
97    $self->pounds( $self->pounds - $amount );
98  }
99
100  has taste => (
101    is => 'ro',
102  );
103
104  has brand => (
105    is  => 'ro',
106    isa => sub {
107      die "Only SWEET-TREATZ supported!" unless $_[0] eq 'SWEET-TREATZ'
108    },
109 );
110
111  has pounds => (
112    is  => 'rw',
113    isa => quote_sub q{ die "$_[0] is too much cat food!" unless $_[0] < 15 },
114  );
115
116  1;
117
118 and else where
119
120  my $full = Cat::Food->new(
121     taste  => 'DELICIOUS.',
122     brand  => 'SWEET-TREATZ',
123     pounds => 10,
124  );
125
126  $full->feed_lion;
127
128  say $full->pounds;
129
130 =head1 DESCRIPTION
131
132 This module is an extremely light-weight, high-performance L<Moose> replacement.
133 It also avoids depending on any XS modules to allow simple deployments.  The
134 name C<Moo> is based on the idea that it provides almost -but not quite- two
135 thirds of L<Moose>.
136
137 Unlike C<Mouse> this module does not aim at full L<Moose> compatibility.  See
138 L</INCOMPATIBILITIES> for more details.
139
140 =head1 IMPORTED METHODS
141
142 =head2 new
143
144  Foo::Bar->new( attr1 => 3 );
145
146 or
147
148  Foo::Bar->new({ attr1 => 3 });
149
150 =head2 BUILDARGS
151
152 This feature from Moose is not yet supported.
153
154 =head2 BUILDALL
155
156 Don't override (or probably even call) this method.  Instead, you can define
157 a C<BUILD> method on your class and the constructor will automatically call the
158 C<BUILD> method from parent down to child after the object has been
159 instantiated.  Typically this is used for object validation or possibly logging.
160
161 =head2 does
162
163  if ($foo->does('Some::Role1')) {
164    ...
165  }
166
167 Returns true if the object composes in the passed role.
168
169 =head1 IMPORTED SUBROUTINES
170
171 =head2 extends
172
173  extends 'Parent::Class';
174
175 Declares base class. Multiple superclasses can be passed for multiple
176 inheritance (but please use roles instead).
177
178 Calling extends more than once will REPLACE your superclasses, not add to
179 them like 'use base' would.
180
181 =head2 with
182
183  with 'Some::Role1';
184  with 'Some::Role2';
185
186 Composes a L<Role::Tiny> into current class.  Only one role may be composed in
187 at a time to allow the code to remain as simple as possible.
188
189 =head2 has
190
191  has attr => (
192    is => 'ro',
193  );
194
195 Declares an attribute for the class.
196
197 The options for C<has> are as follows:
198
199 =over 2
200
201 =item * is
202
203 B<required>, must be C<ro> or C<rw>.  Unsurprisingly, C<ro> generates an
204 accessor that will not respond to arguments; to be clear: a setter only. C<rw>
205 will create a perlish getter/setter.
206
207 =item * isa
208
209 Takes a coderef which is meant to validate the attribute.  Unlike L<Moose> Moo
210 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
211 one should do
212
213  isa => quote_sub q{
214    die "$_[0] is not a number!" unless looks_like_number $_[0]
215  },
216
217 L<Sub::Quote aware|/SUB QUOTE AWARE>
218
219 =item * coerce
220
221 This Moose feature is not yet supported
222
223 =begin hide
224
225 Takes a coderef which is meant to coerce the attribute.  The basic idea is to
226 do something like the following:
227
228  coerce => quote_sub q{
229    $_[0] + 1 unless $_[0] % 2
230  },
231
232 L<Sub::Quote aware|/SUB QUOTE AWARE>
233
234 =end hide
235
236 =item * trigger
237
238 Takes a coderef which will get called any time the attribute is set. Coderef
239 will be invoked against the object with the new value as an argument.
240
241 Note that Moose also passes the old value, if any; this feature is not yet
242 supported.
243
244 L<Sub::Quote aware|/SUB QUOTE AWARE>
245
246 =item * default
247
248 Takes a coderef which will get called with $self as its only argument
249 to populate an attribute if no value is supplied to the constructor - or
250 if the attribute is lazy, when the attribute is first retrieved if no
251 value has yet been provided.
252
253 Note that if your default is fired during new() there is no guarantee that
254 other attributes have been populated yet so you should not rely on their
255 existence.
256
257 L<Sub::Quote aware|/SUB QUOTE AWARE>
258
259 =item * predicate
260
261 Takes a method name which will return true if an attribute has a value.
262
263 A common example of this would be to call it C<has_$foo>, implying that the
264 object has a C<$foo> set.
265
266 =item * builder
267
268 Takes a method name which will be called to create the attribute - functions
269 exactly like default except that instead of calling
270
271   $default->($self);
272
273 Moo will call
274
275   $self->$builder;
276
277 =item * clearer
278
279 Takes a method name which will clear the attribute.
280
281 =item * lazy
282
283 B<Boolean>.  Set this if you want values for the attribute to be grabbed
284 lazily.  This is usually a good idea if you have a L</builder> which requires
285 another attribute to be set.
286
287 =item * required
288
289 B<Boolean>.  Set this if the attribute must be passed on instantiation.
290
291 =item * weak_ref
292
293 B<Boolean>.  Set this if you want the reference that the attribute contains to
294 be weakened; use this when circular references are possible, which will cause
295 leaks.
296
297 =item * init_arg
298
299 Takes the name of the key to look for at instantiation time of the object.  A
300 common use of this is to make an underscored attribute have a non-underscored
301 initialization name. C<undef> means that passing the value in on instantiation
302
303 =back
304
305 =head2 before
306
307  before foo => sub { ... };
308
309 See L<< Class::Method::Modifiers/before method(s) => sub { ... } >> for full
310 documentation.
311
312 =head2 around
313
314  around foo => sub { ... };
315
316 See L<< Class::Method::Modifiers/around method(s) => sub { ... } >> for full
317 documentation.
318
319 =head2 after
320
321  after foo => sub { ... };
322
323 See L<< Class::Method::Modifiers/after method(s) => sub { ... } >> for full
324 documentation.
325
326 =head1 SUB QUOTE AWARE
327
328 L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
329 giving us a handy, XS-free speed boost.  Any option that is L<Sub::Quote>
330 aware can take advantage of this.
331
332 =head1 INCOMPATIBILITIES WITH MOOSE
333
334 You can only compose one role at a time.  If your application is large or
335 complex enough to warrant complex composition, you wanted L<Moose>.
336
337 There is no complex type system.  C<isa> is verified with a coderef, if you
338 need complex types, just make a library of coderefs, or better yet, functions
339 that return quoted subs.
340
341 C<initializer> is not supported in core since the author considers it to be a
342 bad idea but may be supported by an extension in future.
343
344 There is no meta object.  If you need this level of complexity you wanted
345 L<Moose> - Moo succeeds at being small because it explicitly does not
346 provide a metaprotocol.
347
348 No support for C<super>, C<override>, C<inner>, or C<augment> - override can
349 be handled by around albeit with a little more typing, and the author considers
350 augment to be a bad idea.
351
352 L</default> only supports coderefs, because doing otherwise is usually a
353 mistake anyway.
354
355 C<lazy_build> is not supported per se, but of course it will work if you
356 manually set all the options it implies.
357
358 C<auto_deref> is not supported since the author considers it a bad idea.
359
360 C<documentation> is not supported since it's a very poor replacement for POD.