X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FManual%2FMooseX.pod;h=c47d15fe3b5da8f28dbab3f08b5b7315850b3a21;hb=31c248bf3c003492975ce3f29dbe81fc6f78f655;hp=c76537fd45a5ded2dea6aac3f5c40aa505000188;hpb=2840a3b25fac3ab606e2053ce9ef30b39687270d;p=gitmo%2FMoose.git diff --git a/lib/Moose/Manual/MooseX.pod b/lib/Moose/Manual/MooseX.pod index c76537f..c47d15f 100644 --- a/lib/Moose/Manual/MooseX.pod +++ b/lib/Moose/Manual/MooseX.pod @@ -1,19 +1,21 @@ -=pod +package Moose::Manual::MooseX; + +# ABSTRACT: Recommended Moose extensions -=head1 NAME +__END__ -Moose::Manual::MooseX - Recommended Moose Extensions +=pod =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,39 +23,28 @@ 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. +The functionality of this MooseX module has been moved into Moose core. +See L. -This lets you create I cleaner and fluent APIs. +=head1 L - package User; +MooseX::AttributeHelpers, but turned inside out, Moose::Autobox provides +methods on both arrays/hashes/etc. but also references to them, using +Moose roles, allowing you do to things like: - use Moose; - use MooseX::AttributeHelpers; - - has '_orders' => ( - metaclass => 'Collection::Array', - is => 'ro', - isa => 'ArrayRef', - default => sub { [] }, - provides => { - push => 'add_order', - shift => 'next_order', - elements => 'orders', - }, - ); + use Moose::Autobox; + + $somebody_elses_object->orders->push($order); -Instead of directly exposing an array reference, we have three -well-named, easy to use methods. +Lexically scoped and not to everybody's taste, but very handy for sugaring +up other people's APIs and your own code. -=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,38 +57,43 @@ 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, these modules, while used regularly in +production by some of the more insane members of the community, are +still marked alpha just in case backwards incompatible changes need to +be made. + +If you don't want to risk that, 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. package User; use Moose; - use MooseX::Params::Validate qw( validatep ); + use MooseX::Params::Validate; 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,11 +121,19 @@ 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 -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 -singleton: +=head1 L + +To be honest, using a singleton is just a way to have a magic global +variable in languages that don't actually have global variables. + +In perl, you can just as easily use a global. However, if your +colleagues are Java-infected, they might prefer a singleton. Also, if +you have an existing class that I a singleton but should be, +using L is the easiest way to convert it. package Config; @@ -141,13 +145,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,26 +162,26 @@ 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 -declare => ['PositiveInt']; use MooseX::Types::Moose 'Int'; - subtype PositiveInt - => as Int, - => where { $_ > 0 } - => message {"Int is not larger than 0"}; + subtype PositiveInt, + as Int, + 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 +197,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,46 +212,51 @@ attributes. class_has 'Cache' => ( ... ); -=head2 MooseX::Daemonize +Note however that this class attribute does I inherit like a +L or similar attribute - calling + + $subclass->Cache($cache); + +will set it for the superclass as well. Additionally, class data is usually +The Wrong Thing To Do in a strongly OO program since it makes testing a +lot harder - consider carefully whether you'd be better off with an object +that's passed around instead. + +=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 +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". - -=head2 MooseX::SemiAffordanceAccessor - -Autoamtically names all accessors with an explicit set and implicit -get, "name" and "set_name". - -=head1 AUTHOR - -Dave Rolsky Eautarch@urth.orgE +"get_size" and "set_size". -=head1 COPYRIGHT AND LICENSE +=head2 L -Copyright 2009 by Infinity Interactive, Inc. +Automatically names all accessors with an explicit set and implicit +get, "size" and "set_size". -L +=head2 L -This library is free software; you can redistribute it and/or modify -it under the same terms as Perl itself. +MooseX::NonMoose allows for easily subclassing non-Moose classes with Moose, +taking care of the annoying details connected with doing this, such as +setting up proper inheritance from Moose::Object and installing +(and inlining, at make_immutable time) a constructor that makes sure things +like BUILD methods are called. =cut