lib/Moose/Manual.pod

   1 package Moose::Manual;
   2
   3 # ABSTRACT: What is Moose, and how do I use it?
   4
   5 __END__
   6
   7 =pod
   8
   9 =head1 WHAT IS MOOSE?
  10
  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.
  16
  17 Moose aims to do the same thing for Perl 5 OO. We can't actually
  18 create new keywords, but we do offer "sugar" that looks a lot like
  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.
  22
  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.
  26
  27 Moose is built on top of C<Class::MOP>, a meta-object protocol (aka
  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
  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(?).
  33
  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.
  37
  38 =head1 WHY MOOSE?
  39
  40 Moose makes Perl 5 OO both simpler and more powerful. It encapsulates
  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.
  43
  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.
  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 =head1 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::Unsweetened>
 116
 117 Shows two example classes, each written first with Moose and then with
 118 "plain old Perl 5".
 119
 120 =item L<Moose::Manual::Classes>
 121
 122 How do you make use of Moose in your classes? Now that I'm a Moose,
 123 how do I subclass something?
 124
 125 =item L<Moose::Manual::Attributes>
 126
 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!
 130
 131 =item L<Moose::Manual::Delegation>
 132
 133 Delegation is a powerful way to make use of attributes which are
 134 themselves objects.
 135
 136 =item L<Moose::Manual::Construction>
 137
 138 Learn how objects are built in Moose, and in particular about the
 139 C<BUILD> and C<BUILDARGS> methods. Also covers object destruction
 140 with C<DEMOLISH>.
 141
 142 =item L<Moose::Manual::MethodModifiers>
 143
 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.
 147
 148 =item L<Moose::Manual::Roles>
 149
 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.
 153
 154 =item L<Moose::Manual::Types>
 155
 156 Moose's type system lets you strictly define what values an attribute
 157 can contain.
 158
 159 =item L<Moose::Manual::MOP>
 160
 161 Moose's meta API system lets you ask classes about their parents,
 162 children, methods, attributes, etc.
 163
 164 =item L<Moose::Manual::MooseX>
 165
 166 This document describes a few of the most useful Moose extensions on
 167 CPAN.
 168
 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
 175 =item L<Moose::Manual::FAQ>
 176
 177 Frequently asked questions about Moose.
 178
 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
 188 =back
 189
 190 =head1 JUSTIFICATION
 191
 192 If you're still asking yourself "Why do I need this?", then this
 193 section is for you.
 194
 195 =over 4
 196
 197 =item Another object system!?!?
 198
 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
 202 instead an extension of the existing object system.
 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
 219 Moose has been used successfully in production environments by many
 220 people and companies. There are Moose applications which have been in
 221 production with little or no issue now for years. We consider it
 222 highly stable and we are committed to keeping it stable.
 223
 224 Of course, in the end, you need to make this call yourself. If you
 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.
 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
 232 6. Instead, it is an OO system for Perl 5. Stevan built Moose because
 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
 253 =cut