=pod

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

=encoding utf8

=head1 NAME

Data::Resolver::FromTar - resolver for TAR file

=head1 SYNOPSIS

   use Data::Resolver::FromTar;
   my $resolver = Data::Resolver::FromTar->new(root => $path);

   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 is fed from a TAR file in the
filesystem. It inherits from L<Data::Resolver::Base> and implements the
corresponding methods according to the expected semantics.

The class is provided a path to the TAR file in the filesystem and an
optional prefix; plain files in the archive will be considered valid assets
if they appear at the I<right> level, as well as directory objects will be
considere valid starting points for sub-resolvers.

Only files immediately below the provided prefix will be considered. E.g.
consider the following tree of files inside the archive:

   .
   ├── ciao.txt
   └── foo
      ├── bar.txt
      └── galook
         └── final.txt

If the prefix is empty, then C<ciao.txt> will be an exposed asset and C<foo>
will be a valid base for a sub-resolver; if the prefix is C<foo>, then the
available asset will be C<bar.txt> and the sub-resolver will be C<galook>;
and so on.

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

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

retrieve the file data 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 sub-directory C<$key>, as a new
object of class L<Data::Resolver::FromTar>. It is obtained by pointing to
the same TAR archive, but setting a different L</prefix>.

=head3 B<< has_asset >>

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

test existence of asset (file) for C<$key>.

=head3 B<< has_sub_resolver >>

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

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

=head3 B<< list_asset_keys >>

   sub list_asset_keys        ($self)       { ... }

return a list of file names available from the resolver.

=head3 B<< list_sub_resolver_keys >>

   sub list_sub_resolver_keys ($self)       { ... }

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

=head3 B<< prefix >>

   my $string = $obj->prefix;

get the prefix used for accessing sub-directories in a TAR archive.

=head3 B<< root >>

   my $dirpath = $obj->root;

The path to the base TAR file used for the resolver.


=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
