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 don't require any special knowledge of how
  42 Perl works under the hood.
  43
  44 Moose makes Perl 5 OO fun, accessible, and powerful. And if you want
  45 to dig about in the guts, Moose lets you do that too, by using and
  46 extending its powerful introspection API.
  47
  48 =head1 AN EXAMPLE
  49
  50   package Person;
  51
  52   use Moose;
  53
  54   has 'first_name' => (
  55       is  => 'rw',
  56       isa => 'Str',
  57   );
  58
  59   has 'last_name' => (
  60       is  => 'rw',
  61       isa => 'Str',
  62   );
  63
  64 This is a I<complete and usable> class definition!
  65
  66   package User;
  67
  68   use DateTime;
  69   use Moose;
  70
  71   extends 'Person';
  72
  73   has 'password' => (
  74       is  => 'rw',
  75       isa => 'Str',
  76   );
  77
  78   has 'last_login' => (
  79       is      => 'rw',
  80       isa     => 'DateTime',
  81       handles => { 'date_of_last_login' => 'date' },
  82   );
  83
  84   sub login {
  85       my $self = shift;
  86       my $pw   = shift;
  87
  88       return 0 if $pw ne $self->password;
  89
  90       $self->last_login( DateTime->now() );
  91
  92       return 1;
  93   }
  94
  95 We'll leave the line-by-line explanation of this code to other
  96 documentation, but you can see how Moose reduces common OO idioms to
  97 simple declarative constructs.
  98
  99 =head2 TABLE OF CONTENTS
 100
 101 This manual consists of a number of documents.
 102
 103 =over 4
 104
 105 =item L<Moose::Manual::Concepts>
 106
 107 Introduces Moose concepts, and contrasts them against "old school"
 108 Perl 5 OO.
 109
 110 =item L<Moose::Manual::UsingMoose>
 111
 112 How do you make use of Moose in your classes?
 113
 114 =item L<Moose::Manual::Subclassing>
 115
 116 Now that I'm a Moose, how do I subclass something?
 117
 118 =item L<Moose::Manual::Construction>
 119
 120 Learn how objects are built in Moose, and in particular about the
 121 C<BUILD>, C<BUILDARGS> methods. Also covers object destruction
 122 with C<DEMOLISH>.
 123
 124 =item L<Moose::Manual::Attributes>
 125
 126 Attributes are a core part of the Moose OO system. An attribute is a
 127 piece of data that an object has. Moose has a lot of attribute-related
 128 features!
 129
 130 =item L<Moose::Manual::MethodModifiers>
 131
 132 A method modifier lets you say "before calling method X, do this
 133 first", or "wrap method X in this code". Method modifiers are
 134 particularly handy in roles and with attribute accessors.
 135
 136 =item L<Moose::Manual::Roles>
 137
 138 A role is something a class does (like "Debuggable" or
 139 "Printable"). Roles provide a way of adding behavior to classes that
 140 is orthogonal to inheritance.
 141
 142 =item L<Moose::Manual::Types>
 143
 144 Moose's type system lets you strictly define what values an attribute
 145 can contain.
 146
 147 =item L<Moose::Manual::Introspection>
 148
 149 Moose's introspection system (primarily from C<Class::MOP>) lets you
 150 ask classes about their parents, children, methods, attributes, etc.
 151
 152 =item L<Moose::Manual::MooseX>
 153
 154 This document shows a few of the most useful Moose extensions on CPAN.
 155
 156 =back
 157
 158 =head1 JUSTIFICATION
 159
 160 If you're still still asking yourself "Why do I need this?", then this
 161 section is for you.
 162
 163 =over 4
 164
 165 =item Another object system!?!?
 166
 167 Yes, I know there has been an explosion recently of new ways to
 168 build objects in Perl 5, most of them based on inside-out objects
 169 and other such things. Moose is different because it is not a new
 170 object system for Perl 5, but instead an extension of the existing
 171 object system.
 172
 173 Moose is built on top of L<Class::MOP>, which is a metaclass system
 174 for Perl 5. This means that Moose not only makes building normal
 175 Perl 5 objects better, but it also provides the power of metaclass
 176 programming.
 177
 178 =item Is this for real? Or is this just an experiment?
 179
 180 Moose is I<based> on the prototypes and experiments Stevan did for the
 181 Perl 6 meta-model. However, Moose is B<NOT> an experiment or
 182 prototype; it is for B<real>.
 183
 184 =item Is this ready for use in production?
 185
 186 Yes.
 187
 188 Moose has been used successfully in production environments by several
 189 people and companies. There are Moose applications which have been in
 190 production with little or no issue now for well over two years. We
 191 consider it highly stable and we are commited to keeping it stable.
 192
 193 Of course, in the end, you need to make this call yourself. If you
 194 have any questions or concerns, please feel free to email Stevan, the
 195 moose@perl.org list, or just stop by irc.perl.org#moose and ask away.
 196
 197 =item Is Moose just Perl 6 in Perl 5?
 198
 199 No. While Moose is very much inspired by Perl 6, it is not itself Perl
 200 6.  Instead, it is an OO system for Perl 5. Stevan built Moose because
 201 he was tired of writing the same old boring Perl 5 OO code, and
 202 drooling over Perl 6 OO. So instead of switching to Ruby, he wrote
 203 Moose :)
 204
 205 =item Wait, I<post> modern, I thought it was just I<modern>?
 206
 207 Stevan read Larry Wall's talk from the 1999 Linux World entitled
 208 "Perl, the first postmodern computer language" in which he talks about
 209 how he picked the features for Perl because he thought they were cool
 210 and he threw out the ones that he thought sucked. This got him
 211 thinking about how we have done the same thing in Moose. For Moose, we
 212 have "borrowed" features from Perl 6, CLOS (LISP), Smalltalk, Java,
 213 BETA, OCaml, Ruby and more, and the bits we didn't like (cause they
 214 sucked) we tossed aside. So for this reason (and a few others) Stevan
 215 has re-dubbed Moose a I<postmodern> object system.
 216
 217 Nuff Said.
 218
 219 =back
 220
 221 =head1 AUTHOR
 222
 223 Dave Rolsky E<lt>autarch@urth.orgE<gt> and Stevan Little
 224 E<lt>stevan@iinteractive.comE<gt>
 225
 226 =head1 COPYRIGHT AND LICENSE
 227
 228 Copyright 2008 by Infinity Interactive, Inc.
 229
 230 L<http://www.iinteractive.com>
 231
 232 This library is free software; you can redistribute it and/or modify
 233 it under the same terms as Perl itself.
 234
 235 =cut