Add first draft of classes manual document

[gitmo/Moose.git] / lib / Moose / Manual / Classes.pod

=pod

=head1 NAME

Moose::Manual::Classes - Making your classes use Moose (and subclassing)

=head1 USING MOOSE

Using Moose is very simple, you just C<use Moose>:

  package Person;

  use Moose;

That's it, you've now made a Moose-based class!

There's actually a lot going on here under the hood, so let's step
through it. The L<Moose> package does several things when you load it.

When you load Moose, you get a bunch of sugar functions 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 ...

  package Person;

  use Moose;

  has 'ssn' => ( is => 'rw' );

Attributes are described in the L<Moose::Manual::Attributes>
documentation.

Loading Moose in your class also turns on the C<strict> and
C<warnings> pragmas in your class for you.

It also creates a L<Moose::Meta::Class> object for your class. This
metaclass object is now available by calling a C<meta> method on your
class, for example C<< Person->meta >>.

The metaclass object an introspection API for your class. It is also
used by Moose itself under the hood to add attributes, define parent
classes, and so on. In fact, all of Moose's sugar does the real work
by calling methods on this metaclass object (and other meta level
objects).

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
methods. You can read more about this in the
L<Moose::Manual::Construction> document.

As a convenience, Moose creates a new class type with the name of your
class, by calling the C<class_type> function in
L<Moose::Util::Constraints>. See the L<Moose::Manual::Types> document
for more about types.

=head1 SUBCLASSING

Moose provides a simple sugar function for declaring your parent
classes, C<extends>:

  package User;

  use Moose;

  extends 'Person';

  has 'username' => ( is => 'rw' );

When you call extends, Moose takes the class(es) you provide and makes
those the parent of the current class. Note, that each call to
C<extends> will I<reset> your parents, so for multiple inheritance you
should provide all you parents at once, C<extends 'Foo', 'Bar'>.

You can use Moose to extend a non-Moose parent. However, when you do
this, you will inherit the parent class's constructor (assuming it is
also called C<new>). In that case, you will have to take care of
initializing attributes manually, either in the parent's constructor,
or in your subclass, and you will generally lose a lot of Moose magic.

=head1 NO MOOSE

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.

What this does is delete the functions from your class's namespace, so
that C<< Person->can('has') >> will no longer return true.

=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
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,
specifically not adding any attributes, methods, roles, etc.

This allows Moose to generate code specific to your class for its
constructor and other methods, making object construction much
faster. It also makes some of the introspection methods faster as
well.

To make your class immutable you simply call C<make_immutable> on your
class's metaclass object.

=head1 RECOMMENDATIONS

We recommend that you end your Moose class definitions by removing the
Moose sugar and making your class immutable.

  package Person;

  use Moose;

  # extends, roles, attributes, etc.

  # methods

  no Moose;

  __PACKAGE__->meta->make_immutable;

  1;

=head1 AUTHOR

Dave Rolsky E<lt>autarch@urth.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2008 by Infinity Interactive, Inc.

L<http://www.iinteractive.com>

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut