/ 
Config-Locale-0.02
River stage zero No dependents
/ Config::Locale

NAME

Config::Locale - Load and merge locale-specific configuration files.

SYNOPSIS

use Config::Locale;

my $locale = Config::Locale->new(
    identity => \@values,
    directory => $config_dir,
);

my $config = $locale->config();

DESCRIPTION

This module takes an identity array, determines the permutations of the identity using Algorithm::Loops, loads configuration files using Config::Any, and finally combines the configurations using Hash::Merge.

So, given this setup:

Config::Locale->new(
    identity => ['db', '1', 'qa'],
);

The following configuration files will be looked for (listed from least specific to most):

default
all.all.qa
all.1.all
all.1.qa
db.all.all
db.all.qa
db.1.all
db.1.qa

For each file found the contents will be parsed and then merged together to produce the final configuration hash. The hashes will be merged so that the most specific configuration file will take precedence over the least specific files. So, in the example above, "db.1.qa" values will overwrite values from "default".

ARGUMENTS

identity

The identity that configuration files will be loaded for. In a typical hostname-basedc configuration setup this will be the be the parts of the hostname that declare the class, number, and cluster that the current host identifies itself as. But, this could be any list of values.

directory

The directory to load configuration files from. Defaults to the current directory.

wildcard

The wildcard string to use when constructing the configuration filenames. Defaults to "all". This may be explicitly set to undef wich will cause the wildcard string to not be added to the filenames at all.

Note that this argument is completely ignored if you are using the PERMUTE algorithm.

default

The name of the configuration file that contains the default configuration. Defaults to "default". This may be explcitly set to undef which will cause the default configuration file to look just like all the other configuration files, just using the "wildcard" for all of the identity values.

separator

The character that will be used to separate the identity keys in the configuration filenames. Defaults to ".".

prefix

An optional prefix that will be prepended to the configuration filenames.

suffix

An optional suffix that will be apended to the configuration filenames. While it may seem like the right place, you probably should not be using this to specify the extension of your configuration files. Config::Any automatically tries many various forms of extensions without the need to explicitly declare the extension that you are using.

algorithm

Which algorithm used to determine, based on the identity, what configuration files to consider for inclusion.

The default, NESTED, keeps the order of the identity. This is most useful for identities that are derived from the name of a resource as resource names (such as hostnames of machines) typically have a defined structure.

The PERMUTE algorithm will shift the identity values around in all possible permutations. This is most useful when the identity contains attributes of a resource.

merge_behavior

Specify a Hash::Merge merge behavior. The default is LEFT_PRECEDENT.

ATTRIBUTES

config

Contains the final configuration hash as merged from the hashes in "configs".

configs

Contains an array of hashrefs, one hashref for each file in "stems" that exists.

stems

Contains an array of Path::Class::File objects for each value in "combinations".

combinations

Holds an array of arrays containing all possible permutations of the identity, per the specified "algorithm".

AUTHOR

Aran Clary Deltac <bluefeet@gmail.com>

LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.