The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Config-Source-0.08
River stage zero No dependents
++
/ Config::Source

NAME

Config::Source - manage a configuration from multiple sources

VERSION

Version 0.08

SYNOPSIS

    use Config::Source;

    my $config = Config::Source->new;
    $config->add_source( get_default_config() );
    
    # override values from the default keys with
    $config->add_source( File::Spec->catfile( $HOME, '.application', 'config' ) );
    
    # and now with
    $config->add_source( '/etc/application.config' );
    
    my $value = $config->get( 'user.key' );
    $config->set( 'user.key' => $value );
    
    $config->save_file( File::Spec->catfile( $HOME, '.application', 'config' ) );

    sub get_default_config {
        return {
            'app.name' => '...',
            'app.version' => 1,
            'user.key' => 'test',
            'user.array' => [ 200, 300 ],
            'user.deeper.struct' => { a => 'b', c => [ 'd', 'e' ] },
        };
    }

DESCRIPTION

This module allows defining and loading multiple sources to generate a configuration.

Sometimes you want a configuration initially provided by your application, but partially or fully redefined at multiple locations. You can have a default configuration distributed with your program and under your control as developer. On the first startup you want to generate a user configuration file to store individual relevant data. And for the administration, you want to provide a central configuration file indented to specify shared resources. You may also want a file which is only loaded on debug sessions.

This module uses Perl data structures for representing your configuration. It can also assure, that you only work with a true copy of the data.

CONFIGURATION FILE

Your configuration file must simply return an hash with the last evaluated statement. Additionally, you can use all the perl code you want. But this code is discarded if you save your config back.

This module proposes a flat hash for storing your configuration. It treats everything behind the first level of keys as a value.

instead of writing:

    {
        'log' => {
            'file' => 'path',
            'level' => 'DEBUG',
        },
    }

you should write:

    {
        'log.file' => 'path,
        'log.level' => 'DEBUG',
    }

Of course, you can use any separator in the string you want.

If you want get a more hierarchical access, take a look at Config::Source::Hierarchical (not implemented, currently only a throught).

METHODS

new( parameter => value, ... )

All the following parameter are optional.

clone_get

If true, then every time you try to get a ref-data, a clone will performed, before returning it. Default is false.

clone_set

If true, then every time you try to set a ref-data, a clone will performed, before assign it to the key. Default is true.

add_source( source, parameter => value, ... )

Loads the given source. This can either be a filepath, a hashref or a scalarref.

The following parameter are supportet:

discard

If you want to exclude some keys from loading from the given source, you can pass a arrayref with these keys or regexes.

    $config->add_source( $source, discard => [ 'key.to.remove', qr/^match/ ] );
discard_additional_keys

Discard all keys, which are not currently loaded by the configuration. Default is false for the first source you want to load and true for each subsequent one. Keys matched by discard will always be discarded.

merge_values

Takes a reference to a list of keys or regular expressions for merging. Keys matched by discard will always be discarded.

currently not implemented

get( key )

Returns the value for the given key.

Dies if the key is not found.

set( key => value )

Set the key to the given value.

Dies if the key not exists.

Before setting deep data structures a copy with clone is performed by default.

exists( key )

Return true, if the key exists. False otherwise.

keys( regex )

Returns all matching keys in sorted order, so you can easily iterate over it.

If Regex is omitted, all keys are returned.

reset( key, source )

Resets the given key to the value in the given configs.

Dies, if the key is not found either in the current config, or the source.

getall( parameter => value )

Returns a cloned copy from the configuration hash. This is a hashref.

You can restrict the given keys with the following parameters:

include

Arrayref with keys or regular expressions. Only the matched keys from the configuration will saved.

exclude

Arrayref with keys or regular expressions. All matched keys will excluded from saving. Keys matched by include and exclude will excluded.

save_file( file, paramter => value, ... )

Saves the configuration to the given file.

Dies if no file spezified.

You can restrict the saved keys with the same parameters specified in getall.

INTERNAL METHODS

_load_source

ACCESSORS

clone_get
clone_set

CLONING

You can change the cloning implementation with a package parameter:

    use Data::Clone;
    use Config::Source clone => \&Data::Clone::clone;

Or change it at any time with the class method import. The default implementation is Storables dclone.

OTHER FILE FORMATS

Most of the config modules out there can return a simple hash of the configuration. The following example shows how to read a default configuration and a user configuration with Config::General, as well as the saving of the configuration file back.

    use Config::General;
    use Config::Source;
    
    my %default = Config::General->new( 'default_location' )->getall;
    my %user    = Config::General->new( 'user_location' )   ->getall;
    
    my $config = Config::Source->new
                 ->add_source( \%default )
                 ->add_source( \%user );
    
    # ...
    
    my $hash = $config->getall;
    
    Config::General->new->save_file( 'user_location', $hash );

Be sure the passed values are unblessed hash references. And know the limitations of the other modules.

Maybe i add the option to direct load these file formats in a future release.

AUTHOR

Tarek Unger, <taunger at cpan.org>

BUGS

Please report any bugs or feature requests to bug-config-source at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-Source. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Config::Source

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2013-2014 Tarek Unger.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.