NAME

Bolts::Injector - inject options and parameters into artifacts

VERSION

version 0.143171

SYNOPSIS

    package MyApp::CustomInjector;
    use Moose;

    with 'Bolts::Injector';

    sub pre_inject_value {
        my ($self, $loc, $value, $param) = @_;
        $param->set($self->key, $value);
    }

    sub post_inject_value {
        my ($self, $loc, $value, $artifact) = @_;
        $artifact->set($self->key, $value);
    }

DESCRIPTION

Defines the interface that injectors use to inject dependencies into an artifact being resolved. While the locator finds the object for the caller and the blueprint determines how to construct the artifact, the injector helps the blueprint by passing through any parameters or settings needed to complete the construction.

This is done in two phases, with most injectors only implementing one of them:

  1. Pre-injection. Allows the injector to configure the parameters sent through to blueprint's builder method, such as might be needed when constructing a new object.

  2. Post-injection. This phase gives the injector access to the newly constructed but partially incomplete object to perform additional actions on the object, such as calling methods to set additional attributes or activate state on the object.

This role provides the tools necessary to allow the injection implementations to focus only on the injection process without worrying about the value being injected.

ATTRIBUTES

init_locator

If provided with a reference to the meta-locator for the bag to which the injector is going to be attached, the blueprint may be given as initializers.

key

This is the key used to desribe what the injector is injecting. This might be a parameter name, an array index, or method name (or any other descriptive string).

blueprint

This is the blueprint that defines how the value being injected will be constructed. So, not only is the injector part of the process of construction, but it has its own blueprint for constructing the value needed to perform the injection.

All the injector needs to worry about is the "get" method, which handles the process of getting and validating the value for you.

Instead of passing the blueprint object in directly, you can provide an initializer in an array reference, similar to what you would pass to acquire to get the blueprint from the meta-locator, e.g.:

    blueprint => bolts_init('blueprint', 'acquire', {
        path => [ 'foo' ],
    }),

If so, you must provide an "init_locator".

does

This is a type constraint describing what value is expected for injection. This is checked within "get".

isa

This is a type constraint describing what value is expected for injection. This is checked within "get".

OVERRIDDEN METHODS

pre_inject_value

    $injector->pre_inject_value($loc, $value, $param);

This method is called first, before the artifact has been constructed by the parent blueprint.

The $loc provides the context for the injector. It is the bag that contains the artifact being constructed. The $value is the value to be injected. The $param is the value to inject into, which will be passed through to the blueprint for use during construction.

If your injector does not provide any pre-injection, do not implement this method.

post_inject_value

    $injector->post_inject_value($loc, $value, $artifact);

This method is called after the blueprint has already constructed the object for additional modification.

The $loc provides the context for the injector. It is the bag that contains the artifact being constructed. The $value is the value to be injected. The $artifact is the constructed artifact to be injected into.

If your injector does not provide any post-injection, do not implement this method.

METHODS

pre_inject

   $injector->pre_inject($loc, $options, $param);

Performs the complete process of pre-injection, calling "pre_inject_value", if needed.

post_inject

    $injector->post_inject($loc, $options, $artifact);

Performs the complete process of post-injection, calling "post_inject_value", if needed.

exists

    my $exists = $injector->exists($loc, $options);

Returns true if the blueprint reports the value for injection exists. Injection is skipped if it does not exists.

get

    my $value = $injector->get($loc, $options);

These are used by "pre_inject" and "post_inject" to acquire the value to be injected.

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.