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

NAME

Bolts::Role::RootLocator - Interface for locating artifacts from some root 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. This actually also implements everything needed for the process except for the "root".

ROLES

REQUIRED METHODS

root

This is the object to use as the bag to start searching. It may be an object, a reference to an array, or a reference to a hash.

Caution: This will be renamed in the future.

METHODS

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.

After it finds the artifact, it will resolve the artifact using the "resolve" method, which is passed the (optional) %options.

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

Acquisition in this implementation proceeds according to the following rules:

  1. If the bag is an object:

    • If the object implements the Bolts::Role::Opaque role, lookup will end in an error.

    • If the object implements the Bolts::Role::Locator role, control of the lookup for the remaining components in @path will pass over to that object.

    • If the can method on the object returns false for the next component in @path, lookup will end in an error.

    • Finally, the method named in the next component in @path will be called and the result used as either the value to resolve or the next bag to locate within (repeating this process).

  2. If the bag is a hash, the name of the next component in @path will be used as a key in the hash to find the next value to resolve or the next bag to locate within.

  3. If the bag is an array and the name of the next component in @path is a number, it will be used as the index to fetch from the array to use as the value to resolve or the next bag to locate within.

  4. Anything else will result in lookup ending in an error.

acquire_all

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

This is similar to acquire, but returns the value as a reference to an array of resolved artifacts.

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.

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.