X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FCookbook.pod;h=275cfc3ad7a5bd20b6a1a8100acc49085d3cf49e;hb=3900cea16697e2d5ddc24b6284c5c1f2a858c6b0;hp=541c5bf92d56446d80de72172ca8069d6f89d90b;hpb=104379bc77144fb62e619d1edc3f7d9b3db47043;p=gitmo%2FMoose.git diff --git a/lib/Moose/Cookbook.pod b/lib/Moose/Cookbook.pod index 541c5bf..275cfc3 100644 --- a/lib/Moose/Cookbook.pod +++ b/lib/Moose/Cookbook.pod @@ -1,93 +1,230 @@ +package Moose::Cookbook; -=pod +# ABSTRACT: How to cook a Moose + +__END__ -=head1 NAME -Moose::Cookbook - How to cook a Moose +=pod =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 and a L -for common questions and problems people have with Moose. +You should probably read the L first. The manual +explains Moose concepts without being too code-heavy. =head1 RECIPES =head2 Basic Moose +These recipes will give you a good overview of Moose's capabilities, 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 - The (always classic) B example +=item L - The (always classic) B example + +A simple Moose-based class. Demonstrates Moose attributes and subclassing. + +=item L - A simple B example + +A slightly more complex Moose class. Demonstrates using a method +modifier in a subclass. + +=item L - A lazy B example + +Demonstrates several attribute features, including types, weak +references, predicates ("does this object have a foo?"), defaults, +laziness, and triggers. + +=item L - Subtypes, and modeling a simple B class hierarchy + +Introduces the creation and use of custom types, a C method, +and the use of C in a subclass. + +=item L - More subtypes, coercion in a B class + +More type examples, including the use of type coercions. + +=item L - The augment/inner example -=item L - A simple B example +Demonstrates the use of C method modifiers, a way of turning +the usual method overriding style "inside-out". -=item L - A lazy B example +=item L - Making Moose fast with immutable -=item L - Subtypes, and modeling a simple B class hierarchy +Making a class immutable greatly increases the speed of accessors and +object construction. -=item L - More subtypes, coercion in a B class +=item L - Builder methods and lazy_build -=item L - The augment/inner example +The builder feature provides an inheritable and role-composable way to +provide a default attribute value. -=item L - Making Moose fast with immutable (TODO) +=item L - Operator overloading, subtypes, and coercion -=item L - ?? +Demonstrates using operator overloading, coercion, and subtypes to +model how eye color is determined during reproduction. -=item L - ?? +=item L - Using BUILDARGS and BUILD to hook into object construction + +This recipe demonstrates the use of C and C to hook +into object construction. + +=item L - Extending a non-Moose base class + +In this recipe, we make a Moose-based subclass of L, a +module which does not use Moose itself. =back =head2 Moose Roles +These recipes will show you how to use Moose roles. + =over 4 -=item L - The Moose::Role example +=item L - 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 - Advanced Role Composition - method exclusion and aliasing + +Sometimes you just want to include part of a role in your +class. Sometimes you want the whole role but one of its methods +conflicts with one in your class. With method exclusion and aliasing, +you can work around these problems. -=item L - Advanced Role Composition (TODO) +=item L - Applying a role to an object instance -=item L - Runtime Role Composition (TODO) +In this recipe, we apply a role to an existing object instance. =back =head2 Meta Moose +These recipes show you how to write your own meta classes, which lets +you extend the object system provided by Moose. + =over 4 -=item L - Welcome to the meta-world (TODO) +=item L - 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 - 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) and behavior to provide additional +attribute functionality. + +=item L - 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 - The meta-attribute example +=item L - Adding a "table" attribute to the metaclass -=item L - The meta-attribute trait example (TODO) +If you want to store more information about your classes, you'll have +to extend C. Doing so is simple, but you'll +probably also want to provide some sugar, so see +L as well. -=item L - The meta-instance example (TODO) +=item L - The "table" attribute implemented as a metaclass trait -=item L - The meta-class example (TODO) +This recipe takes the class metaclass we saw in the previous recipe +and reimplements it as a metaclass trait. + +=item L - A method metaclass for marking methods public or private + +This recipe shows a custom method metaclass that implements making a +method private. + +=item L - Using a blessed array reference as an object instance + +This recipe shows an example of how you create your own meta-instance +class. The meta-instance determines the internal structure of object +instances and provide access to attribute slots. + +=item Moose::Cookbook::Meta::Recipe8 - Hooking into immutabilization (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. =back -=head1 SEE ALSO +=head2 Extending Moose + +These recipes cover some more ways to extend Moose, and will be useful +if you plan to write your own C module. =over 4 -=item L +=item L - Moose extension overview + +There are quite a few ways to extend Moose. This recipe provides an +overview of each method, and provides recommendations for when each is +appropriate. + +=item L - 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 +module. + +=item L - 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 over and over. + +=item L - Acting like Moose.pm and providing sugar Moose-style + +This recipe shows how to provide a replacement for C. You +may want to do this as part of the API for a C module, +especially if you want to default to a new metaclass class or base +object class. =back -=head1 AUTHOR +=head1 SNACKS -Stevan Little Estevan@iinteractive.comE +=over 4 -=head1 COPYRIGHT AND LICENSE +=item L -Copyright 2006-2008 by Infinity Interactive, Inc. +=item L -L +=back -This library is free software; you can redistribute it and/or modify -it under the same terms as Perl itself. +=head1 SEE ALSO + +=over 4 + +=item L + +=back -=cut \ No newline at end of file +=cut