lib/Moose/Manual/Classes.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Moose::Manual::Classes - Making your classes use Moose (and subclassing)
   6
   7 =head1 USING MOOSE
   8
   9 Using Moose is very simple, you just C<use Moose>:
  10
  11   package Person;
  12
  13   use Moose;
  14
  15 That's it, you've made a class with Moose!
  16
  17 There's actually a lot going on here under the hood, so let's step
  18 through it.
  19
  20 When you load L<Moose>, a bunch of sugar functions are exported into your
  21 class, such as C<extends>, C<has>, C<with>, and more. These functions are what
  22 you use to define your class. For example, you might define an attribute ...
  23
  24   package Person;
  25
  26   use Moose;
  27
  28   has 'ssn' => ( is => 'rw' );
  29
  30 Attributes are described in the L<Moose::Manual::Attributes>
  31 documentation.
  32
  33 Loading Moose also enables the C<strict> and C<warnings> pragmas in your
  34 class.
  35
  36 When you load Moose, your class will become a subclass of
  37 L<Moose::Object>. The L<Moose::Object> class provides a default
  38 constructor and destructor, as well as object construction helper
  39 methods. You can read more about this in the
  40 L<Moose::Manual::Construction> document.
  41
  42 As a convenience, Moose creates a new class type for your class. See
  43 the L<Moose::Manual::Types> document to learn more about types.
  44
  45 It also creates a L<Moose::Meta::Class> object for your class. This
  46 metaclass object is now available by calling a C<meta> method on your
  47 class, for example C<< Person->meta >>.
  48
  49 The metaclass object provides an introspection API for your class. It
  50 is also used by Moose itself under the hood to add attributes, define
  51 parent classes, and so on. In fact, all of Moose's sugar does the real
  52 work by calling methods on this metaclass object (and other meta API
  53 objects).
  54
  55 =head1 SUBCLASSING
  56
  57 Moose provides a simple sugar function for declaring your parent
  58 classes, C<extends>:
  59
  60   package User;
  61
  62   use Moose;
  63
  64   extends 'Person';
  65
  66   has 'username' => ( is => 'rw' );
  67
  68 Note that each call to C<extends> will I<reset> your parents. For
  69 multiple inheritance you must provide all the parents at once,
  70 C<extends 'Foo', 'Bar'>.
  71
  72 You can use Moose to extend a non-Moose parent. However, when you do
  73 this, you will inherit the parent class's constructor (assuming it is
  74 also called C<new>). In that case, you will have to take care of
  75 initializing attributes manually, either in the parent's constructor,
  76 or in your subclass, and you will lose a lot of Moose magic.
  77
  78 See the L<MooseX::NonMoose> module on CPAN if you're interested in extending
  79 non-Moose parent classes with Moose child classes.
  80
  81 =head1 CLEANING UP MOOSE DROPPINGS
  82
  83 Moose exports a number of functions into your class. It's a good idea to
  84 remove these sugar functions from your class's namespace, so that C<<
  85 Person->can('has') >> will no longer return true.
  86
  87 There are several ways to do this. We recommend using L<namespace::autoclean>,
  88 a CPAN module. Not only will it remove Moose exports, it will also remove
  89 any other exports.
  90
  91   package Person;
  92
  93   use namespace::autoclean;
  94
  95   use Moose;
  96
  97 If you absolutely can't use a CPAN module (but can use Moose?), you can write
  98 C<no Moose> at the end of your class. This will remove any Moose exports in
  99 your class.
 100
 101   package Person;
 102
 103   use Moose;
 104
 105   has 'ssn' => ( is => 'rw' );
 106
 107   no Moose;
 108
 109 =head1 MAKING IT FASTER
 110
 111 Moose has a feature called "immutabilization" that you can use to
 112 greatly speed up your classes at runtime. However, using it incurs
 113 a cost when your class is first being loaded. When you make your class
 114 immutable you tell Moose that you will not be changing it in the
 115 future. You will not be adding any more attributes, methods, roles, etc.
 116
 117 This allows Moose to generate code specific to your class. In
 118 particular, it creates an "inline" constructor, making object
 119 construction much faster.
 120
 121 To make your class immutable you simply call C<make_immutable> on your
 122 class's metaclass object.
 123
 124   __PACKAGE__->meta->make_immutable;
 125
 126 =head2 Immutabilization and C<new()>
 127
 128 If you override C<new()> in your class, then the immutabilization code
 129 will not be able to provide an optimized constructor for your
 130 class. Instead, you should use a C<BUILD()> method, which will be
 131 called from the inlined constructor.
 132
 133 Alternately, if you really need to provide a different C<new()>, you
 134 can also provide your own immutabilization method. Doing so requires
 135 extending the Moose metaclasses, and is well beyond the scope of this
 136 manual.
 137
 138 =head1 AUTHOR
 139
 140 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 141
 142 =head1 COPYRIGHT AND LICENSE
 143
 144 Copyright 2008-2010 by Infinity Interactive, Inc.
 145
 146 L<http://www.iinteractive.com>
 147
 148 This library is free software; you can redistribute it and/or modify
 149 it under the same terms as Perl itself.
 150
 151 =cut