Comment out alias/excludes warnings for 1.12 release
[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
dab94063 25Moose is built on top of C<Class::MOP>, a meta-object protocol (aka
270df362 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
2d72162f 102=head1 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
d68b26d1 113=item L<Moose::Manual::Unsweetened>
114
6d505648 115Shows two example classes, each written first with Moose and then with
d68b26d1 116"plain old Perl 5".
117
cdebe1c6 118=item L<Moose::Manual::Classes>
270df362 119
cdebe1c6 120How do you make use of Moose in your classes? Now that I'm a Moose,
121how do I subclass something?
270df362 122
cdebe1c6 123=item L<Moose::Manual::Attributes>
270df362 124
cdebe1c6 125Attributes are a core part of the Moose OO system. An attribute is a
126piece of data that an object has. Moose has a lot of attribute-related
127features!
270df362 128
cef2dfda 129=item L<Moose::Manual::Delegation>
130
dab94063 131Delegation is a powerful way to make use of attributes which are
cef2dfda 132themselves objects.
133
cde84af5 134=item L<Moose::Manual::Construction>
270df362 135
cde84af5 136Learn how objects are built in Moose, and in particular about the
0e27121a 137C<BUILD> and C<BUILDARGS> methods. Also covers object destruction
cde84af5 138with C<DEMOLISH>.
270df362 139
cde84af5 140=item L<Moose::Manual::MethodModifiers>
270df362 141
cde84af5 142A method modifier lets you say "before calling method X, do this
143first", or "wrap method X in this code". Method modifiers are
144particularly handy in roles and with attribute accessors.
270df362 145
cde84af5 146=item L<Moose::Manual::Roles>
270df362 147
cde84af5 148A role is something a class does (like "Debuggable" or
149"Printable"). Roles provide a way of adding behavior to classes that
150is orthogonal to inheritance.
270df362 151
cde84af5 152=item L<Moose::Manual::Types>
270df362 153
cde84af5 154Moose's type system lets you strictly define what values an attribute
155can contain.
270df362 156
87817dcf 157=item L<Moose::Manual::MOP>
270df362 158
87817dcf 159Moose's meta API system lets you ask classes about their parents,
160children, methods, attributes, etc.
270df362 161
cde84af5 162=item L<Moose::Manual::MooseX>
270df362 163
dab94063 164This document describes a few of the most useful Moose extensions on
165CPAN.
e03c5ed2 166
0e27121a 167=item L<Moose::Manual::BestPractices>
168
169Moose has a lot of features, and there's definitely more than one way
170to do it. However, we think that picking a subset of these features
171and using them consistently makes everyone's life easier.
172
19440c7c 173=item L<Moose::Manual::FAQ>
174
175Frequently asked questions about Moose.
176
29d05a51 177=item L<Moose::Manual::Contributing>
178
179Interested in hacking on Moose? Read this.
180
181=item L<Moose::Manual::Delta>
182
183This document details backwards-incompatibilities and other major
184changes to Moose.
185
270df362 186=back
187
270df362 188=head1 JUSTIFICATION
189
dab94063 190If you're still asking yourself "Why do I need this?", then this
270df362 191section is for you.
192
193=over 4
194
195=item Another object system!?!?
196
ed5b20d9 197Yes, we know there are many, many ways to build objects in Perl 5,
198many of them based on inside-out objects and other such things. Moose
199is different because it is not a new object system for Perl 5, but
c56e5db4 200instead an extension of the existing object system.
270df362 201
202Moose is built on top of L<Class::MOP>, which is a metaclass system
203for Perl 5. This means that Moose not only makes building normal
204Perl 5 objects better, but it also provides the power of metaclass
205programming.
206
207=item Is this for real? Or is this just an experiment?
208
209Moose is I<based> on the prototypes and experiments Stevan did for the
210Perl 6 meta-model. However, Moose is B<NOT> an experiment or
211prototype; it is for B<real>.
212
213=item Is this ready for use in production?
214
215Yes.
216
c56e5db4 217Moose has been used successfully in production environments by many
270df362 218people and companies. There are Moose applications which have been in
0e27121a 219production with little or no issue now for years. We consider it
220highly stable and we are committed to keeping it stable.
270df362 221
222Of course, in the end, you need to make this call yourself. If you
dab94063 223have any questions or concerns, please feel free to email Stevan or
224the moose@perl.org list, or just stop by irc.perl.org#moose and ask
225away.
270df362 226
227=item Is Moose just Perl 6 in Perl 5?
228
229No. While Moose is very much inspired by Perl 6, it is not itself Perl
0e27121a 2306. Instead, it is an OO system for Perl 5. Stevan built Moose because
270df362 231he was tired of writing the same old boring Perl 5 OO code, and
232drooling over Perl 6 OO. So instead of switching to Ruby, he wrote
233Moose :)
234
235=item Wait, I<post> modern, I thought it was just I<modern>?
236
237Stevan read Larry Wall's talk from the 1999 Linux World entitled
238"Perl, the first postmodern computer language" in which he talks about
239how he picked the features for Perl because he thought they were cool
240and he threw out the ones that he thought sucked. This got him
241thinking about how we have done the same thing in Moose. For Moose, we
242have "borrowed" features from Perl 6, CLOS (LISP), Smalltalk, Java,
243BETA, OCaml, Ruby and more, and the bits we didn't like (cause they
244sucked) we tossed aside. So for this reason (and a few others) Stevan
245has re-dubbed Moose a I<postmodern> object system.
246
247Nuff Said.
248
249=back
250
ed5b20d9 251=head1 AUTHORS
270df362 252
ed5b20d9 253Dave Rolsky E<lt>autarch@urth.orgE<gt>
254
255Stevan Little E<lt>stevan@iinteractive.comE<gt>
270df362 256
257=head1 COPYRIGHT AND LICENSE
258
ed5b20d9 259Copyright 2008-2009 by Infinity Interactive, Inc.
270df362 260
261L<http://www.iinteractive.com>
262
263This library is free software; you can redistribute it and/or modify
264it under the same terms as Perl itself.
265
266=cut