NAME

App::Fetchware::Config - Manages App::Fetchware's internal representation of Fetchwarefiles.

VERSION

version 1.011

SYNOPSIS

    use App::Fetchware::Config ':CONFIG';

    my $some_config_sub_value = config('some_config_sub');
    $config_sub_value = config($config_sub_name, $config_sub_value);

    # You can also take advantage of config('config_sub_name') returning the
    # value if it exists or returning false if it does not to make ifs testing
    # if the value exists or not.
    if (config('config_sub_name')) {
        # config_sub_name exists in %CONFIG.
    } else {
        # config_sub_name does not exist in %CONFIG.
    }

    config_replace($name, $value);

    config_delete($name);

    __clear_CONFIG();

    debug_CONFIG();

DESCRIPTION

App::Fetchware::Config maintains an abstraction layer between fetchware and fetchware's internal Fetchwarefile represenation, which is inside %CONFIG inside App::Fetchware::Config.

App::Fetchware::Config gives the user a small, flexible API for manipulating fetchware's internal represenation of the user's Fetchwarefile. This API allows the user to get (via config()), set (via config()), replace (via config_replace()), delete (via config_delete()), delete all (via __clear_CONFIG()), and even debug (via debug_CONFIG()) the internal representation of the users Fetchwarefile.

NOTICE App::Fetchware::Config's represenation of your Fetchwarefile is per process. If you parse a new Fetchwarefile it will conflict with the existing %CONFIG, and various exceptions may be thrown.

%CONFIG is a global per process variable! You can not try to maniuplate more than one Fetchwarefile in memory at one time! It will not work! You can however use __clear_CONFIG() to clear the global %CONFIG, so that you can use it again. This is mostly just done in fetchware's test suite, so this design limitation is not such a big deal.

CONFIG SUBROUTINES

config()

    $config_sub_value = config($config_sub_name, $config_sub_value);

config() stores all of the configuration options that are parsed (actually executed) in your Fetchwarefile. They are stored in the %CONFIG variable that is lexically only shared with the private __clear_CONFIG() subroutine, which when executed simply clears %CONFIG for the next run of App::Fetchware in bin/fetchware's upgrade_all() subroutine, which is the only place multiple Fetchwarefiles may be parsed in on execution of bin/fetchware.

If config() is given more than 2 args, then the second arg, and all of the other arguments are stored in %CONFIG as an ARRAY ref. Also storing a second argument where there was a previously defined() argument will cause that element of %CONFIG to be promoted to being an ARRAY ref.

config_iter()

    # Create a config "iterator."
    my $mirror_iter = config_iter('mirror');

    # Use the iterator to return a new value of 'mirror' each time it is kicked,
    # called.
    my $mirror
    while (defined($mirror = $mirror_iter->())) {
        # Do something with this version of $mirror
        # Next iteration will "kick" the iterator again
    }

config_iter() returns an iterator. An iterator is simply a subroutine reference that when called (ex: $mirror_iter->()) will return the next value. And the coolest part is that the iterator will keep track of where it is in the list of values that configuration option has itself, so you don't have to yourself.

Iterators returned from config_iter() will return one or more elements of the configuration option that you specify has stored. After you exceed the length of the internal array reference the iterator will return false (undef).

config_replace()

    config_replace($name, $value);

    # Supports multiple values and arrays too.
    config_replace($name, $val1, $val2, $val3);
    config_replace($name, @values);

Allows you to replace the $value of the specified ($name) existing element of the %CONFIG internal hash. It supports multiple values and arrays, and will store those multiple values or arrays with an arrayref.

config_delete()

    config_delete($name);

delete's $name from %CONFIG.

__clear_CONFIG()

    __clear_CONFIG();

Clears the %CONFIG globalish variable. Meant more for use in testing, then for use in Fetchware itself, or in Fetchware extensions.

debug_CONFIG()

    debug_CONFIG();

Data::Dumper::Dumper()'s %CONFIG and prints it.

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.

BUGS

App::Fetchware::Config's represenation of your Fetchwarefile is per process. If you parse a new Fetchwarefile it will conflict with the existing %CONFIG, and various exceptions may be thrown.

%CONFIG is a global per process variable! You can not try to maniuplate more than one Fetchwarefile in memory at one time! It will not work! You can however use __clear_CONFIG() to clear the global %CONFIG, so that you can use it again. This is mostly just done in fetchware's test suite, so this design limitation is not such a big deal.

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