NAME

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

SYNOPSIS

	#!perl
	use Modern::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 . '-';
	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 instances on the fly.

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 redundant to the Moose::Meta::Class->class(%args) method. The use of this method is best when paired with build_instance. This function takes take 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 here is that most key value pairs are optional! The caveat being that some 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 a BEGIN 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

Carp

SEE ALSO

Moose::Meta::Class ->create

Moose::Util ->with_traits

MooseX::ClassCompositor

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