=pod

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

=encoding utf8

=head1 NAME

Data::Resolver::Base - (abstract) base for resolver classes


=head1 SYNOPSIS

   package My::New::Resolver;
   use Moo;
   extends 'Data::Resolver::Base';

   has foo => (is => 'ro', required => 1);
   ...

   sub get_asset              ($self, $key) { ... }
   sub get_sub_resolver       ($self, $key) { ... }
   sub has_asset              ($self, $key) { ... }
   sub has_sub_resolver       ($self, $key) { ... }
   sub list_asset_keys        ($self)       { ... }
   sub list_sub_resolver_keys ($self)       { ... }

   1;

=head1 DESCRIPTION

This class, based on L<Moo>, provides a base for deriving resolver classes.

A compliant resolver MUST implement both the asset and the sub-resolver
methods. Both types of elements from a resolver support three kind of
operations:

=over

=item B<< listing >>

get a list of assets (L</list_asset_keys>) or sub-resolvers
(L</list_sub_resolver_keys>).

=item B<< checking for existence of a key >>

check if an asset is present (L</has_asset>) or if a sub-resolver is
present (L</has_sub_resolver>).

=item B<< retrieval >>

get an asset as a L<Data::Resolver::Asset> (L</get_asset>), or get a
sub-resolver (L</get_sub_resolver>). In the latter case, the result is
supposed to be compliant to this interface, although it might be of a
different class from the starting object.

=back

Retrieval functions are supposed to throw an exception if the
corresponding key is not present; to this extent, the class composes
L</complain> and L</not_found> from L<Data::Resolver::RoleComplain>.

=head1 INTERFACE

This class composes the role L<Data::Resolver::RoleComplain>, allowing for
the optional usage of L<Ouch>.

=head2 METHODS

The following methods are available from the base class.

=head3 B<< asset >>

   my $asset = $obj->asset($key, $type, $value);

create an instance of class L<Data::Resolver::Asset>, setting the C<key> to
the provided C<$key>, setting slot C<$type> with the provided C<$value>, and
propagating the configurations for L<Data::Resolver::RoleComplain>.

=head3 B<< complain >>

Compound from L<Data::Resolver::RoleComplain/complain>.

=head3 B<< not_found >>

Compound from L<Data::Resolver::RoleComplain/not_found>.

=head3 B<< use_ouch >>

Compound from L<Data::Resolver::RoleComplain/use_ouch>.

=head2 ABSTRACT METHODS

The following methods are expected to be implemented:

=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>. It's supposed to be an
object that supports the same interface as any resolver, i.e. to derive from
this class too.

If sub-resolvers are not supported, this function MUST always throw an
exception.

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

If sub-resolvers are not supported, this function MUST always return a
false value.

=head3 B<< list_asset_keys >>

   sub list_asset_keys        ($self)       { ... }

return a list of strings, each representing a valid key for an asset
available from the resolver.

=head3 B<< list_sub_resolver_keys >>

   sub list_sub_resolver_keys ($self)       { ... }

return a list of strings, each representing a valid key for a sub-resolver
available from the resolver.

If sub-resolvers are not supported, this function MUST always return an
empty list.

=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
