=head1 DESCRIPTION
-The Moose cookbook is a series of recipes taken from the Moose
-test suite. Each recipe presents some code, which demonstrates
-some of the features of Moose, and then proceeds to explain the
-details of the code.
+The Moose cookbook is a series of recipes showing various Moose
+features. Most recipes present some code demonstrating some feature,
+and then explain the details of the code.
-We also provide a L<Moose::Cookbook::FAQ> and a L<Moose::Cookbook::WTF>
-for common questions and problems people have with Moose.
+You should probably read the L<Moose::Manual> first. The manual
+explains Moose concepts without being too code-heavy.
=head1 RECIPES
=head2 Basic Moose
+These recipes will give you a good idea of what Moose is capable,
+starting with simple attribute declaration, and moving on to more
+powerful features like laziness, types, type coercion, method
+modifiers, and more.
+
=over 4
-=item L<Moose::Cookbook::Recipe1> - The (always classic) B<Point> example
+=item L<Moose::Cookbook::Basics::Recipe1> - The (always classic) B<Point> example
+
+A simple Moose-based class. Demonstrated Moose attributes and subclassing.
+
+=item L<Moose::Cookbook::Basics::Recipe2> - A simple B<BankAccount> example
+
+A slightly more complex Moose class. Demonstrates using a method
+modifier in a subclass.
+
+=item L<Moose::Cookbook::Basics::Recipe3> - A lazy B<BinaryTree> example
+
+Demonstrates several attribute features, including types, weak
+references, predicates ("does this object have a foo?"), defaults, and
+lazy attribute construction.
+
+=item L<Moose::Cookbook::Basics::Recipe4> - Subtypes, and modeling a simple B<Company> class hierarchy
+
+Introduces the creation and use of custom types, a C<BUILD> method,
+and the use of C<override> in a subclass.
+
+=item L<Moose::Cookbook::Basics::Recipe5> - More subtypes, coercion in a B<Request> class
+
+More type examples, including the use of type coercions.
+
+=item L<Moose::Cookbook::Basics::Recipe6> - The augment/inner example
+
+Demonstrates the use of C<augment> method modifiers, a way of turning
+the usual method overriding style "inside-out".
+
+=item L<Moose::Cookbook::Basics::Recipe7> - Making Moose fast with immutable
+
+Making a class immutable greatly increases the speed of accessors and
+object construction.
-=item L<Moose::Cookbook::Recipe2> - A simple B<BankAccount> example
+=item L<Moose::Cookbook::Basics::Recipe8> - Managing complex relations with trigger (TODO)
-=item L<Moose::Cookbook::Recipe3> - A lazy B<BinaryTree> example
+I<abstract goes here>
-=item L<Moose::Cookbook::Recipe4> - Subtypes, and modeling a simple B<Company> class hierarchy
+Work off of this http://code2.0beta.co.uk/moose/svn/Moose/trunk/t/200_examples/007_Child_Parent_attr_inherit.t
-=item L<Moose::Cookbook::Recipe5> - More subtypes, coercion in a B<Request> class
+=item L<Moose::Cookbook::Basics::Recipe9> - Builder methods and lazy_build
-=item L<Moose::Cookbook::Recipe6> - The augment/inner example
+The builder feature provides an inheritable and role-composable way to
+provide a default attribute value.
-=item L<Moose::Cookbook::Recipe7> - Making Moose fast with immutable (TODO)
+=item L<Moose::Cookbook::Basics::Recipe10> - Operator overloading, subtypes, and coercion
-=item L<Moose::Cookbook::Recipe8> - ??
+Demonstrates using operator overloading, coercion, and subtypes to
+model how eye color is determined during reproduction.
-=item L<Moose::Cookbook::Recipe9> - ??
+=item L<Moose::Cookbook::Basics::Recipe11> - BUILD and BUILDARGS (TODO)
+
+We need a good recipe demonstrating how these work.
=back
=head2 Moose Roles
+These recipes will show you how to use Moose roles.
+
=over 4
-=item L<Moose::Cookbook::Recipe10> - The Moose::Role example
+=item L<Moose::Cookbook::Roles::Recipe1> - The Moose::Role example
+
+Demonstrates roles, which are also sometimes known as traits or
+mix-ins. Roles provide a method of code re-use which is orthogonal to
+subclassing.
+
+=item L<Moose::Cookbook::Roles::Recipe2> - Advanced Role Composition - method exclusion and aliasing
-=item L<Moose::Cookbook::Recipe11> - Advanced Role Composition (TODO)
+Sometimes you just want to include part of a role in your
+class. Sometimes you want the whole role but one if its methods
+conflicts with one in your class. With method exclusion and aliasing,
+you can work around these problems.
+
+=item L<Moose::Cookbook::Roles::Recipe3> - Runtime Role Composition (TODO)
+
+I<abstract goes here>
=back
=head2 Meta Moose
+These recipes show you how to write your own meta classes, which lets
+you extend the object system provide by Moose.
+
=over 4
-=item L<Moose::Cookbook::Recipe20> - Welcome to the meta-world (TODO)
+=item L<Moose::Cookbook::Meta::Recipe1> - Welcome to the meta-world (Why Go Meta?)
+
+If you're wondering what all this "meta" stuff is, and why you should
+care about it, read this "recipe".
+
+=item L<Moose::Cookbook::Meta::Recipe2> - A meta-attribute, attributes with labels
+
+One way to extend Moose is to provide your own attribute
+metaclasses. Attribute metaclasses let you extend attribute
+declarations (with C<has>) and behavior to provide additional
+attribute functionality.
+
+=item L<Moose::Cookbook::Meta::Recipe3> - Labels implemented via attribute traits
+
+Extending Moose's attribute metaclass is a great way to add
+functionality. However, attributes can only have one metaclass.
+Applying roles to the attribute metaclass lets you provide
+composable attribute functionality.
+
+=item L<Moose::Cookbook::Meta::Recipe4> - Adding a "table" attribute to the metaclass
-=item L<Moose::Cookbook::Recipe21> - The meta-attribute example
+If you want to store more information about your classes, you'll have
+to extend C<Moose::Meta::Class>. Doing so is simple, but you'll
+probably also want to provide some sugar, so see
+L<Moose::Cookbook::Extending::Recipe2> as well.
-=item L<Moose::Cookbook::Recipe22> - The meta-attribute trait example (TODO)
+=item L<Moose::Cookbook::Meta::Recipe5> - The "table" attribute implemented as a metaclass trait
+
+This example takes the class metaclass we saw in the previous recipe
+and reimplements it as a metaclass trait.
+
+=item L<Moose::Cookbook::Meta::Recipe6> - Hooking into the immutabilization system (TODO)
+
+Moose has a feature known as "immutabilization". By calling C<<
+__PACKAGE__->meta()->make_immutable() >> after defining your class
+(attributes, roles, etc), you tell Moose to optimize things like
+object creation, attribute access, and so on.
+
+If you are creating your own metaclasses, you may need to hook into
+the immutabilization system. This cuts across a number of spots,
+including the metaclass class, meta method classes, and possibly the
+meta-instance class as well.
+
+This recipe shows you how to write extensions which immutabilize
+properly.
+
+=item L<Moose::Cookbook::Meta::Recipe7> - I<meta-instance> (TODO)
+
+I<abstract goes here>
+
+=back
+
+=head2 Extending Moose
+
+These recipes cover some more ways to extend Moose, and will be useful
+if you plan to write your own C<MooseX> module.
+
+=over 4
+
+=item L<Moose::Cookbook::Extending::Recipe1> - Moose extension overview
+
+There are quite a number of ways to extend Moose. This recipe explains
+provides an overview of each method, and provides recommendations for
+when each is appropriate.
+
+=item L<Moose::Cookbook::Extending::Recipe2> - Providing a base object class role
+
+Many base object class extensions can be implemented as roles. This
+example shows how to provide a base object class debugging role that
+is applied to any class that uses a notional C<MooseX::Debugging>
+module.
+
+=item L<Moose::Cookbook::Extending::Recipe3> - Providing an alternate base object class
+
+You may find that you want to provide an alternate base object class
+along with a meta extension, or maybe you just want to add some
+functionality to all your classes without typing C<extends
+'MyApp::Base'> over and over.
+
+=item L<Moose::Cookbook::Extending::Recipe4> - Acting like Moose.pm and providing sugar Moose-style
+
+This recipe shows how to provide a replacement for C<Moose.pm>. You
+may want to do this as part of the API for a C<MooseX> module,
+especially if you want to default to a new metaclass class or base
+object class.
+
+=back
+
+=head1 SNACKS
+
+=over 4
-=item L<Moose::Cookbook::Recipe23> - The meta-instance example (TODO)
+=item L<Moose::Cookbook::Snack::Keywords>
-=item L<Moose::Cookbook::Recipe24> - The meta-class example (TODO)
+=item L<Moose::Cookbook::Snack::Types>
=back
=head1 COPYRIGHT AND LICENSE
-Copyright 2006-2008 by Infinity Interactive, Inc.
+Copyright 2006-2009 by Infinity Interactive, Inc.
L<http://www.iinteractive.com>
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
-=cut
\ No newline at end of file
+=cut
projects / gitmo/Moose.git / blobdiff