/ 
Bolts-0.143171
River stage zero No dependents
/ Bolts::Role::Locator

NAME

Bolts::Role::Locator - Interface for locating artifacts in a bag

VERSION

version 0.143171

DESCRIPTION

This is the interface that any locator must implement. A locator's primary job is to provide a way to find artifacts within a bag or selection of bags. This performs the acquisition and resolution process.

The reference implementation of this interface is found in Bolts::Role::RootLocator.

REQUIRED METHODS

Note that the behavior described here is considered the ideal and correct behavior. If it works within your application to fudge on this specifications a little bit, that's your choice, but the implementations provided by the Bolts library itself should adhere to these requirements perfectly.

acquire

my $artifact = $loc->acquire(@path, \%options);

Given a @path of symbol names to traverse, this goes through each artifact in turn, resolves it, if necessary, and then continues to the next path component.

The final argument, \%options, is optional. It must be a reference to a hash to pass through to the final component to aid with resolution.

When complete, the complete, resolved artifact found is returned.

acquire_all

my @artifacts = @{ $loc->acquire_all(@path, \%options) };

This is similar to acquire, but performs an extra step, the behavior of which varies slightly depending on what artifact is resolved on the component of @path:

  • If the last resolved artifact is a reference to an array, then all the artifacts within that bag are acquired, resolved, and returned as a reference to an array.

  • If the last resolved artifact is a reference to a hash, then all the values within are pulled, resolved, and returned as a reference to an array.

  • In any other case, the final resolved artifact is returned as a single item list.

The final argument is optional. As with "acquire", it is must be a hash reference and is passed to each of the artifacts during their resolution.

resolve

my $resolved_artifact = $loc->resolve($bag, $artifact, \%options);

After the artifact has been found, this method resolves the a partial artifact implementing the Bolts::Role::Artifact and turns it into the complete artifact.

This method is called during each step of acquisition to resolve the artifact (which might be a bag) at each step, including the final step. The given %options are required. They are derefenced and passed to the "get" in Bolts::Role::Artifact method, if the artifact being resolved implements Bolts::Role::Artifact.

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.