-=pod
+package Moose::Manual::Classes;
+
+# ABSTRACT: Making your classes use Moose (and subclassing)
-=head1 NAME
+__END__
-Moose::Manual::Classes - Making your classes use Moose (and subclassing)
+=pod
=head1 USING MOOSE
There's actually a lot going on here under the hood, so let's step
through it.
-When you load L<Moose>, a bunch of sugar functions are exported into
-your class. These include things like C<extends>, C<has>, C<with>, and
-more. These functions are what you use to define your class. For
-example, you might define an attribute ...
+When you load L<Moose>, a bunch of sugar functions are exported into your
+class, such as C<extends>, C<has>, C<with>, and more. These functions are what
+you use to define your class. For example, you might define an attribute ...
package Person;
Attributes are described in the L<Moose::Manual::Attributes>
documentation.
-Loading Moose also turns enables C<strict> and C<warnings> pragmas in
-your class.
+Loading Moose also enables the C<strict> and C<warnings> pragmas in your
+class.
When you load Moose, your class will become a subclass of
L<Moose::Object>. The L<Moose::Object> class provides a default
-constructor, destructor, as well as object construction helper
+constructor and destructor, as well as object construction helper
methods. You can read more about this in the
L<Moose::Manual::Construction> document.
has 'username' => ( is => 'rw' );
-ote, that each call to C<extends> will I<reset> your parents. For
+Note that each call to C<extends> will I<reset> your parents. For
multiple inheritance you must provide all the parents at once,
C<extends 'Foo', 'Bar'>.
initializing attributes manually, either in the parent's constructor,
or in your subclass, and you will lose a lot of Moose magic.
-=head1 NO MOOSE
+See the L<MooseX::NonMoose> module on CPAN if you're interested in extending
+non-Moose parent classes with Moose child classes.
+
+=head1 CLEANING UP MOOSE DROPPINGS
+
+Moose exports a number of functions into your class. It's a good idea to
+remove these sugar functions from your class's namespace, so that C<<
+Person->can('has') >> will no longer return true.
+
+There are several ways to do this. We recommend using L<namespace::autoclean>,
+a CPAN module. Not only will it remove Moose exports, it will also remove
+any other exports.
+
+ package Person;
+
+ use namespace::autoclean;
+
+ use Moose;
+
+If you absolutely can't use a CPAN module (but can use Moose?), you can write
+C<no Moose> at the end of your class. This will remove any Moose exports in
+your class.
-Moose also allows you to remove its sugar functions from your class's
-namespace. We recommend that you take advantage of this feature, since
-it just makes your classes "cleaner". You can do this by simply adding
-C<no Moose> at the end of your module file.
+ package Person;
-This deletes Moose's sugar functions from your class's namespace, so
-that C<< Person->can('has') >> will no longer return true.
+ use Moose;
+
+ has 'ssn' => ( is => 'rw' );
+
+ no Moose;
=head1 MAKING IT FASTER
Moose has a feature called "immutabilization" that you can use to
-greatly speed up your classes at runtime. However, using it does incur
+greatly speed up your classes at runtime. However, using it incurs
a cost when your class is first being loaded. When you make your class
immutable you tell Moose that you will not be changing it in the
-future. You will not adding any more attributes, methods, roles, etc.
+future. You will not be adding any more attributes, methods, roles, etc.
This allows Moose to generate code specific to your class. In
particular, it creates an "inline" constructor, making object
__PACKAGE__->meta->make_immutable;
-=head1 AUTHOR
-
-Dave Rolsky E<lt>autarch@urth.orgE<gt>
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2008-2009 by Infinity Interactive, Inc.
+=head2 Immutabilization and C<new()>
-L<http://www.iinteractive.com>
+If you override C<new()> in your class, then the immutabilization code
+will not be able to provide an optimized constructor for your
+class. Instead, you should use a C<BUILD()> method, which will be
+called from the inlined constructor.
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
+Alternately, if you really need to provide a different C<new()>, you
+can also provide your own immutabilization method. Doing so requires
+extending the Moose metaclasses, and is well beyond the scope of this
+manual.
=cut
projects / gitmo/Moose.git / blobdiff