X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FManual%2FMooseX.pod;h=607bf35138cf6193cd6e87206676dceace618341;hb=c305a605cddbd97089f240ad9908a92bb1fa9828;hp=b447df9b0c95b12a927b716e7935bc21a1e4e687;hpb=b6eaf79785817508968a530d188ba4f4d5615999;p=gitmo%2FMoose.git diff --git a/lib/Moose/Manual/MooseX.pod b/lib/Moose/Manual/MooseX.pod index b447df9..607bf35 100644 --- a/lib/Moose/Manual/MooseX.pod +++ b/lib/Moose/Manual/MooseX.pod @@ -2,18 +2,18 @@ =head1 NAME -Moose::Manual::MooseX - Recommended Moose Extensions +Moose::Manual::MooseX - Recommended Moose extensions =head1 MooseX? -One of the great things about Moose is that it is easy to extend and -override. You can use the meta-model API to do things your own way, +It's easy to extend and change Moose, and this is part of what makes +Moose so powerful. You can use the MOP API to do things your own way, add new features, and generally customize your Moose. Writing your own extensions does require a good understanding of the -meta-model. You can start learning about thiswith the -L docs. There are also several extensions -recipes in the L. +meta-model. You can start learning about this with the +L docs. There are also several extension recipes +in the L. Explaining how to write extensions is beyond the scope of this manual. Fortunately, lots of people have already written extensions @@ -21,12 +21,11 @@ and put them on CPAN for you. This document covers a few of the ones we like best. -=head1 MooseX::AttributeHelpers +=head1 L -If you only look at one extension, it should be this one. The name -isn't the best, but what it does it provide the equivalent of -delegation for all of Perl's native data types, such as array -reference, hash references, numbers, strings, etc. +If you only look at one extension, it should be this one. It provides +the equivalent of delegation for all of Perl's native data types, such +as array reference, hash references, numbers, strings, etc. This lets you create I cleaner and fluent APIs. @@ -50,10 +49,10 @@ This lets you create I cleaner and fluent APIs. Instead of directly exposing an array reference, we have three well-named, easy to use methods. -=head1 MooseX::StrictConstructor +=head1 L By default, Moose lets you pass any old junk into a class's -constructor. If you load C, your class will +constructor. If you load L, your class will throw an error if it sees something it doesn't recognize; package User; @@ -66,15 +65,15 @@ throw an error if it sees something it doesn't recognize; User->new( name => 'Bob', emali => 'bob@example.com' ); -With C, that typo ("emali") will cause a -runtime error. Otherwise, the "emali" attribute would just be silently -ignored. +With L, that typo ("emali") will cause a +runtime error. With plain old Moose, the "emali" attribute would be +silently ignored. -=head1 MooseX::Params::Validate +=head1 L -We have high hopes for the future of C and -C. However, for now we recommend the decidely more -clunky (but also faster and simpler) C. This +We have high hopes for the future of L and +L. However, for now we recommend the decidedly more +clunky (but also faster and simpler) L. This module lets you apply Moose types and coercions to any method arguments. @@ -86,18 +85,18 @@ arguments. sub login { my $self = shift; my ($password) - = validatep( \@_, password => { isa => 'Str', required => 1 } ); + = validated_list( \@_, password => { isa => 'Str', required => 1 } ); ... } -=head1 MooseX::Getopt +=head1 L This is a role which adds a C method to your class. This is a constructor that takes the command line options and uses them to populate attributes. -Thia makes writing a command-line application as a module trivially +This makes writing a command-line application as a module trivially simple: package App::Foo; @@ -125,10 +124,14 @@ Then in the script that gets run we have: App::Foo->new_with_options->run; -=head1 MooseX::Singleton +From the command line, someone can execute the script: + + foo@example> foo --input /path/to/input --output /path/to/output + +=head1 L To be honest, using a singleton is often a hack, but it sure is a -handy hack. C lets you have a Moose class that's a +handy hack. L lets you have a Moose class that's a singleton: package Config; @@ -141,13 +144,11 @@ It's that simple. =head1 EXTENSIONS TO CONSIDER -There are literally dozens of other extensions on CPAN. These are a -few to consider. We're not quite ready to recommend them outright, -though. There's a couple reasons for this. One, they may be very -specialized. Two, they may be immature. Three, they may not be quite -right yet. Four, we may not all agree they're such a great idea. +There are literally dozens of other extensions on CPAN. This is a list +of extensions that you might find useful, but we're not quite ready to +endorse just yet. -=head2 MooseX::Declare +=head2 L Extends Perl with Moose-based keywords using C. Very cool, but still new and experimental. @@ -160,10 +161,10 @@ cool, but still new and experimental. method login (Str $password) { ... } } -=head2 MooseX::Types +=head2 L This extension helps you build a type library for your application. It -also lets you pre-declare type names and use them as barewords. +also lets you predeclare type names and use them as barewords. use MooseX::Types -declare => ['PosInt']; use MooseX::Types::Moose 'Int'; @@ -173,13 +174,13 @@ also lets you pre-declare type names and use them as barewords. => where { $_ > 0 } => message {"Int is not larger than 0"}; -One nice feature is the those bareword names are actually namespaces +One nice feature is that those bareword names are actually namespaced in Moose's type registry, so multiple applications can use the same bareword names, even if the type definitions differ. -=head2 MooseX::Types::Structured +=head2 L -This extension builds on top of C to let you declare +This extension builds on top of L to let you declare complex data structure types. use MooseX::Types -declare => [ qw( Name Color ) ]; @@ -195,7 +196,7 @@ complex data structure types. Of course, you could always use objects to represent these sorts of things too. -=head2 MooseX::ClassAttribute +=head2 L This extension provides class attributes for Moose classes. The declared class attributes are introspectable just like regular Moose @@ -210,34 +211,34 @@ attributes. class_has 'Cache' => ( ... ); -=head2 MooseX::Daemonize +=head2 L This is a role that provides a number of methods useful for creating a daemon, including methods for starting and stopping, managing a PID file, and signal handling. -=head2 MooseX::Role::Parameterized +=head2 L If you find yourself wanting a role that customizes itself for each consumer, this is the tool for you. With this module, you can create a role that accepts parameters and generates attributes, methods, etc on a customized basis for each consumer. -=head2 MooseX::POE +=head2 L This is a small wrapper that ties together a Moose class with C, and gives you an C sugar function to declare event handlers. -=head2 MooseX::FollowPBP +=head2 L Automatically names all accessors I-style, -"get_name" and "set_name". +"get_size" and "set_size". -=head2 MooseX::SemiAffordanceAccessor +=head2 L -Autoamtically names all accessors with an explicit set and implicit -get, "name" and "set_name". +Automatically names all accessors with an explicit set and implicit +get, "size" and "set_size". =head1 AUTHOR @@ -245,7 +246,7 @@ Dave Rolsky Eautarch@urth.orgE =head1 COPYRIGHT AND LICENSE -Copyright 2008 by Infinity Interactive, Inc. +Copyright 2009 by Infinity Interactive, Inc. L