X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FCookbook.pod;h=8e96f7129ef5ed674219cba84039f9d1cda5ae84;hb=48ac876af2c1991bd6cdba0d54b775a121e01725;hp=c5132b51673f278fbbf701ff61d8fd6d7519ad7c;hpb=2840a3b25fac3ab606e2053ce9ef30b39687270d;p=gitmo%2FMoose.git diff --git a/lib/Moose/Cookbook.pod b/lib/Moose/Cookbook.pod index c5132b5..8e96f71 100644 --- a/lib/Moose/Cookbook.pod +++ b/lib/Moose/Cookbook.pod @@ -1,84 +1,85 @@ +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 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. +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 -A simple Moose-based class. Demonstrated Moose attributes and subclassing. +A simple Moose-based class. Demonstrates basic Moose attributes and subclassing. -=item L - A simple B example +=item L -A slightly more complex Moose class. Demonstrates using a method -modifier in a subclass. +A slightly more complex Moose class. Demonstrates using a method modifier in a +subclass. -=item L - A lazy B example +=item L Demonstrates several attribute features, including types, weak -references, predicates ("does this object have a foo?"), defaults, and -lazy attribute uction. +references, predicates ("does this object have a foo?"), defaults, +laziness, and triggers. -=item L - Subtypes, and modeling a simple B class hierarchy +=item L -Introduces the creation and use of custom types, a C method, -and the use of C in a subclass. +Introduces the creation and use of custom types, a C method, and the +use of C in a subclass. This recipe also shows how to model a set of +classes that could be used to model companies, people, employees, etc. -=item L - More subtypes, coercion in a B class +=item L -More type examples, including the use of type coercions. +This recipe covers more subtype creation, including the use of type coercions. -=item L - The augment/inner example - -Demonstrates the use of C method modifiers, a way of turning -the usual method overriding style "inside-out". - -=item L - Making Moose fast with immutable +=item L Making a class immutable greatly increases the speed of accessors and object construction. -=item L - Managing complex relations with trigger (TODO) - -I - -Work off of this http://code2.0beta.co.uk/moose/svn/Moose/trunk/t/200_examples/007_Child_Parent_attr_inherit.t - -=item L - Builder methods and lazy_build +=item L - Builder methods and lazy_build The builder feature provides an inheritable and role-composable way to provide a default attribute value. -=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 - BUILD and BUILDARGS (TODO) +=item L + +This recipe demonstrates the use of C and C to hook +into object construction. + +=item L -We need a good recipe demonstrating how these work. +In this recipe, we make a Moose-based subclass of L, a +module which does not use Moose itself. + +=item L + +Demonstrates the use of C method modifiers, a way of turning +the usual method overriding style "inside-out". =back @@ -88,64 +89,64 @@ These recipes will show you how to use Moose roles. =over 4 -=item L - The Moose::Role example +=item L 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 +=item L Sometimes you just want to include part of a role in your -class. Sometimes you want the whole role but one if its methods +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 - Runtime Role Composition (TODO) +=item L -I +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 provide by Moose. +you extend the object system provided by Moose. =over 4 -=item L - Welcome to the meta-world (Why Go Meta?) +=item L 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 +=item L 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 - Adding a "table" attribute to the metaclass +=item L -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. +This recipe takes the class metaclass we saw in the previous recipe +and reimplements it as a metaclass trait. -=item L - The "table" attribute implemented as a metaclass trait +=item L -This example takes the class metaclass we saw in the previous recipe -and reimplements it as a metaclass trait. +This recipe shows a custom method metaclass that implements making a +method private. + +=item L + +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. + +In this particular instance, we use a blessed glob reference as the instance +instead of a blessed hash reference. -=item L - Hooking into the immutabilization system (TODO) +=item Hooking into immutabilization (TODO) Moose has a feature known as "immutabilization". By calling C<< __PACKAGE__->meta()->make_immutable() >> after defining your class @@ -160,10 +161,6 @@ meta-instance class as well. This recipe shows you how to write extensions which immutabilize properly. -=item L - I (TODO) - -I - =back =head2 Extending Moose @@ -173,27 +170,20 @@ if you plan to write your own C module. =over 4 -=item L - Moose extension overview +=item L -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. +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 +=item L 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 +=item L 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, @@ -212,25 +202,27 @@ object class. =back -=head1 SEE ALSO +=head1 Legacy Recipes + +These cover topics that are no longer considered best practice. We've kept +them in case in you encounter these usages in the wild. =over 4 -=item L +=item L -=back +=item L -=head1 AUTHOR +=item L -Stevan Little Estevan@iinteractive.comE +=back -=head1 COPYRIGHT AND LICENSE +=head1 SEE ALSO -Copyright 2006-2009 by Infinity Interactive, Inc. +=over 4 -L +=item L -This library is free software; you can redistribute it and/or modify -it under the same terms as Perl itself. +=back =cut