Simple API to use configuration data, independent of its source.
Config::Any and Config::Simple were already taken.
Config::Tree is a simple module which exports (unconditionally) two
functions, CONFIG and SECRET. SECRET is simply a wrapper around CONFIG
which will (when it's written) decode the value obtained in some
fashion.
Config::Tree can be used as a standalone module accessing a global
configuration or subclassed to access application-specific
configuration.
Actual configuration data is stored in 3 global variables in either
Config::Tree's namespace or that of the module which subclasses
it. They are:
%volatile - Updated values in memory only.
@stack - Zero or more loaded or tied hashes.
%default - Default values.
In the general case, an application would use Config::Tree as follows:
#!/usr/bin/perl
use Config::Tree;
%Config::Tree::default = ( ... );
# Loading configuration:
my $encoded = read_text("/path/to/config.json");
CONFIG->append(decode_json($encoded));
# Accessing values:
my $foo = CONFIG("foo");
my $true = CONFIG->true("bar.baz");
my $bingable = CONFIG->exists("bar.bing");
Any modules this application uses which also use Config::Tree will
look for their configuration values in the same place.
Library modules which need their own configuration will use
Config::Tree as follows:
package My::Library::Config;
use Config::Tree ':reexport'; # Almost the same as use base 'Config::Tree';
our %default = (
default => "values",
);
package My::Library::Module;
use My::Library::Config;
my $anything = CONFIG("whatever");
Any code which imports My::Library::Config will use the same API
exported by Config::Tree to access the %volatile, @stack and %default
in My::Library::Config.
Config::Tree subclasses may wish to override _find to modify how the
variables are scanned and how the key is decoded.
A library should normally provide any default values which are
necessary and leave loading & saving to the application using it.
Configuration data is loaded into a hashref, referred to as a stash,
and inserted into a stack of stashes which are searched
sequentially. An individual stash can also be a listref but that's
weird.
There are always 2 stashes hard-coded at the top (%volatile) and
bottom (%default) of the stack. Configuration data is loaded and
inserted at the top or bottom of the stack but between %volatile and
%default (ie. @stack). The contents of these variables can be obtained
with CONFIG->volatile, CONFIG->default and CONFIG->stack;
@stack is manipulated with the methods append, prepend and replace,
all of which expect 1 or more stashes as arguments to be pushed or
unshifted, or to replace entirely the current @stack.
Actually loading and parsing a file (or saving one) is not performed
by Config::Tree. Data must be pre-processed before passing it to
append/prepend/replace and serialised before saving it. A future
version of Config::Tree will include load and save functionality,
using other modules to perform the actual I/O and not depending on any
specific one of them.
