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

NAME

Config::Tree - Simple API for accessing configuration data

SYNOPSIS

    # Basic:

    use Config::Tree;

    my %new_config = (
        simple => 42,
        more => {
            complex => {
                data => 12,
            },
        },
    );
    CONFIG->append(\%new_config);
    CONFIG("simple");            # 42
    CONFIG("more.complex");      # { data => 12 }
    CONFIG("more.complex.data"); # 12

    # Classy:

    package MyApp::Config;
    use Config::Tree ':reexport';
    our %volatile = (...);
    our @stack    = (...);
    our %default  = (...);

    package main;
    use MyApp::Config;
    CONFIG("foo")                # Scan's MyApp::Config's stashes

BUGS

  • I'm not sure about the append/prepend api.

  • The hash scanner is a bit too magical.

  • Autovivified entries in %volatile are always hashes regardless of the contents of @stack or %default.

    (... not magical enough)

  • Uses global variables which restrict its usefulness in library code.

IMPORTANT NOTE

This module does not handle loading configuration data from a file (or other source) nor does it save data which have been set at runtime.

Methods to load and save will be included in a future release provided the API remains unchanged and this distribution's dependencies minimal.

DESCRIPTION

A common API with for interacting with configuration data. This module is centred around the "CONFIG" function, which is exported unconditionally (along with "SECRET", which uses it). The most common way to use CONFIG is to simply call it with the desired configuration key as an argument:

    CONFIG("foo.bar.baz");

If the key doesn't exist then an exception will be thrown (Value not found). To return a default value instead, pass the key as the first item in an arrayref where the second value is the desired default:

    CONFIG(["foo.bar.baz", "default-baz"]);

The default value can be undef.

Multiple values can be returned from a single call, with or without defaults. When used in this way CONFIG must be called in list context.

When CONFIG is called without arguments it returns the configuration singleton, whose methods are described below. Ordinarily this will be the global singleton but see "Object interface" for a explanation of how to customise that. CONFIG with arguments is actually a shortcut to calling CONFIG->get().

Configuration stack

Configuration values are stored in a stack of hashrefs which are searched in order. At the top of the stack is %volatile which contains values which have been set at runtime by "set". At the bottom is %default, the purpose of which I hope is obvious.

In between the volatile and default stashes are zero or more hashrefs, attached by "append" and "prepend".

Object interface

If Config::Tree is imported into a module with the :reexport option. Then that module becomes a subclass of Config::Tree and also re-exports "CONFIG" and "SECRET", modified as necessary to use the re-exporter's configuration stash.

By way of example, under normal circumstances CONFIG scans @Config::Tree::stack. T this can be adjusted by re-exporting Config::Tree's symbols:

    package Foo;
    use Config::Tree ':reexport';

Any module which imports Foo will obtain its configuration from @Foo::stack (and %Foo::volatile and %Foo::default) instead.

API

CONFIG

The heart of Config::Tree. When called without arguments returns the global configuration stash (for whose methods see below). When called with arguments returns the value or values requested.

More than one key can be requested, in which case the values are returned as a list in the same order. Note that CONFIG must be called in list context when used in this way.

Each key requested is a plain scalar consisting of hash or array elements seperated by dots (.). Each component of the key represents a level within the configuration stack. That is the key foo.bar.baz refers to the value at $stash{foo}{bar}{baz}.

Alternatively the key can be given as the first item of an arrayref, in which case the second item is the default value which will be returned if the key cannot be found.

SECRET

(Not written yet)

A wrapper around "CONFIG" which post-processes each value retrieved. The intention is that the value in the configuration will refer in some way to secret data, which this method will obtain and/or decode/decrypt.

METHODS

exists

Returns a boolean indicating whether the requested key exists in the configuration stash.

Takes exactly 1 key.

    CONFIG->exists("foo.bar");
exists

Returns a boolean indicating whether the requested key exists in the configuration stash and contains a value which perl considers true.

Takes exactly 1 key.

    CONFIG->true("foo.bar");
get

Return the value or values for the requested key(s). See "CONFIG" or the "DESCRIPTION" for more detail.

Generally you will want to use "CONFIG" directly.

    CONFIG->get("foo.bar");
    CONFIG->get("foo.bar", "foo.baz");
    CONFIG->get(["foo.bar", "default-bar"]);
set

Sets the value or values for the named key(s). The set values are stored in memory only.

Parent values which don't exist in the volatile stash are autovivified as hashrefs, despite what the key component is at that level or what exists in the rest of the stash.

    CONFIG->set("foo.bar" => "new-bar");
    CONFIG->set("foo.bar" => "new-bar",
                "foo.baz" => "new-baz");
append

Append the stash or stashes to the end of the configuration stack (but before the default values).

    CONFIG->append(\%new_config, ...);
prepend

Prepend the stash or stashes to the beginning of the configuration stack (but after the in-memory values).

    CONFIG->prepend(\%new_config, ...);
replace

Replace the contents of the entire configuration stack with the stash(es) supplied.

This does not affect the default or in-memory values.

    CONFIG->replace(\%new_config, ...);
default

Return the default stash.

stack

Return (as a list) the inner stashes.

volatile

Return the in-memory stash.

stash

(Not written yet)

Return the entire configuration stash, normalised, as a hashref.

WHY?

It seems like everyone on the CPAN wants their own config-loading module. Why another one?

Well this one is mine, see?

SEE ALSO

https://metacpan.org/search?q=Config%3A%3A

AUTHOR

Matthew King <chohag@jtan.com>