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

       Copyright (C) 2001-2009 Andy Wardley.  All Rights Reserved.

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