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 now made a Moose-based class!
  16
  17 There's actually a lot going on here under the hood, so let's step
  18 through it. The L<Moose> package does several things when you load it.
  19
  20 When you load Moose, you get a bunch of sugar functions 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 in your class also turns on the C<strict> and
  35 C<warnings> pragmas in your class for you.
  36
  37 The metaclass object an introspection API for your class. It is also
  38 used by Moose itself under the hood to add attributes, define parent
  39 classes, and so on. In fact, all of Moose's sugar does the real work
  40 by calling methods on this metaclass object (and other meta level
  41 objects).
  42
  43 When you load Moose, your class will become a subclass of
  44 L<Moose::Object>. The L<Moose::Object> class provides a default
  45 constructor, destructor, as well as object construction helper
  46 methods. You can read more about this in the
  47 L<Moose::Manual::Construction> document.
  48
  49 As a convenience, Moose creates a new class type with the name of your
  50 class, by calling the C<class_type> function in
  51 L<Moose::Util::Constraints>. See the L<Moose::Manual::Types> document
  52 for more about types.
  53
  54 It also creates a L<Moose::Meta::Class> object for your class. This
  55 metaclass object is now available by calling a C<meta> method on your
  56 class, for example C<< Person->meta >>.
  57
  58 =head1 SUBCLASSING
  59
  60 Moose provides a simple sugar function for declaring your parent
  61 classes, C<extends>:
  62
  63   package User;
  64
  65   use Moose;
  66
  67   extends 'Person';
  68
  69   has 'username' => ( is => 'rw' );
  70
  71 When you call extends, Moose takes the class(es) you provide and makes
  72 those the parent of the current class. Note, that each call to
  73 C<extends> will I<reset> your parents, so for multiple inheritance you
  74 should provide all you parents at once, C<extends 'Foo', 'Bar'>.
  75
  76 You can use Moose to extend a non-Moose parent. However, when you do
  77 this, you will inherit the parent class's constructor (assuming it is
  78 also called C<new>). In that case, you will have to take care of
  79 initializing attributes manually, either in the parent's constructor,
  80 or in your subclass, and you will generally lose a lot of Moose magic.
  81
  82 =head1 NO MOOSE
  83
  84 Moose also allows you to remove its sugar functions from your class's
  85 namespace. We recommend that you take advantage of this feature, since
  86 it just makes your classes "cleaner". You can do this by simply adding
  87 C<no Moose> at the end of your module file.
  88
  89 What this does is delete the functions from your class's namespace, so
  90 that C<< Person->can('has') >> will no longer return true.
  91
  92 =head1 MAKING IT FASTER
  93
  94 Moose has a feature called "immutabilization" that you can use to
  95 greatly speed up your classes at runtime. However, using it does incur
  96 a cost when your class is first being loaded. When you make your class
  97 immutable you tell Moose that you will not be changing it,
  98 specifically not adding any attributes, methods, roles, etc.
  99
 100 This allows Moose to generate code specific to your class for its
 101 constructor and other methods, making object construction much
 102 faster. It also makes some of the introspection methods faster as
 103 well.
 104
 105 To make your class immutable you simply call C<make_immutable> on your
 106 class's metaclass object.
 107
 108 =head1 AUTHOR
 109
 110 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 111
 112 =head1 COPYRIGHT AND LICENSE
 113
 114 Copyright 2008 by Infinity Interactive, Inc.
 115
 116 L<http://www.iinteractive.com>
 117
 118 This library is free software; you can redistribute it and/or modify
 119 it under the same terms as Perl itself.
 120
 121 =cut