ignore generated recipes
[gitmo/Moose.git] / lib / Moose / Manual.pod
CommitLineData
270df362 1=pod
2
3=head1 NAME
4
cde84af5 5Moose::Manual - What is Moose, and how do I use it?
270df362 6
ed5b20d9 7=head1 WHAT IS MOOSE?
270df362 8
ed5b20d9 9Moose is a I<complete> object system for Perl 5. Consider any modern
10object-oriented language (which Perl 5 definitely isn't). It provides
11keywords for attribute declaration, object construction, inheritance,
12and maybe more. These keywords are part of the language, and you don't
13care how they are implemented.
270df362 14
15Moose aims to do the same thing for Perl 5 OO. We can't actually
10821858 16create new keywords, but we do offer "sugar" that looks a lot like
ed5b20d9 17them. More importantly, with Moose, you I<define your class
18declaratively>, without needing to know about blessed hashrefs,
19accessor methods, and so on.
270df362 20
ed5b20d9 21With Moose, you can concentrate on the I<logical> structure of your
22classes, focusing on "what" rather than "how". A class definition with
23Moose reads like a list of very concise English sentences.
270df362 24
25Moose is built in top of C<Class::MOP>, a meta-object protocol (aka
26MOP). Using the MOP, Moose provides complete introspection for all
27Moose-using classes. This means you can ask classes about their
28attributes, parents, children, methods, etc., all using a well-defined
ed5b20d9 29API. The MOP abstracts away the symbol table, looking at C<@ISA> vars,
30and all the other crufty Perl tricks we know and love(?).
270df362 31
10821858 32Moose is based in large part on the Perl 6 object system, as well as
33drawing on the best ideas from CLOS, Smalltalk, and many other
34languages.
270df362 35
36=head1 WHY MOOSE?
37
10821858 38Moose makes Perl 5 OO both simpler and more powerful. It encapsulates
ed5b20d9 39Perl 5 power tools in high-level declarative APIs which are easy to
40use. Best of all, you don't need to be a wizard to use it.
270df362 41
ed5b20d9 42But if you want to dig about in the guts, Moose lets you do that too,
43by using and extending its powerful introspection API.
270df362 44
45=head1 AN EXAMPLE
46
47 package Person;
48
49 use Moose;
50
51 has 'first_name' => (
52 is => 'rw',
53 isa => 'Str',
54 );
55
56 has 'last_name' => (
57 is => 'rw',
58 isa => 'Str',
59 );
60
0079cb0c 61 no Moose;
62 __PACKAGE__->meta->make_immutable;
63
270df362 64This is a I<complete and usable> class definition!
65
66 package User;
67
68 use DateTime;
69 use Moose;
70
71 extends 'Person';
72
73 has 'password' => (
74 is => 'rw',
f330de33 75 isa => 'Str',
76 );
270df362 77
78 has 'last_login' => (
79 is => 'rw',
80 isa => 'DateTime',
fec9ca3e 81 handles => { 'date_of_last_login' => 'date' },
270df362 82 );
83
84 sub login {
85 my $self = shift;
86 my $pw = shift;
87
88 return 0 if $pw ne $self->password;
89
90 $self->last_login( DateTime->now() );
91
92 return 1;
93 }
94
0079cb0c 95 no Moose;
96 __PACKAGE__->meta->make_immutable;
97
270df362 98We'll leave the line-by-line explanation of this code to other
10821858 99documentation, but you can see how Moose reduces common OO idioms to
100simple declarative constructs.
270df362 101
cde84af5 102=head2 TABLE OF CONTENTS
270df362 103
cde84af5 104This manual consists of a number of documents.
270df362 105
106=over 4
107
cde84af5 108=item L<Moose::Manual::Concepts>
270df362 109
cde84af5 110Introduces Moose concepts, and contrasts them against "old school"
111Perl 5 OO.
270df362 112
cdebe1c6 113=item L<Moose::Manual::Classes>
270df362 114
cdebe1c6 115How do you make use of Moose in your classes? Now that I'm a Moose,
116how do I subclass something?
270df362 117
cdebe1c6 118=item L<Moose::Manual::Attributes>
270df362 119
cdebe1c6 120Attributes are a core part of the Moose OO system. An attribute is a
121piece of data that an object has. Moose has a lot of attribute-related
122features!
270df362 123
cef2dfda 124=item L<Moose::Manual::Delegation>
125
126Delegation is a powerful way to make use of attribute which are
127themselves objects.
128
cde84af5 129=item L<Moose::Manual::Construction>
270df362 130
cde84af5 131Learn how objects are built in Moose, and in particular about the
0e27121a 132C<BUILD> and C<BUILDARGS> methods. Also covers object destruction
cde84af5 133with C<DEMOLISH>.
270df362 134
cde84af5 135=item L<Moose::Manual::MethodModifiers>
270df362 136
cde84af5 137A method modifier lets you say "before calling method X, do this
138first", or "wrap method X in this code". Method modifiers are
139particularly handy in roles and with attribute accessors.
270df362 140
cde84af5 141=item L<Moose::Manual::Roles>
270df362 142
cde84af5 143A role is something a class does (like "Debuggable" or
144"Printable"). Roles provide a way of adding behavior to classes that
145is orthogonal to inheritance.
270df362 146
cde84af5 147=item L<Moose::Manual::Types>
270df362 148
cde84af5 149Moose's type system lets you strictly define what values an attribute
150can contain.
270df362 151
87817dcf 152=item L<Moose::Manual::MOP>
270df362 153
87817dcf 154Moose's meta API system lets you ask classes about their parents,
155children, methods, attributes, etc.
270df362 156
cde84af5 157=item L<Moose::Manual::MooseX>
270df362 158
cde84af5 159This document shows a few of the most useful Moose extensions on CPAN.
e03c5ed2 160
0e27121a 161=item L<Moose::Manual::BestPractices>
162
163Moose has a lot of features, and there's definitely more than one way
164to do it. However, we think that picking a subset of these features
165and using them consistently makes everyone's life easier.
166
270df362 167=back
168
270df362 169=head1 JUSTIFICATION
170
171If you're still still asking yourself "Why do I need this?", then this
172section is for you.
173
174=over 4
175
176=item Another object system!?!?
177
ed5b20d9 178Yes, we know there are many, many ways to build objects in Perl 5,
179many of them based on inside-out objects and other such things. Moose
180is different because it is not a new object system for Perl 5, but
c56e5db4 181instead an extension of the existing object system.
270df362 182
183Moose is built on top of L<Class::MOP>, which is a metaclass system
184for Perl 5. This means that Moose not only makes building normal
185Perl 5 objects better, but it also provides the power of metaclass
186programming.
187
188=item Is this for real? Or is this just an experiment?
189
190Moose is I<based> on the prototypes and experiments Stevan did for the
191Perl 6 meta-model. However, Moose is B<NOT> an experiment or
192prototype; it is for B<real>.
193
194=item Is this ready for use in production?
195
196Yes.
197
c56e5db4 198Moose has been used successfully in production environments by many
270df362 199people and companies. There are Moose applications which have been in
0e27121a 200production with little or no issue now for years. We consider it
201highly stable and we are committed to keeping it stable.
270df362 202
203Of course, in the end, you need to make this call yourself. If you
204have any questions or concerns, please feel free to email Stevan, the
205moose@perl.org list, or just stop by irc.perl.org#moose and ask away.
206
207=item Is Moose just Perl 6 in Perl 5?
208
209No. While Moose is very much inspired by Perl 6, it is not itself Perl
0e27121a 2106. Instead, it is an OO system for Perl 5. Stevan built Moose because
270df362 211he was tired of writing the same old boring Perl 5 OO code, and
212drooling over Perl 6 OO. So instead of switching to Ruby, he wrote
213Moose :)
214
215=item Wait, I<post> modern, I thought it was just I<modern>?
216
217Stevan read Larry Wall's talk from the 1999 Linux World entitled
218"Perl, the first postmodern computer language" in which he talks about
219how he picked the features for Perl because he thought they were cool
220and he threw out the ones that he thought sucked. This got him
221thinking about how we have done the same thing in Moose. For Moose, we
222have "borrowed" features from Perl 6, CLOS (LISP), Smalltalk, Java,
223BETA, OCaml, Ruby and more, and the bits we didn't like (cause they
224sucked) we tossed aside. So for this reason (and a few others) Stevan
225has re-dubbed Moose a I<postmodern> object system.
226
227Nuff Said.
228
229=back
230
ed5b20d9 231=head1 AUTHORS
270df362 232
ed5b20d9 233Dave Rolsky E<lt>autarch@urth.orgE<gt>
234
235Stevan Little E<lt>stevan@iinteractive.comE<gt>
270df362 236
237=head1 COPYRIGHT AND LICENSE
238
ed5b20d9 239Copyright 2008-2009 by Infinity Interactive, Inc.
270df362 240
241L<http://www.iinteractive.com>
242
243This library is free software; you can redistribute it and/or modify
244it under the same terms as Perl itself.
245
246=cut