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