=pod

=for vim
   vim: tw=72 ts=3 sts=3 sw=3 et ai :

=encoding utf8

=head1 NAME

Data::Resolver::Alternatives - resolver from other resolvers

=head1 SYNOPSIS

   use Data::Resolver::Alternatives;
   use Data::Resolver::FromDir;
   use Data::Resolver::FromTar;

   my $dir1 = Data::Resolver::FromDir->new(root => $path);
   my $dir2 = Data::Resolver::FromDir->new(root => $other_path);
   my $tar  = Data::Resolver::FromTar->new(root => $path_to_tar);

   # one to rule them all
   my $resolver = Data::Resolver::Alternatives->new(
      alternatives => [ $dir1, $dir2, $tar ]);

   my @list_of_asset_keys = $resolver->list_asset_keys;
   say 'have it' if $resolver->has_asset($key);
   my $asset = $resolver->get($key);

   my @list_of_sub_resolver_keys = $resolver->list_sub_resolver_keys;
   say 'have it' if $resolver->has_sub_resolver($srkey);
   my $sub_resolver = $resolver->get_sub_resolver($srkey);


=head1 DESCRIPTION

This class implements a resolver that relies upon a list of I<alternatives>,
which are in turn resolvers which are tried in order to complete the
required operation.

Operations for individual keys (either check or retrieval) are performed by
selecting the first candidate that supports the key and then applying the
operation upon it. On the other hand, lists are collected from all
alternatives, removing duplicates.

Resolvers appearing first in the provided L</alternatives> will be tried
first.


=head1 INTERFACE

This class inherits from L<Data::Resolver::Base>, inheriting all of its
methods and overloading the abstract ones, while keeping the expected
semantics.

=head2 METHODS

=head3 B<< alternatives >>

   my $array_ref = $obj->alternatives;

The list of alternatives that are used for operating.

=head3 B<< get_asset >>

   sub get_asset              ($self, $key) { ... }

retrieve the asset associated to C<$key>, as a L<Data::Resolver::Asset>.

=head3 B<< get_sub_resolver >>

   sub get_sub_resolver       ($self, $key) { ... }

retrieve the sub-resolver associated to C<$key>.

Note that, in general, the sub-resolver will be of a different class from
this one. This is considered a feature.

=head3 B<< has_asset >>

   sub has_asset              ($self, $key) { ... }

test existence of asset for C<$key>.

=head3 B<< has_sub_resolver >>

   sub has_sub_resolver       ($self, $key) { ... }

test existence of sub-resolver for C<$key>.

=head3 B<< list_asset_keys >>

   sub list_asset_keys        ($self)       { ... }

return a list of asset names available from the resolver.

=head3 B<< list_sub_resolver_keys >>

   sub list_sub_resolver_keys ($self)       { ... }

return a list of sub-resolver names available as sub-resolvers.


=head1 AUTHOR

Flavio Poletti <flavio@polettix.it>

=head1 COPYRIGHT AND LICENSE

Copyright 2023 by Flavio Poletti <flavio@polettix.it>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


=cut
