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