NAME

Bolts::Bag - Helper for creating bags containing artifacts

VERSION

version 0.143171

SYNOPSIS

    use Bolts;

    my $meta = Bolts::Bag->start_bag(
        package => 'MyApp::Holder',
    );

    # In case the definition already ran...
    unless ($meta->is_finished_bag) {
        $meta->add_artifact(logger => Bolts::Artifact->new(
            name      => 'logger',
            blueprint => $meta->locator->acquire('blueprint', 'factory', {
                class => 'MyApp::Logger',
            },
            infer => 'acquisition',
            scope => $meta->locator->acquire('scope', 'singleton'),
        ));

        $meta->add_artifact(log_file => "var/messages.log");

        $meta->add_artifact(config => sub {
            return YAML::LoadFile("etc/config.yml");
        });

        $meta->finish_bag;
    }

    my $bag = $meta->name->new;

DESCRIPTION

This is a helper for creating bag objects. Technically, any object may be treated as a bag. However, this is the way Bolts creates bags through the sugar API in Bolts and some other internals. The primary benefit to creating this way is access to the bag meta locator during construction so you can use the standard blueprints, injectors, scopes, etc. in the standard way.

METHODS

start_bag

    my $meta = Bolts::Bag->start_bag(
        package        => 'MyApp::Bag',
        meta_locator   => Bolts::Meta::Locator->new,
        such_that_each => {
            does => 'MyApp::Role',
            isa  => 'MyApp::Thing',
        },
    );

This returns a Class::MOP::Class object representing the bag you want to define. The returned meta class will be created new if it does not yet exist. If it does already exist (as determined by "find_meta" in Moose::Util, the existing class will be returned.

It is good practice to always check to see if the definition of the bag has already been finished before continuing, which allows the definition code to be run more than once:

    if ($meta->is_finished_bag) {
        # some ->add_artifact calls here...
        
        $meta->finish_bag;
    }

You can then use the meta class to get an instance like so:

    my $bag = $meta->name->new(%params);

After getting the meta class returned from this class method, the remainder of the methods you need are found in Bolts::Meta::Class::Trait::Bag and Bolts::Meta::Class::Trait::Locator, which the returned object implement.

This class method takes the following parameters:

package

This is the package name to give the class within the Perl interpreter. If not given, the name will be anonymously chosen by Moose. It will also never return a finished class.

meta_locator

You may pass this in to customize the meta locator object to use with your class. This is Bolts::Meta::Locator by default.

such_that_each

This is used to limit the types of artifacts allowed within the bag. This is a hash that may contain one or both of these keys:

does

This names a Moose::Role that all artifacts returned from this bag must implement.

isa

This names a Moose type constraint that all artifacts returned from this bag must match.

AUTHOR

Andrew Sterling Hanenkamp <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Qubling Software LLC.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.