NAME

Badger::Config - configuration module

SYNOPSIS

    use Badger::Config;

    my $config = Badger::Config->new(
        user => {
            name => {
                given  => 'Arthur',
                family => 'Dent',
            },
            email => [
                'arthur@dent.org',
                'dent@heart-of-gold.com',
            ],
        },
        planet => {
            name        => 'Earth',
            description => 'Mostly Harmless',
        },
    );

    # fetch top-level data item - these both do the same thing
    my $user = $config->user;                       # shortcut method
    my $user = $config->get('user');                # generic get() method

    # fetch nested data item - these all do the same thing
    print $config->get('user', 'name', 'given');    # Arthur
    print $config->get('user.name.family');         # Dent
    print $config->get('user/email/0');             # arthur@dent.org
    print $config->get('user email 1');             # dent@heart-of-gold.com

DESCRIPTION

This is a quick hack to implement a placeholder for the Badger::Config module. A config object is currently little more than a blessed hash with an AUTOLOAD method which allows you to get/set items via methods.

Update: this has been improved a little since the above was written. It's still incomplete, but it's being worked on.

METHODS

new()

Constructor method to create a new Badger::Config object. Configuration data can be specified as the "data" named parameter:

    my $config = Badger::Config->new(
        data => {
            name  => 'Arthur Dent',
            email => 'arthur@dent.org',
        },
    );

The "items" parameter can be used to specify the names of other valid configuration values that this object supports.

    my $config = Badger::Config->new(
        data => {
            name  => 'Arthur Dent',
            email => 'arthur@dent.org',
        },
        items => 'planet friends',
    );

Any data items defined in either "data" or "items" can be accessed via methods.

    print $config->name;                # Arthur Dent
    print $config->email;               # arthur@dent.org
    print $config->planet || 'Earth';   # Earth

As a shortcut you can also specify configuration data direct to the method.

    my $config = Badger::Config->new(
        name  => 'Arthur Dent',
        email => 'arthur@dent.org',
    );

You should avoid this usage if there is any possibility that your configuration data might contain the "data" or "items" items.

get($name)

Method to retrieve a value from the configuration.

    my $name = $config->get('name');

This can also be used to fetch nested data. You can specify each element as a separate argument, or as a string delimited with any non-word characters. For example, given the following configuration data:

    my $config = Badger::Config->new(
        user => {
            name => {
                given  => 'Arthur',
                family => 'Dent',
            },
            email => [
                'arthur@dent.org',
                'dent@heart-of-gold.com',
            ],
        },
    );

You can then access data items using any of the following syntax:

    print $config->get('user', 'name', 'given');    # Arthur
    print $config->get('user.name.family');         # Dent
    print $config->get('user/email/0');             # arthur@dent.org
    print $config->get('user email 1');             # dent@heart-of-gold.com

In addition to accessing list and hash array items, the "get()" will call subroutine references and object methods, as shown in this somewhat contrived example:

    # a trivial object class
    package Example;
    use base 'Badger::Base';

    sub wibble {
        return 'wobble';
    }

    package main;

    # a config with a function that returns a hash containing an object
    my $config = Badger::Config->new(
        function => sub {
            return {
                object => Example->new(),
            }
        }
    );
    print $config->get('function.object.wibble');   # wobble

set($name,$value)

Method to store a value in the configuration.

    $config->set( friend  => 'Ford Prefect' );
    $config->set( friends => ['Ford Prefect','Trillian','Marvin'] );

At present this does not allow you to set nested data items in the way that the get() method does.

INTERNAL METHODS

can_configure($name)

Internal method used to generate accessor methods on demand. This is installed using the auto_can hook in Badger::Class.

AUTHOR

Andy Wardley <http://wardley.org/>

COPYRIGHT

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