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 =head2 DESCRIPTION
   8
   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.
  11
  12 Moose aims to do the same thing for Perl 5 OO. We can't actually
  13 create new keywords, but we do offer "sugar" that looks a lot like
  14 them. More importantly, with Moose, you I<declaratively define> your
  15 class, without needing to know about blessed hashrefs, accessor
  16 methods, and so on.
  17
  18 Moose helps you define the I<logical> structure of your classes, so
  19 you can focus on "what" rather than "how". With Moose, a class
  20 definition reads like a list of very concise English sentences.
  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
  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
  28 we know and love(?).
  29
  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.
  33
  34 =head1 WHY MOOSE?
  35
  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
  38 which are easy to use, and doesn't require any special knowledge of
  39 how Perl works under the hood.
  40
  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.
  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
  60   no Moose;
  61   __PACKAGE__->meta->make_immutable;
  62
  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',
  74       isa => 'Str',
  75   );
  76
  77   has 'last_login' => (
  78       is      => 'rw',
  79       isa     => 'DateTime',
  80       handles => { 'date_of_last_login' => 'date' },
  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
  94   no Moose;
  95   __PACKAGE__->meta->make_immutable;
  96
  97 We'll leave the line-by-line explanation of this code to other
  98 documentation, but you can see how Moose reduces common OO idioms to
  99 simple declarative constructs.
 100
 101 =head2 TABLE OF CONTENTS
 102
 103 This manual consists of a number of documents.
 104
 105 =over 4
 106
 107 =item L<Moose::Manual::Concepts>
 108
 109 Introduces Moose concepts, and contrasts them against "old school"
 110 Perl 5 OO.
 111
 112 =item L<Moose::Manual::Classes>
 113
 114 How do you make use of Moose in your classes? Now that I'm a Moose,
 115 how do I subclass something?
 116
 117 =item L<Moose::Manual::Attributes>
 118
 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!
 122
 123 =item L<Moose::Manual::Delegation>
 124
 125 Delegation is a powerful way to make use of attribute which are
 126 themselves objects.
 127
 128 =item L<Moose::Manual::Construction>
 129
 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>.
 133
 134 =item L<Moose::Manual::MethodModifiers>
 135
 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.
 139
 140 =item L<Moose::Manual::Roles>
 141
 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.
 145
 146 =item L<Moose::Manual::Types>
 147
 148 Moose's type system lets you strictly define what values an attribute
 149 can contain.
 150
 151 =item L<Moose::Manual::MOP>
 152
 153 Moose's meta API system lets you ask classes about their parents,
 154 children, methods, attributes, etc.
 155
 156 =item L<Moose::Manual::MooseX>
 157
 158 This document shows a few of the most useful Moose extensions on CPAN.
 159
 160 =back
 161
 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
 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.
 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
 191 Moose has been used successfully in production environments by many
 192 people and companies. There are Moose applications which have been in
 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.
 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
 226 Dave Rolsky E<lt>autarch@urth.orgE<gt> and Stevan Little
 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