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