NAME

App::Fetchware::Fetchwarefile - Helps Fetchware extensions create Fetchwarefiles.

VERSION

version 1.014

SYNOPSIS

    use App::Fetchware::Fetchwarefile;

    # First create a new Fetchwarefile object.
    App::Fetchware::Fetchwarefile->new(
        header => <<EOF,
    use App::Fetchware;
    # Auto generated @{[localtime()]} by fetchware's new command.
    # However, feel free to edit this file if fetchware's new command's
    # autoconfiguration is not enough.
    # 
    # Please look up fetchware's documentation of its configuration file syntax at
    # perldoc App::Fetchware, and only if its configuration file syntax is not
    # malleable enough for your application should you resort to customizing
    # fetchware's behavior. For extra flexible customization see perldoc
    # App::Fetchware.
    EOF
        descriptions => {
            program => <<EOD,
    program simply names the program the Fetchwarefile is responsible for
    downloading, building, and installing.
    EOD
            temp_dir => <<EOD,
    temp_dir specifies what temporary directory fetchware will use to download and
    build this program.
    EOD
        
            ...
        }
    );

    ...

    # Then add whatever configuration options you need.
    $fetchwarefile->config_options(temp_dir => '/var/tmp');
    $fetchwarefile->config_options(no_install => 'True');
    $fetchwarefile->config_options(make_options => '-j 4');
    ...
    $fetchwarefile->config_options(
        temp_dir => 'var/tmp',
        program => 'Example',
        ...
        make_options => '-j $',
    );

    ...

    # Turn the Fetchwarefile object into a string or saving or executing.
    my $fetchwarefile_text = $fetchwarefile->generate();

DESCRIPTION

App::Fetchware::Fetchwarefile (Fetchwarefile) is an Object-Oriented Module that allows you to programatically build an example Fetchwarefile for your user.

This is done by providing a "header" that will go first in your Fetchwarefile that must include your Fetchware extension's use App::FetchwareX::...; line, and a "description", which is a hashref of configuration options and descriptions for those configuration options. These "descriptions" will be printed before each associate configuration option, so the user does not need to read the documentation as much.

Next, you call config_options() as many times as needed to added whatever condiguration options and their associated values to your Fetchwarefile.

Finally, you call generate(), which "generates" your Fetchwarefile by just concatenating all of the different strings together making sure the whitespace between them isn't screwed up.

FETCHWAREFILE METHODS

new()

    App::Fetchware::Fetchwarefile->new(
        header => <<EOF,
    use App::Fetchware;
    # Auto generated @{[localtime()]} by fetchware's new command.
    # However, feel free to edit this file if fetchware's new command's
    # autoconfiguration is not enough.
    # 
    # Please look up fetchware's documentation of its configuration file syntax at
    # perldoc App::Fetchware, and only if its configuration file syntax is not
    # malleable enough for your application should you resort to customizing
    # fetchware's behavior. For extra flexible customization see perldoc
    # App::Fetchware.
    EOF
        descriptions => {
            program => <<EOD,
    program simply names the program the Fetchwarefile is responsible for
    downloading, building, and installing.
    EOD
            temp_dir => <<EOD,
    temp_dir specifies what temporary directory fetchware will use to download and
    build this program.
    EOD
        
            ...
        }
    );

new() constructs new App::Fetchware::Fetchwarefile objects that represent Fetchwarefiles. It uses per insance data instead of globals, so you can create multiple Fetchwarefile objects if you want to, or need to in your test suite.

Both of its options header and descriptions are required, and must be a faux hash instead of actual hashref to avoid another layer of annoying braces.

header should be a string that is the header of your Fetchwarefile, which just means it should be a message that includes your extension's use App::FetchwareX::ExtensionName as well as a brief comment block explaining that this Fetchwarefile was autogenerated, and whatever helpful info you want to add about it such as where the documentation for it is, and so on.

descriptions should be a hashref whoose keys are this Fetchwarefile object's associated App::Fetchware extension's configuration options. It must include all of them. The values of these keys should be brief descriptions of each configuration option intended to be prepended above each configuration option in the generated Fetchwarefile.

The values of the keys of descriptions are turned into a Fetchwarefile as shown below...

    ...

    # program simply names the program the Fetchwarefile is responsible for
    # downloading, building, and installing.
    program 'my program';


    # temp_dir specifies what temporary directory fetchware will use to download and
    # build this program.
    temp_dir '/var/tmp';

    ...

config_options()

    $fetchwarefile->config_options(temp_dir => '/var/tmp');

    # And you can set multiple config options in one call.
    $fetchwarefile->config_options(
        temp_dir => 'var/tmp',
        program => 'Example',
        ...
        make_options => '-j $',
    );

config_options() should be used as needed to add whatever options to your Fetchwarefile as needed. Can be called more than once for each configuration option, and when it is, it promotes that key to an arrayref, and stores a list of options. config_options() also supports adding multiple "values" to one object in just one call to support MANY type configuration options.

generate()

    my $fetchwarefile_text = $fetchwarefile->generate();

    print $fetchwarefile->generate();

generate() takes the header and descriptions that new() added to your $fetchwarefile object along with whatever configuration options you have also added to your $fetchwarefile object with config_option(), and generates and returns a string that represents your Fetchwarefile. You can then change it as needed, or just store it in a file for the user to use later on.

ERRORS

As with the rest of App::Fetchware, App::Fetchware::Config does not return any error codes; instead, all errors are die()'d if it's App::Fetchware::Config'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.

cpanm App::Fetchware

perl -MCPAN -e shell
install App::Fetchware