[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 made a class with 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 ...

  package Person;

  use Moose;

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

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

Loading Moose also enables 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 and 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 for your class. See
the L<Moose::Manual::Types> document to learn more about types.

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 provides 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 API
objects).

=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' );

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'>.

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 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.

  package Person;

  use Moose;

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

  no Moose;

This deletes Moose's sugar 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 in the
future. You will not 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
construction much faster.

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

  __PACKAGE__->meta->make_immutable;

=head2 Immutabilization and C<new()>

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.

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.

=head1 AUTHOR

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

=head1 COPYRIGHT AND LICENSE

Copyright 2008-2009 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
Commit	Line	Data
6c40a460	1	=pod
	2
	3	=head1 NAME
	4
	5	Moose::Manual::Classes - Making your classes use Moose (and subclassing)
	6
	7	=head1 USING MOOSE
	8
	9	Using Moose is very simple, you just C<use Moose>:
	10
	11	package Person;
	12
	13	use Moose;
	14
3ac9038a	15	That's it, you've made a class with Moose!
6c40a460	16
6c40a460	17	There's actually a lot going on here under the hood, so let's step
3ac9038a	18	through it.
6c40a460	19
3ac9038a	20	When you load L<Moose>, a bunch of sugar functions are exported into
6c40a460	21	your class. These include things like C<extends>, C<has>, C<with>, and
	22	more. These functions are what you use to define your class. For
	23	example, you might define an attribute ...
	24
	25	package Person;
	26
	27	use Moose;
	28
	29	has 'ssn' => ( is => 'rw' );
	30
	31	Attributes are described in the L<Moose::Manual::Attributes>
	32	documentation.
	33
dab94063	34	Loading Moose also enables C<strict> and C<warnings> pragmas in your
dab94063	35	class.
6c40a460	36
	37	When you load Moose, your class will become a subclass of
	38	L<Moose::Object>. The L<Moose::Object> class provides a default
dab94063	39	constructor and destructor, as well as object construction helper
6c40a460	40	methods. You can read more about this in the
	41	L<Moose::Manual::Construction> document.
	42
3ac9038a	43	As a convenience, Moose creates a new class type for your class. See
3ac9038a	44	the L<Moose::Manual::Types> document to learn more about types.
6c40a460	45
056348be	46	It also creates a L<Moose::Meta::Class> object for your class. This
	47	metaclass object is now available by calling a C<meta> method on your
	48	class, for example C<< Person->meta >>.
	49
3ac9038a	50	The metaclass object provides an introspection API for your class. It
	51	is also used by Moose itself under the hood to add attributes, define
	52	parent classes, and so on. In fact, all of Moose's sugar does the real
	53	work by calling methods on this metaclass object (and other meta API
	54	objects).
	55
6c40a460	56	=head1 SUBCLASSING
	57
	58	Moose provides a simple sugar function for declaring your parent
	59	classes, C<extends>:
	60
	61	package User;
	62
	63	use Moose;
	64
	65	extends 'Person';
	66
	67	has 'username' => ( is => 'rw' );
	68
0f62a437	69	Note that each call to C<extends> will I<reset> your parents. For
3ac9038a	70	multiple inheritance you must provide all the parents at once,
3ac9038a	71	C<extends 'Foo', 'Bar'>.
6c40a460	72
	73	You can use Moose to extend a non-Moose parent. However, when you do
	74	this, you will inherit the parent class's constructor (assuming it is
	75	also called C<new>). In that case, you will have to take care of
	76	initializing attributes manually, either in the parent's constructor,
3ac9038a	77	or in your subclass, and you will lose a lot of Moose magic.
6c40a460	78
	79	=head1 NO MOOSE
	80
	81	Moose also allows you to remove its sugar functions from your class's
	82	namespace. We recommend that you take advantage of this feature, since
	83	it just makes your classes "cleaner". You can do this by simply adding
	84	C<no Moose> at the end of your module file.
	85
adf8494e	86	package Person;
	87
	88	use Moose;
	89
	90	has 'ssn' => ( is => 'rw' );
	91
	92	no Moose;
	93
3ac9038a	94	This deletes Moose's sugar functions from your class's namespace, so
6c40a460	95	that C<< Person->can('has') >> will no longer return true.
	96
	97	=head1 MAKING IT FASTER
	98
	99	Moose has a feature called "immutabilization" that you can use to
	100	greatly speed up your classes at runtime. However, using it does incur
	101	a cost when your class is first being loaded. When you make your class
3ac9038a	102	immutable you tell Moose that you will not be changing it in the
3ac9038a	103	future. You will not adding any more attributes, methods, roles, etc.
6c40a460	104
3ac9038a	105	This allows Moose to generate code specific to your class. In
	106	particular, it creates an "inline" constructor, making object
	107	construction much faster.
6c40a460	108
	109	To make your class immutable you simply call C<make_immutable> on your
	110	class's metaclass object.
	111
3ac9038a	112	__PACKAGE__->meta->make_immutable;
3ac9038a	113
1a5d5ecd	114	=head2 Immutabilization and C<new()>
	115
	116	If you override C<new()> in your class, then the immutabilization code
	117	will not be able to provide an optimized constructor for your
dab94063	118	class. Instead, you should use a C<BUILD()> method, which will be
dab94063	119	called from the inlined constructor.
1a5d5ecd	120
	121	Alternately, if you really need to provide a different C<new()>, you
	122	can also provide your own immutabilization method. Doing so requires
	123	extending the Moose metaclasses, and is well beyond the scope of this
	124	manual.
	125
6c40a460	126	=head1 AUTHOR
	127
	128	Dave Rolsky E<lt>autarch@urth.orgE<gt>
	129
	130	=head1 COPYRIGHT AND LICENSE
	131
3ac9038a	132	Copyright 2008-2009 by Infinity Interactive, Inc.
6c40a460	133
	134	L<http://www.iinteractive.com>
	135
	136	This library is free software; you can redistribute it and/or modify
	137	it under the same terms as Perl itself.
	138
	139	=cut