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