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 | |
7 | =head1 WHAT IS MOOSE? |
8 | |
9 | Moose is a I<complete> object system for Perl 5. If you've used a |
10821858 |
10 | modern object-oriented language (which Perl 5 definitely isn't), you |
11 | know they provide keywords for attribute declaration, object |
12 | construction, and inheritance. These keywords are part of the |
13 | language, and you don't care how they are implemented. |
270df362 |
14 | |
15 | Moose aims to do the same thing for Perl 5 OO. We can't actually |
10821858 |
16 | create new keywords, but we do offer "sugar" that looks a lot like |
9f0ce58b |
17 | them. More importantly, with Moose, you I<declaratively define> your |
10821858 |
18 | class, without needing to know about blessed hashrefs, accessor |
19 | methods, and so on. |
270df362 |
20 | |
cde84af5 |
21 | Moose helps you define the I<logical> structure of your classes, so |
10821858 |
22 | you can focus on "what" rather than "how". With Moose, a class |
cde84af5 |
23 | definition reads like a list of very concise English sentences. |
270df362 |
24 | |
25 | Moose is built in 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 |
10821858 |
29 | API. The MOP abstracts away tedious digging about in the Perl symbol |
30 | table, looking at C<@ISA> vars, and all the other crufty Perl tricks |
cde84af5 |
31 | we know and love(?). |
270df362 |
32 | |
10821858 |
33 | Moose is based in large part on the Perl 6 object system, as well as |
34 | drawing on the best ideas from CLOS, Smalltalk, and many other |
35 | languages. |
270df362 |
36 | |
37 | =head1 WHY MOOSE? |
38 | |
10821858 |
39 | Moose makes Perl 5 OO both simpler and more powerful. It encapsulates |
40 | all the tricks of Perl 5 power users in high-level declarative APIs |
cdebe1c6 |
41 | which are easy to use, and doesn't require any special knowledge of |
42 | how Perl works under the hood. |
270df362 |
43 | |
cdebe1c6 |
44 | If you want to dig about in the guts, Moose lets you do that too, by |
45 | 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 | |
cde84af5 |
104 | =head2 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 | |
cdebe1c6 |
115 | =item L<Moose::Manual::Classes> |
270df362 |
116 | |
cdebe1c6 |
117 | How do you make use of Moose in your classes? Now that I'm a Moose, |
118 | how do I subclass something? |
270df362 |
119 | |
cdebe1c6 |
120 | =item L<Moose::Manual::Attributes> |
270df362 |
121 | |
cdebe1c6 |
122 | Attributes are a core part of the Moose OO system. An attribute is a |
123 | piece of data that an object has. Moose has a lot of attribute-related |
124 | features! |
270df362 |
125 | |
cde84af5 |
126 | =item L<Moose::Manual::Construction> |
270df362 |
127 | |
cde84af5 |
128 | Learn how objects are built in Moose, and in particular about the |
129 | C<BUILD>, C<BUILDARGS> methods. Also covers object destruction |
130 | with C<DEMOLISH>. |
270df362 |
131 | |
cde84af5 |
132 | =item L<Moose::Manual::MethodModifiers> |
270df362 |
133 | |
cde84af5 |
134 | A method modifier lets you say "before calling method X, do this |
135 | first", or "wrap method X in this code". Method modifiers are |
136 | particularly handy in roles and with attribute accessors. |
270df362 |
137 | |
cde84af5 |
138 | =item L<Moose::Manual::Roles> |
270df362 |
139 | |
cde84af5 |
140 | A role is something a class does (like "Debuggable" or |
141 | "Printable"). Roles provide a way of adding behavior to classes that |
142 | is orthogonal to inheritance. |
270df362 |
143 | |
cde84af5 |
144 | =item L<Moose::Manual::Types> |
270df362 |
145 | |
cde84af5 |
146 | Moose's type system lets you strictly define what values an attribute |
147 | can contain. |
270df362 |
148 | |
cde84af5 |
149 | =item L<Moose::Manual::Introspection> |
270df362 |
150 | |
cde84af5 |
151 | Moose's introspection system (primarily from C<Class::MOP>) lets you |
152 | ask classes about their parents, children, methods, attributes, etc. |
270df362 |
153 | |
cde84af5 |
154 | =item L<Moose::Manual::MooseX> |
270df362 |
155 | |
cde84af5 |
156 | This document shows a few of the most useful Moose extensions on CPAN. |
e03c5ed2 |
157 | |
270df362 |
158 | =back |
159 | |
270df362 |
160 | =head1 JUSTIFICATION |
161 | |
162 | If you're still still asking yourself "Why do I need this?", then this |
163 | section is for you. |
164 | |
165 | =over 4 |
166 | |
167 | =item Another object system!?!? |
168 | |
c56e5db4 |
169 | Yes, I know there are many, many ways to build objects in Perl 5, many |
170 | of them based on inside-out objects and other such things. Moose is |
171 | different because it is not a new object system for Perl 5, but |
172 | instead an extension of the existing object system. |
270df362 |
173 | |
174 | Moose is built on top of L<Class::MOP>, which is a metaclass system |
175 | for Perl 5. This means that Moose not only makes building normal |
176 | Perl 5 objects better, but it also provides the power of metaclass |
177 | programming. |
178 | |
179 | =item Is this for real? Or is this just an experiment? |
180 | |
181 | Moose is I<based> on the prototypes and experiments Stevan did for the |
182 | Perl 6 meta-model. However, Moose is B<NOT> an experiment or |
183 | prototype; it is for B<real>. |
184 | |
185 | =item Is this ready for use in production? |
186 | |
187 | Yes. |
188 | |
c56e5db4 |
189 | Moose has been used successfully in production environments by many |
270df362 |
190 | people and companies. There are Moose applications which have been in |
c56e5db4 |
191 | production with little or no issue now for well years. We consider it |
192 | highly stable and we are commited to keeping it stable. |
270df362 |
193 | |
194 | Of course, in the end, you need to make this call yourself. If you |
195 | have any questions or concerns, please feel free to email Stevan, the |
196 | moose@perl.org list, or just stop by irc.perl.org#moose and ask away. |
197 | |
198 | =item Is Moose just Perl 6 in Perl 5? |
199 | |
200 | No. While Moose is very much inspired by Perl 6, it is not itself Perl |
201 | 6. Instead, it is an OO system for Perl 5. Stevan built Moose because |
202 | he was tired of writing the same old boring Perl 5 OO code, and |
203 | drooling over Perl 6 OO. So instead of switching to Ruby, he wrote |
204 | Moose :) |
205 | |
206 | =item Wait, I<post> modern, I thought it was just I<modern>? |
207 | |
208 | Stevan read Larry Wall's talk from the 1999 Linux World entitled |
209 | "Perl, the first postmodern computer language" in which he talks about |
210 | how he picked the features for Perl because he thought they were cool |
211 | and he threw out the ones that he thought sucked. This got him |
212 | thinking about how we have done the same thing in Moose. For Moose, we |
213 | have "borrowed" features from Perl 6, CLOS (LISP), Smalltalk, Java, |
214 | BETA, OCaml, Ruby and more, and the bits we didn't like (cause they |
215 | sucked) we tossed aside. So for this reason (and a few others) Stevan |
216 | has re-dubbed Moose a I<postmodern> object system. |
217 | |
218 | Nuff Said. |
219 | |
220 | =back |
221 | |
222 | =head1 AUTHOR |
223 | |
10821858 |
224 | Dave Rolsky E<lt>autarch@urth.orgE<gt> and Stevan Little |
270df362 |
225 | E<lt>stevan@iinteractive.comE<gt> |
226 | |
227 | =head1 COPYRIGHT AND LICENSE |
228 | |
229 | Copyright 2008 by Infinity Interactive, Inc. |
230 | |
231 | L<http://www.iinteractive.com> |
232 | |
233 | This library is free software; you can redistribute it and/or modify |
234 | it under the same terms as Perl itself. |
235 | |
236 | =cut |