File Coverage

blib/lib/Bolts/Role/Locator.pm

Criterion	Covered	Total	%
statement	3	3	100.0
branch			n/a
condition			n/a
subroutine	1	1	100.0
pod			n/a
total	4	4	100.0

line	stmt	sub	time	code
1				package Bolts::Role::Locator;
2				$Bolts::Role::Locator::VERSION = '0.143171';
3				# ABSTRACT: Interface for locating artifacts in a bag
4
5	11	11	4460	use Moose::Role;
	11		16
	11		54
6
7
8				requires 'acquire';
9
10
11				requires 'acquire_all';
12
13
14				requires 'resolve';
15
16				1;
17
18				__END__
19
20				=pod
21
22				=encoding UTF-8
23
24				=head1 NAME
25
26				Bolts::Role::Locator - Interface for locating artifacts in a bag
27
28				=head1 VERSION
29
30				version 0.143171
31
32				=head1 DESCRIPTION
33
34				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.
35
36				The reference implementation of this interface is found in L<Bolts::Role::RootLocator>.
37
38				=head1 REQUIRED METHODS
39
40				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.
41
42				=head2 acquire
43
44				my $artifact = $loc->acquire(@path, \%options);
45
46				Given a C<@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.
47
48				The final argument, C<\%options>, is optional. It must be a reference to a hash to pass through to the final component to aid with resolution.
49
50				When complete, the complete, resolved artifact found is returned.
51
52				=head2 acquire_all
53
54				my @artifacts = @{ $loc->acquire_all(@path, \%options) };
55
56				This is similar to L<acquire>, but performs an extra step, the behavior of which varies slightly depending on what artifact is resolved on the component of C<@path>:
57
58				=over
59
60				=item *
61
62				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.
63
64				=item *
65
66				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.
67
68				=item *
69
70				In any other case, the final resolved artifact is returned as a single item list.
71
72				=back
73
74				The final argument is optional. As with L</acquire>, it is must be a hash reference and is passed to each of the artifacts during their resolution.
75
76				=head2 resolve
77
78				my $resolved_artifact = $loc->resolve($bag, $artifact, \%options);
79
80				After the artifact has been found, this method resolves the a partial artifact implementing the L<Bolts::Role::Artifact> and turns it into the complete artifact.
81
82				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 C<%options> are required. They are derefenced and passed to the L<Bolts::Role::Artifact/get> method, if the artifact being resolved implements L<Bolts::Role::Artifact>.
83
84				=head1 AUTHOR
85
86				Andrew Sterling Hanenkamp <hanenkamp@cpan.org>
87
88				=head1 COPYRIGHT AND LICENSE
89
90				This software is copyright (c) 2014 by Qubling Software LLC.
91
92				This is free software; you can redistribute it and/or modify it under
93				the same terms as the Perl 5 programming language system itself.
94
95				=cut