NAME

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

VERSION

version 1.006

SYNOPSIS

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

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 "CREATING A FETCHWARE EXTENSION" in App::Fetchware in App::Fetchware's documentation for more information on how to create your very own fetchware extension.

EXPORTAPI'S API METHODS

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

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.

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 (start(), lookup(), download(), verify(), unarchive(), build(), install(), and uninstall()) to the caller()'s @EXPORT. It also imports Exporter's import() subroutine to the caller's package, so that the caller has 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.

This is how fetchware extensions inherit whatever API subroutines that they want to reuse from App::Fetchware.

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

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 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 _export_api() 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.

ERRORS

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

AUTHOR

David Yingling <deeelwy@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 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.