/ 
App-Fetchware-1.016
River stage zero No dependents
/ App::Fetchware::ExportAPI

NAME

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

VERSION

version 1.016

SYNOPSIS

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

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

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 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 KEEP type is how fetchware extensions inherit whatever API subroutines that they want to reuse from App::Fetchware, while 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.

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.

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

AUTHOR

David Yingling <deeelwy@gmail.com>

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.