The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
MooseX-ShortCut-BuildInstance-v0.014.002
River stage one • 4 direct dependents • 4 total dependents
2 ++
/ README

MooseX::ShortCut::BuildInstance

This module is a shortcut to build Moose instances on the fly.

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 custom 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.

Even though this is a Moose based class it provides a functional interface.

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 should_re_use_classes. An alternative is to leave the package name out and let this class create a unique by-instance anonymous name.

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 four potential key value pairs. It then uses the Moose::Meta::Class module and the Moose::Util 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.

    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 four 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. This will overwrite any class in 'lib' with the same 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)

      add_roles_in_sequence: this will compose, in sequence, each role in the array ref into the class built on the prior three arguments using Moose::Util 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.

    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.

should_re_use_classes( $bool )

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

$MooseX::ShortCut::BuildInstance::instance_count

This is an integer that increments and appends to the anonymous package name for each new anonymous package created.

$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.

$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 cluck in warning.

SUPPORT

TODO

    1. Add a type package to manage the inputs to the exported methods

    2. Swap Smart::Comments for Log::Shiras

      (Get Log::Shiras CPAN-ready first!)

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.

This software is copyrighted (c) 2013 by Jed Lund

Dependencies

SEE ALSO

Install from Source

(for example git)

    1. Download a compressed file with the code

    2. Extract the code from the compressed file

    3. cd into the extracted directory

(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