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. If you've used a
  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.
  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<declaratively define> your
  18 class, without needing to know about blessed hashrefs, accessor
  19 methods, and so on.
  20
  21 Moose helps you define the I<logical> structure of your classes, so
  22 you can focus on "what" rather than "how". With Moose, a class
  23 definition reads like a list of very concise English sentences.
  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
  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
  31 we know and love(?).
  32
  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.
  36
  37 =head1 WHY MOOSE?
  38
  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
  41 which are easy to use, and doesn't require any special knowledge of
  42 how Perl works under the hood.
  43
  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.
  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
  63   no Moose;
  64   __PACKAGE__->meta->make_immutable;
  65
  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',
  77       isa => 'Str',
  78   );
  79
  80   has 'last_login' => (
  81       is      => 'rw',
  82       isa     => 'DateTime',
  83       handles => { 'date_of_last_login' => 'date' },
  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
  97   no Moose;
  98   __PACKAGE__->meta->make_immutable;
  99
 100 We'll leave the line-by-line explanation of this code to other
 101 documentation, but you can see how Moose reduces common OO idioms to
 102 simple declarative constructs.
 103
 104 =head2 TABLE OF CONTENTS
 105
 106 This manual consists of a number of documents.
 107
 108 =over 4
 109
 110 =item L<Moose::Manual::Concepts>
 111
 112 Introduces Moose concepts, and contrasts them against "old school"
 113 Perl 5 OO.
 114
 115 =item L<Moose::Manual::Classes>
 116
 117 How do you make use of Moose in your classes? Now that I'm a Moose,
 118 how do I subclass something?
 119
 120 =item L<Moose::Manual::Attributes>
 121
 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!
 125
 126 =item L<Moose::Manual::Delegation>
 127
 128 Delegation is a powerful way to make use of attribute which are
 129 themselves objects.
 130
 131 =item L<Moose::Manual::Construction>
 132
 133 Learn how objects are built in Moose, and in particular about the
 134 C<BUILD>, C<BUILDARGS> methods. Also covers object destruction
 135 with C<DEMOLISH>.
 136
 137 =item L<Moose::Manual::MethodModifiers>
 138
 139 A method modifier lets you say "before calling method X, do this
 140 first", or "wrap method X in this code". Method modifiers are
 141 particularly handy in roles and with attribute accessors.
 142
 143 =item L<Moose::Manual::Roles>
 144
 145 A role is something a class does (like "Debuggable" or
 146 "Printable"). Roles provide a way of adding behavior to classes that
 147 is orthogonal to inheritance.
 148
 149 =item L<Moose::Manual::Types>
 150
 151 Moose's type system lets you strictly define what values an attribute
 152 can contain.
 153
 154 =item L<Moose::Manual::Introspection>
 155
 156 Moose's introspection system (primarily from C<Class::MOP>) lets you
 157 ask classes about their parents, children, methods, attributes, etc.
 158
 159 =item L<Moose::Manual::MooseX>
 160
 161 This document shows a few of the most useful Moose extensions on CPAN.
 162
 163 =back
 164
 165 =head1 JUSTIFICATION
 166
 167 If you're still still asking yourself "Why do I need this?", then this
 168 section is for you.
 169
 170 =over 4
 171
 172 =item Another object system!?!?
 173
 174 Yes, I know there are many, many ways to build objects in Perl 5, many
 175 of them based on inside-out objects and other such things. Moose is
 176 different because it is not a new object system for Perl 5, but
 177 instead an extension of the existing object system.
 178
 179 Moose is built on top of L<Class::MOP>, which is a metaclass system
 180 for Perl 5. This means that Moose not only makes building normal
 181 Perl 5 objects better, but it also provides the power of metaclass
 182 programming.
 183
 184 =item Is this for real? Or is this just an experiment?
 185
 186 Moose is I<based> on the prototypes and experiments Stevan did for the
 187 Perl 6 meta-model. However, Moose is B<NOT> an experiment or
 188 prototype; it is for B<real>.
 189
 190 =item Is this ready for use in production?
 191
 192 Yes.
 193
 194 Moose has been used successfully in production environments by many
 195 people and companies. There are Moose applications which have been in
 196 production with little or no issue now for well years. We consider it
 197 highly stable and we are commited to keeping it stable.
 198
 199 Of course, in the end, you need to make this call yourself. If you
 200 have any questions or concerns, please feel free to email Stevan, the
 201 moose@perl.org list, or just stop by irc.perl.org#moose and ask away.
 202
 203 =item Is Moose just Perl 6 in Perl 5?
 204
 205 No. While Moose is very much inspired by Perl 6, it is not itself Perl
 206 6.  Instead, it is an OO system for Perl 5. Stevan built Moose because
 207 he was tired of writing the same old boring Perl 5 OO code, and
 208 drooling over Perl 6 OO. So instead of switching to Ruby, he wrote
 209 Moose :)
 210
 211 =item Wait, I<post> modern, I thought it was just I<modern>?
 212
 213 Stevan read Larry Wall's talk from the 1999 Linux World entitled
 214 "Perl, the first postmodern computer language" in which he talks about
 215 how he picked the features for Perl because he thought they were cool
 216 and he threw out the ones that he thought sucked. This got him
 217 thinking about how we have done the same thing in Moose. For Moose, we
 218 have "borrowed" features from Perl 6, CLOS (LISP), Smalltalk, Java,
 219 BETA, OCaml, Ruby and more, and the bits we didn't like (cause they
 220 sucked) we tossed aside. So for this reason (and a few others) Stevan
 221 has re-dubbed Moose a I<postmodern> object system.
 222
 223 Nuff Said.
 224
 225 =back
 226
 227 =head1 AUTHOR
 228
 229 Dave Rolsky E<lt>autarch@urth.orgE<gt> and Stevan Little
 230 E<lt>stevan@iinteractive.comE<gt>
 231
 232 =head1 COPYRIGHT AND LICENSE
 233
 234 Copyright 2008 by Infinity Interactive, Inc.
 235
 236 L<http://www.iinteractive.com>
 237
 238 This library is free software; you can redistribute it and/or modify
 239 it under the same terms as Perl itself.
 240
 241 =cut