NAME

Bolts::Artifact - Tools for resolving an artifact value

VERSION

version 0.143171

SYNOPSIS

    use Bolts;
    my $meta = Bolts::Bag->start_bag;

    my $artifact = Bolts::Artifact->new(
        meta_locator => $meta,
        name         => 'key',
        blueprint    => [ 'blueprint', 'factory', {
            class => 'MyApp::Thing',
        } ],
        scope        => [ 'scope', 'singleton' ],
        infer        => 'acquisition',
        parameters   => {
            foo => [ 'blueprint', 'given', {
                isa => 'Str',
            } ],
            bar => value 42,
        },
    );

DESCRIPTION

This is the primary implementation of Bolts::Role::Artifact with all the features described in Bolts, including blueprint, scope, inferrence, injection, etc.

ROLES

ATTRIBUTES

init_locator

If provided with a references to the meta-locator for the bag to which the artifact is going to be attached, the "blueprint", "scope", and "injectors" attributes may be given as initializers rather than as objects.

name

Required. This sets the name of the artifact that is being created. This is passed through as part of scope resolution (Bolts::Scope) and blueprint construction (Bolts::Blueprint).

blueprint

Required. This sets the Bolts::Blueprint used to construct the artifact.

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

scope

Required. This sets the Bolts::Scope used to manage the object's lifecycle.

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

  scope => bolts_init('scope', 'singleton'),

If so, you must provide a "init_locator".

infer

This is a setting that tells the artifact what kind of inferrence to perform when inferring injectors from the blueprint. This may e set to one of the following:

none

Default. When this is set, no inferrence is performed. The injectors will be defined according to "dependencies" only.

options

This tells the artifact to infer the injection using the parameters passed to the call to "acquire" in Bolts::Role::Locator. When the object is acquired and resolved, the caller will need to pass through any options needed for building the object.

acquisition

This tells the artifact to infer the injection using automatically acquired artifacts. The acquisition will happen from the bag containing the artifact with paths matching the name of the parameter.

Caution: The way this work is likely to be customizeable in the future and the default behavior may differ.

inference_done

This is an internal setting, which has a reader method named is_inference_done and a writer named inference_is_done. Do not use the writer directly unless you know what you are doing. You cannot set this attribute during construction.

Normally, this is a true value after the automatic inference of injectors has been completed and false before.

injectors

This is an array of Bolts::Injectors, which are used to inject values into or after the construction process. Anything set here will take precedent over inferrence.

Instead of passing the array of injector objects in directly, you can provide an array of initializers, each as an array reference, similar to what you would pass to acquire for each to get each injector from the meta-locator, e.g.:

  injector => [
      bolts_init('injector', 'parameter_name', {
          key       => 'foo',
          blueprint => bolts_init('blueprint', 'literal', {
              value => 42,
          }),
      }),
  ]

If so, you must provide a "init_locator".

does

This is used to control the role the artifact constructed must impement. Usually, this is not set directly, but set by the bag instead as an additional control on bag contents.

isa

This is used to control the type of the constructed artifact. Usually, this is not set directly, but set by the bag instead as an additional control on bag contents.

METHODS

infer_injectors

This performs the inference of "injectors" based upon the "infer" setting. This is called automatically when the artifact is resolved.

such_that

This is a helper for setting "does" and "isa". The bag that contains the artifact normally calls this to enforce type constriants on the artifact.

get

This is called during the resolution phase of Bolts::Role::Locator to either retrieve the object from the "scope" or construct a new object according to the "blueprint".

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.