File Coverage

blib/lib/App/Fetchware/ExportAPI.pm

Criterion	Covered	Total	%
statement	39	39	100.0
branch	8	10	80.0
condition			n/a
subroutine	8	8	100.0
pod			n/a
total	55	57	96.4

package App::Fetchware::ExportAPI;
$App::Fetchware::ExportAPI::VERSION = '1.014';
# ABSTRACT: Used by fetchware extensions to export their API subroutines.
use strict;
use warnings;

# CPAN modules making Fetchwarefile better.
use Sub::Mage;

# ExportAPI takes advantage of CreateConfigOption's _create_config_options() and
# _add_export() to do its dirty work.
use App::Fetchware::CreateConfigOptions ();
# _create_config_options() clone()'s some of App::Fetchware's API subroutines
# when a fetchware extension "KEEP"s them, so I must load it, so I can access
# these subroutines.
use App::Fetchware ();

# Enable Perl 6 knockoffs, and use 5.10.1, because smartmatching and other
# things in 5.10 were changed in 5.10.1+.
use 5.010001;

# Don't use Exporter's import; instead, provide your own. This is all ExportAPI
# does. Provide an import() method, so that it can set up correct exports, and
# ensure that your fetchware extension implementes all of fetchware's API
# subroutines at compile time.



sub import {
    my ($class, @opts) = @_;

    # Just return success if user specified no options, because that just means
    # the user wanted to load the module, but not actually import() anything.
    return 'Success' if @opts == 0;

    my $caller = caller;

    # Forward call to _export_api(), which does all the work.
    _export_api($caller, @opts);
}


# _export_api() has pretty much the same documentation as import() above, and
# why copy and paste any changes I make, when this not here makes more sense?
sub _export_api {
    my ($callers_package_name, %opts) = @_;

    # clone() Exporter's import() into $callers_package_name, because
    # fetchware extensions use Exporter's import() when fetchware eval()'s
    # Fetchwarefile's that use that extension. Exporter's import() is what makes
    # the magic happen.
    clone(import => (from => 'Exporter', to => $callers_package_name));

    my %api_subs = (
        check_syntax => 0,
        new => 0,
        new_install => 0,
        start => 0,
        lookup => 0,
        download => 0,
        verify => 0,
        unarchive => 0,
        build => 0,
        install => 0,
        end => 0,
        uninstall => 0,
        upgrade => 0,
    );

    # Check %opts for correctness.
    for my $sub_type (@opts{qw(KEEP OVERRIDE)}) {
        # Skip KEEP or OVERRIDE if it does not exist.
        # Needed, because the obove hash slice access will create it if it does
        # not already exist.
        next unless defined $sub_type;
        for my $sub (@{$sub_type}) {
            if (exists $api_subs{$sub}) {
                $api_subs{$sub}++;
            }
        }
    }

    # Use (scalar keys %api_subs) to dynamically determine how many API subs
    # there are. I've implemented all of the ones that I've planned, but another
    # upgrade() or check_syntax() could come out of now where, so calculate how
    # many there are dynamically, and then I only have to remember to update
    # %api_subs; instead, of that and also incrementing a constant integer
    # that's now properly a constant.
    die <
App-Fetchware-ExportAPI: _export_api() or import() must be called with either or
both of the KEEP and OVERRIDE options, and you must supply the names of all of
fetchware's API subroutines to either one of these 2 options.
EOD

    # Import any KEEP subs from App::Fetchware.
    for my $sub (@{$opts{KEEP}}) {
        clone($sub => ( from => 'App::Fetchware', to => $callers_package_name));

    }

    # Also import any subroutines the fetchware extension developer wants to
    # keep unless the fetchware extension developer does not want them.
    App::Fetchware::CreateConfigOptions::_create_config_options(
        $callers_package_name,
        IMPORT => $opts{KEEP})
            unless $opts{NOIMPORT};

    ###LIMITATION###You may want _export_api() and import() and ExportAPI to
    #check if all of the required fetchware extension API subroutines have been
    #implemented by our caller using something like
    #"$callers_package_name"->can($sub), but this can't work, because ExportAPI
    #is run inside an implied BEGIN block, from the use(), That means that the
    #rest of the file has *not* been compiled yet, so any subroutines defined
    #later on in the same file have not actually been compiled yet, so any use
    #of can() to lookup if they exist yet will fail, because they don't actually
    #exist yet. But if they have been properly defined, they will properly
    #exist.
    #
    #Therefore, I have moved checking if all of the proper API subroutines have
    #been defined properly to bin/fetchware's parse_fetchwarefile(), because
    #after the Fetchwarefile has been eval()'s the API subroutines should be in
    #bin/fetchware's namespace, so it just uses Sub::Mage's sublist() to see if
    #they all exist.


    # _create_config_options() takes care of setting up KEEP's exports, but
    # I need to ensure OVERRIDE's exports are also set up.
    App::Fetchware::CreateConfigOptions::_add_export(
        $_, $callers_package_name)
            for @{$opts{OVERRIDE}};
}


1;

__END__