lib/Moose/Cookbook.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 Moose::Cookbook - How to cook a Moose
   7
   8 =head1 DESCRIPTION
   9
  10 The Moose cookbook is a series of recipes showing various Moose
  11 features. Most recipes present some code demonstrating some feature,
  12 and then explain the details of the code.
  13
  14 You should probably read the L<Moose::Manual> first. The manual
  15 explains Moose concepts without being too code-heavy.
  16
  17 =head1 RECIPES
  18
  19 =head2 Basic Moose
  20
  21 These recipes will give you a good idea of what Moose is capable,
  22 starting with simple attribute declaration, and moving on to more
  23 powerful features like laziness, types, type coercion, method
  24 modifiers, and more.
  25
  26 =over 4
  27
  28 =item L<Moose::Cookbook::Basics::Recipe1> - The (always classic) B<Point> example
  29
  30 A simple Moose-based class. Demonstrated Moose attributes and subclassing.
  31
  32 =item L<Moose::Cookbook::Basics::Recipe2> - A simple B<BankAccount> example
  33
  34 A slightly more complex Moose class. Demonstrates using a method
  35 modifier in a subclass.
  36
  37 =item L<Moose::Cookbook::Basics::Recipe3> - A lazy B<BinaryTree> example
  38
  39 Demonstrates several attribute features, including types, weak
  40 references, predicates ("does this object have a foo?"), defaults,
  41 laziness, and triggers.
  42
  43 =item L<Moose::Cookbook::Basics::Recipe4> - Subtypes, and modeling a simple B<Company> class hierarchy
  44
  45 Introduces the creation and use of custom types, a C<BUILD> method,
  46 and the use of C<override> in a subclass.
  47
  48 =item L<Moose::Cookbook::Basics::Recipe5> - More subtypes, coercion in a B<Request> class
  49
  50 More type examples, including the use of type coercions.
  51
  52 =item L<Moose::Cookbook::Basics::Recipe6> - The augment/inner example
  53
  54 Demonstrates the use of C<augment> method modifiers, a way of turning
  55 the usual method overriding style "inside-out".
  56
  57 =item L<Moose::Cookbook::Basics::Recipe7> - Making Moose fast with immutable
  58
  59 Making a class immutable greatly increases the speed of accessors and
  60 object construction.
  61
  62 =item L<Moose::Cookbook::Basics::Recipe8> - Managing complex relations with trigger (TODO)
  63
  64 I<abstract goes here>
  65
  66 Work off of this http://code2.0beta.co.uk/moose/svn/Moose/trunk/t/200_examples/007_Child_Parent_attr_inherit.t
  67
  68 =item L<Moose::Cookbook::Basics::Recipe9> - Builder methods and lazy_build
  69
  70 The builder feature provides an inheritable and role-composable way to
  71 provide a default attribute value.
  72
  73 =item L<Moose::Cookbook::Basics::Recipe10> - Operator overloading, subtypes, and coercion
  74
  75 Demonstrates using operator overloading, coercion, and subtypes to
  76 model how eye color is determined during reproduction.
  77
  78 =item L<Moose::Cookbook::Basics::Recipe11> - Using BUILDARGS and BUILD to hook into object construction
  79
  80 This recipe demonstrates the use of C<BUILDARGS> and C<BUILD> to hook
  81 into object construction.
  82
  83 =back
  84
  85 =head2 Moose Roles
  86
  87 These recipes will show you how to use Moose roles.
  88
  89 =over 4
  90
  91 =item L<Moose::Cookbook::Roles::Recipe1> - The Moose::Role example
  92
  93 Demonstrates roles, which are also sometimes known as traits or
  94 mix-ins. Roles provide a method of code re-use which is orthogonal to
  95 subclassing.
  96
  97 =item L<Moose::Cookbook::Roles::Recipe2> - Advanced Role Composition - method exclusion and aliasing
  98
  99 Sometimes you just want to include part of a role in your
 100 class. Sometimes you want the whole role but one if its methods
 101 conflicts with one in your class. With method exclusion and aliasing,
 102 you can work around these problems.
 103
 104 =item L<Moose::Cookbook::Roles::Recipe3> - Applying a role to an object instance
 105
 106 In this recipe, we apply a role to an existing object instance.
 107
 108 =back
 109
 110 =head2 Meta Moose
 111
 112 These recipes show you how to write your own meta classes, which lets
 113 you extend the object system provide by Moose.
 114
 115 =over 4
 116
 117 =item L<Moose::Cookbook::Meta::Recipe1> - Welcome to the meta-world (Why Go Meta?)
 118
 119 If you're wondering what all this "meta" stuff is, and why you should
 120 care about it, read this "recipe".
 121
 122 =item L<Moose::Cookbook::Meta::Recipe2> - A meta-attribute, attributes with labels
 123
 124 One way to extend Moose is to provide your own attribute
 125 metaclasses. Attribute metaclasses let you extend attribute
 126 declarations (with C<has>) and behavior to provide additional
 127 attribute functionality.
 128
 129 =item L<Moose::Cookbook::Meta::Recipe3> - Labels implemented via attribute traits
 130
 131 Extending Moose's attribute metaclass is a great way to add
 132 functionality. However, attributes can only have one metaclass.
 133 Applying roles to the attribute metaclass lets you provide
 134 composable attribute functionality.
 135
 136 =item L<Moose::Cookbook::Meta::Recipe4> - Adding a "table" attribute to the metaclass
 137
 138 If you want to store more information about your classes, you'll have
 139 to extend C<Moose::Meta::Class>. Doing so is simple, but you'll
 140 probably also want to provide some sugar, so see
 141 L<Moose::Cookbook::Extending::Recipe2> as well.
 142
 143 =item L<Moose::Cookbook::Meta::Recipe5> - The "table" attribute implemented as a metaclass trait
 144
 145 This example takes the class metaclass we saw in the previous recipe
 146 and reimplements it as a metaclass trait.
 147
 148 =item L<Moose::Cookbook::Meta::Recipe6> - Hooking into the immutabilization system (TODO)
 149
 150 Moose has a feature known as "immutabilization". By calling C<<
 151 __PACKAGE__->meta()->make_immutable() >> after defining your class
 152 (attributes, roles, etc), you tell Moose to optimize things like
 153 object creation, attribute access, and so on.
 154
 155 If you are creating your own metaclasses, you may need to hook into
 156 the immutabilization system. This cuts across a number of spots,
 157 including the metaclass class, meta method classes, and possibly the
 158 meta-instance class as well.
 159
 160 This recipe shows you how to write extensions which immutabilize
 161 properly.
 162
 163 =item L<Moose::Cookbook::Meta::Recipe7> - Using a blessed array reference as an object instance
 164
 165 This recipe shows an example of how you create your own meta-instance
 166 class. The meta-instance determines the internal structure of object
 167 instances and provide access to attribute slots.
 168
 169 =back
 170
 171 =head2 Extending Moose
 172
 173 These recipes cover some more ways to extend Moose, and will be useful
 174 if you plan to write your own C<MooseX> module.
 175
 176 =over 4
 177
 178 =item L<Moose::Cookbook::Extending::Recipe1> - Moose extension overview
 179
 180 There are quite a number of ways to extend Moose. This recipe explains
 181 provides an overview of each method, and provides recommendations for
 182 when each is appropriate.
 183
 184 =item L<Moose::Cookbook::Extending::Recipe2> - Providing a base object class role
 185
 186 Many base object class extensions can be implemented as roles. This
 187 example shows how to provide a base object class debugging role that
 188 is applied to any class that uses a notional C<MooseX::Debugging>
 189 module.
 190
 191 =item L<Moose::Cookbook::Extending::Recipe3> - Providing an alternate base object class
 192
 193 You may find that you want to provide an alternate base object class
 194 along with a meta extension, or maybe you just want to add some
 195 functionality to all your classes without typing C<extends
 196 'MyApp::Base'> over and over.
 197
 198 =item L<Moose::Cookbook::Extending::Recipe4> - Acting like Moose.pm and providing sugar Moose-style
 199
 200 This recipe shows how to provide a replacement for C<Moose.pm>. You
 201 may want to do this as part of the API for a C<MooseX> module,
 202 especially if you want to default to a new metaclass class or base
 203 object class.
 204
 205 =back
 206
 207 =head1 SNACKS
 208
 209 =over 4
 210
 211 =item L<Moose::Cookbook::Snack::Keywords>
 212
 213 =item L<Moose::Cookbook::Snack::Types>
 214
 215 =back
 216
 217 =head1 SEE ALSO
 218
 219 =over 4
 220
 221 =item L<http://www.gsph.com/index.php?Lang=En&ID=291>
 222
 223 =back
 224
 225 =head1 AUTHOR
 226
 227 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 228
 229 =head1 COPYRIGHT AND LICENSE
 230
 231 Copyright 2006-2009 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