view release on metacpan or  search on metacpan

lib/App/Fetchware/ExportAPI.pm  view on Meta::CPAN

__END__

=pod

=head1 NAME

App::Fetchware::ExportAPI - Used by fetchware extensions to export their API subroutines.

=head1 VERSION

version 1.016

=head1 SYNOPSIS

    use App::Fetchware::ExportAPI KEEP => [qw(start end new_install)],
        OVERRIDE =>
            [qw(new lookup download verify unarchive build install uninstall
            upgrade check_syntax)];

=head1 DESCRIPTION

App::Fetchware::ExportAPI is a utility helper class for fetchware extensions. It
makes it easy to ensure that your fetchware extension implements or imports all
of App::Fetchware's required API subroutines.

See section L<App::Fetchware/CREATING A FETCHWARE EXTENSION> in App::Fetchware's
documentation for more information on how to create your very own fetchware
extension.

=head1 EXPORTAPI'S API METHODS

App::Fetchware::ExportAPI (ExportAPI) has only one user-servicable part--it's
import() method. It works just like L<Exporter>'s import() method except it
takes arguments differently, and checks it's arguments more thoroughly.

It's import() method is what does the heavy lifting of actually importing any
"inherited" Fetchware API subroutines from App::Fetchware, and also setting up
the caller's exports, so that the caller also exports all of Fetchware's API
subroutines.

=head2 import()

    # You don't actually call import() unless you're doing something weird.
    # Instead, use calls import for you.
    use App::Fetchware::ExportAPI KEEP => [qw(start end)],
        OVERRIDE =>
            [qw(lookup download verify unarchive build install uninstall)];

    # But if you really do need to run import() itself.
    BEGIN {
        require App::Fetchware::ExportAPI;
        App::Fetchware::ExportAPI->import(KEEP => [qw(start end)],
            OVERRIDE =>
                [qw(lookup download verify unarchive build install uninstall)]
        );
    }

Adds fetchware's API subroutines (new(), new_install(), check_syntax(), start(),
lookup(), download(), verify(), unarchive(), build(), install(), end(),
uninstall(), and upgrade()) to the caller()'s  @EXPORT.  It also imports
L<Exporter>'s import() subroutine to the caller's package, so that the caller 
as a proper import() subroutine that Perl will use when someone uses your
fetchware extension in their fetchware extension. Used by fetchware extensions
to easily add fetchware's API subroutines to your extension's package exports.

The C<KEEP> type is how fetchware extensions I<inherit> whatever API subroutines that they
want to reuse from App::Fetchware, while C<OVERRIDE> specifies which API
subroutines this Fetchware extension will implement itself or "override".

Normally, you don't actually call import(); instead, you call it implicity by
simply use()ing it.

=over

=item NOTE

All API subroutines that exist in App::Fetchware's API must be mentioned in the
call to import (or implicitly via use). You do not have to OVERRIDE them all,
but those that you do not OVERRRIDE must be mentioned in KEEP. The KEEP tag does
not cause import() to actually do anything with them, but they nevertheless must
be mentioned. 

=back

=over

=item WARNING

_export_api() also imports Exporter's import() method into its
$callers_package_name. This is absolutely required, because when a user's
Fetchwarefile is parsed it is the C<use App::Fetchware::[extensionname];> line
that imports fetchware's API subrotines into fetchware's namespace so its
internals can call the correct fetchware extension. This mechanism simply uses
Exporter's import() method for the heavy lifting, so import() B<must> also
ensure that its caller gets a proper import() method.

If no import() method is in your fetchware extension, then fetchware will fail
to parse any Fetchwarefile's that use your fetchware extension, but this error
is caught with an appropriate error message.

=back

=head1 ERRORS

As with the rest of App::Fetchware, App::Fetchware::ExportAPI does not return 
any error codes; instead, all errors are die()'d if it's Test::Fetchware's error,
or croak()'d if its the caller's fault.

=head1 AUTHOR

David Yingling <deeelwy@gmail.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by David Yingling.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut