=head1 MooseX::ShortCut::BuildInstance

This module is a shortcut to build 
L<Moose|https://metacpan.org/module/Moose::Manual> 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<Moose> class instances on the fly.  
The goal is to compose unique instances of Moose classes on the fly using roles 
in a L<DCI|https://en.wikipedia.org/wiki/Data,_Context,_and_Interaction> 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-E<gt>method( %args ) calls.

=head1 Methods

=head2 Methods for Export

=head3 build_instance( %args|\%args )

=over

=item B<Definition:> This method is used to create a Moose instance on the fly.  
I<It assumes that you do not have the class pre-built and will look for the 
needed information to compose a new class as well.>  Basically this passes the 
%args intact to L<build_class|/build_class( %args|\%args )> and then runs 
$returned_class_name->new( %remaining_args );

=item B<Accepts:> 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-E<gt>new(); instead of this method!)> This hashref can also 
contain any attribute settings for the instance as well.


=item B<Returns:> This will return a blessed instance of your new class with 
the passed attributes set.

=back

=head3 build_class( %args|\%args )

=over

=item B<Definition:> This method is used to compose a Moose class on the fly.  
By itself it is (mostly) redundant to the L<Moose::Meta::Class>->class(%args) 
method.  This function takes the passed arguments and strips out three potential 
key value pairs.  It then uses the L<Moose::Meta::Class> module to build a new 
composed class.  The one additional value of this method over Moose::Meta::Class 
is that most key value pairs are optional!  The caveat being that some instance 
functionality must be passed either through a role or a class.  This function 
will handle any other missing key/value pairs not passed.

=item B<Accepts:> a hash or hashref of arguments.  I<These keys are always used 
to build the class.  They are never passed on to %remaining_args.>  The three key 
value pairs use are;

=over

=item B<package> - 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.

=item B<superclasses> - this is intentionally the same key from 
Moose::Meta::Class.  It expects the same values. (Must be Moose classes)

=item B<roles> - this is intentionally the same key from Moose::Meta::Class.  
It expects the same values. (Must be Moose roles)

=back

=item B<Returns:> 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

=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