NAME

MooseX::ShortCut::BuildInstance - A shortcut to build Moose instances

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
    ##############################################################################

    

DESCRIPTION

This module is a shortcut to build Moose class instances on the fly. The goal is to compose unique instances of Moose classes on the fly using roles in a DCI 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->method( %args ) calls.

Methods

Methods for Export

build_instance( %args|\%args )

Definition: This method is used to create a Moose instance on the fly. 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 build_class and then runs $returned_class_name->new( %remaining_args );

Accepts: a hash or hashref of arguments. They must include the necessary information to build a class. (if you already have a class just call $class->new(); instead of this method!) This hashref can also contain any attribute settings for the instance as well.

Returns: This will return a blessed instance of your new class with the passed attributes set.

build_class( %args|\%args )

Definition: This method is used to compose a Moose class on the fly. By itself it is (mostly) redundant to the Moose::Meta::Class->class(%args) method. This function takes the passed arguments and strips out three potential key value pairs. It then uses the 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.

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

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.

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

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

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.

GLOBAL VARIABLES

$ENV{Smart_Comments}

The module uses Smart::Comments 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 '### #### #####'.

SUPPORT

MooseX-ShortCut-BuildInstance/issues

TODO

• Add a type package to manage the inputs to the exported methods

AUTHOR

Jed Lund

jandrew@cpan.org

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.

Dependencies

version

5.010 - use of defined or

Moose

Moose::Meta::Class

Moose::Exporter

SEE ALSO

Moose::Meta::Class ->create

Moose::Util ->with_traits

MooseX::ClassCompositor

Smart::Comments - is used if the -ENV option is set