=head1 MooseX::ShortCut::BuildInstance This module is a shortcut to build L instances on the fly. =head1 SYNOPSIS #!perl package Mineral; use Moose; has 'type' =>( is => 'ro' ); package Identity; use Moose::Role; has 'name' =>( is => 'ro' ); use MooseX::ShortCut::BuildInstance qw( build_instance ); use Test::More; use Test::Moose; my $paco = build_instance( package => 'Pet::Rock', superclasses =>['Mineral'], roles =>['Identity'], type => 'Quartz', name => 'Paco', ); does_ok( $paco, 'Identity', 'Check that the ' . $paco->meta->name . ' has an -Identity-' ); say 'My ' . $paco->meta->name . ' made from -' . $paco->type . '- (a ' . ( join ', ', $paco->meta->superclasses ) . ') is called -' . $paco->name . "-\n"; done_testing(); ############################################################################## # Output of SYNOPSIS # 01:ok 1 - Check that the Pet::Rock has an -Identity- # 02:My Pet::Rock made from -Quartz- (a Mineral) is called -Paco- # 03:1..1 ############################################################################## =head1 DESCRIPTION This module is a shortcut to custom build L class instances on the fly. The goal is to compose unique instances of Moose classes on the fly using roles in a L fashion. In other words this module accepts all the Moose class building goodness along with any roles requested, and any arguments required for a custom class instance and checks / fills in missing pieces as needed without stringing together a series of Class-Emethod( %args ) calls. Even though this is a Moose based class it provides a functional interface. =head1 WARNING Moose (and I think perl 5) can't have two classes with the same name but different guts coexisting! This means that if you build an instance against a given package name on the fly and then recompose a new instance with the same package name but containing different functionality all calls to the old instance will use the new package functionality for execution. (Usually causing hard to troubleshoot failures) If you are using the 'build_instance' method to generate multiple instances of the same class (by 'package' name) with different attribute settings then you should understand the functionality that is provided by L. An alternative is to leave the package name out and let this class create a unique by-instance anonymous name. =head1 Methods =head2 Methods for Export =head3 build_instance( %args|\%args ) =over B This method is used to create a Moose instance on the fly. I Basically this passes the %args intact to L and then runs $returned_class_name->new( %remaining_args ). B a hash or hashref of arguments. They must include the necessary information to build a class. I<(if you already have a class just call $class-Enew(); instead of this method!)> This hashref can also contain any attribute settings for the instance as well. B This will return a blessed instance of your new class with the passed attributes set. =back =head3 build_class( %args|\%args ) =over B This method is used to compose a Moose class on the fly. By itself it is (mostly) redundant to the L->class(%args) method. This function takes the passed arguments and strips out four potential key value pairs. It then uses the L module and the L module to build a new composed class. There are two incremental values provided by this method over Moose::Meta::Class->create. First, this method makes most of the class creation keys optional! The caveat being that some instance functionality must be passed either through a role or a class. Second, This method can compose roles into the class sequetially allowing for a role to 'require' a method from an earlier installed role. B a hash or hashref of arguments. I The four key-Evalue pairs use are; =over B This is the name (a string) that the new instance of a this class is blessed under. If this key is not provided the package will generate a generic name. This will L any class in 'lib' with the same name. B this is intentionally the same key from Moose::Meta::Class. It expects the same values. (Must be Moose classes) B this is intentionally the same key from Moose::Meta::Class. It expects the same values. (Must be Moose roles) B this will compose, in sequence, each role in the array ref into the class built on the prior three arguments using L apply_all_roles. This will allow an added role to 'require' elements of a role earlier in the sequence. The roles listed under 'role' are installed first and in a group. Then these roles are installed one at a time. =back B This will check the caller and see if it wants an array or a scalar. In array context it returns the new class name and a hash ref of the unused hash key/value pairs. These are presumably the arguments for the instance. If the requested return is a scalar it just returns the name of the newly created class. =back =head3 should_re_use_classes( $bool ) =over This sets/changes the global variable L =back =head1 GLOBAL VARIABLES =head4 $ENV{Smart_Comments} The module uses L if the '-ENV' option is set. The 'use' is encapsulated in an 'if' block triggered by the environmental variable to comfort non-believers. Setting the variable $ENV{Smart_Comments} will load and turn on smart comment reporting. There are three levels of 'Smartness' available in this module '### #### #####'. =head4 $MooseX::ShortCut::BuildInstance::instance_count This is an integer that increments and appends to the anonymous package name for each new anonymous package created. =head4 $MooseX::ShortCut::BuildInstance::built_classes This is a hashref that tracks the class names ('package's) built buy this class to manage duplicate build behaviour. =head4 $MooseX::ShortCut::BuildInstance::re_use_classes This is a boolean (1|0) variable that tracks if the class should overwrite or re-use a package name (and the defined class) from a prior 'build_class' call. If the package name is overwritten it will L in warning. =head1 SUPPORT =over L =back =head1 TODO =over B<1.> Add a type package to manage the inputs to the exported methods B<2.> Swap L for L =over (Get Log::Shiras CPAN-ready first!) =back =back =head1 AUTHOR =over Jed Lund jandrew@cpan.org =back =head1 COPYRIGHT This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module. This software is copyrighted (c) 2013 by Jed Lund =head1 Dependencies =over L L<5.010|http://perldoc.perl.org/perl5100delta.html> (for use of L //) L L L L L L - cluck L =back =head1 SEE ALSO =over L ->create L ->with_traits L L - is used if the -ENV option is set =back =head1 Install from Source (for example git) =over B<1.> Download a compressed file with the code B<2.> Extract the code from the compressed file B<3.> cd into the extracted directory =back (For Windows find what version of make was used to compile your perl) perl -V:make Then (adjusting make as needed) perl Makefile.PL make make test make install make clean