Configuration Options

    package Your::Module;
    use base 'Badger::Base';
    use Badger::Class::Config 'foo', 'bar';

For convenience, multiple items can be specified in a single whitespace delimited string.

    use Badger::Class::Config 'foo bar';

More complex configurations can be specified using list and hash references, but we'll keep things simple for now.

Using the module as shown here has two immediate effects. The first is that the $CONFIG_SCHEMA package variable will be defined in "Your::Module" containing a reference to the configuration schema for your module. This schema contains information about the configuration items which in this example are "foo" and "bar". The second effect is to define a configure() method which uses this schema to configure your object using the configuration options passed to the constructor method. You can call this method from your init() method (if you're using Badger::Base) or from your own construction or initialisation methods.

    sub init {
        my ($self, $config) = @_;
        $self->configure($config);
        return $self;
    }

The configure() method is intentionally simple, although flexible. It doesn't attempt to assert that any configuration items are of the correct type or validate the values in any way. If the relevant values are defined in the $config hash then they will be copied into $self. Otherwise they are ignored.

If a configuration item is mandatory then add a "!" at the end of the name. If no value is defined for this item then the configure() method will throw an exception.

    use Badger::Class::Config 'foo! bar!';      # mandatory items

A default value can be provided using "=";

    use Badger::Class::Config 'foo=10 bar=20';  # default values

Aliases for the configuration item can be provided using "|"

    use Badger::Class::Config 'foo|Foo|FOO';    # aliases for 'foo'

As well as looking for items in the $config hash array, you can search for package variables (in the current package), class variables (in the current package or those of all base class), environment variables, and call object methods.

    use Badger::Class::Config
        'foo|pkg:FOO',                  # fallback to $FOO package var
        'bar|class:BAR',                # fallback to $BAR class var
        'baz|env:BAZ',                  # fallback to $BAZ environment var
        'bam|method:BAM';               # fallback to BAM() method
        'wam|target:slam';              # fallback to $target->{ slam }

Bear in mind that Perl implements constants using subroutines. Thus, you can access a constant defined in a package/class by calling it as a method. So if you have a constant defined in the module that you want to use then specify it using the "method:" prefix.

TODO: more on that

Detailed Specification

    use Badger::Class::Config
        {
            foo => {
                required => 1,
                default  => 10,
                fallback => ['class:FOO', 'env:FOO'],
            },
            bar => {
                required => 1,
                default  => 20,
                fallback => ['class:BAR', 'env:BAR'],
            },

        };

You can mix and match simple and detailed specifications by specifying them as items in a list reference. Each configuration option should be defined as a separate item (i.e. you can't merge multiple items into a single whitespace delimited string). Simple definitions are specified using strings, complex definitions using hash reference. Note that the name of the option must be specified explicitly in the hash array when used this way.

    use Badger::Class::Config
        [
            'foo|class:FOO!',
            {
                name     => 'bar',
                required => 1,
                default  => 20,
                fallback => ['class:BAR', 'env:BAR'],
            },

        ];

Badger::Class Hook

    use Badger::Class
        base   => 'Badger::Base',
        config => 'foo! bar=10 baz|class:BAZ=20';

Or a reference to a hash array or list containing individually defined configuration items.

    use Badger::Class
        base   => 'Badger::Base',
        config => [
            'foo!',
            'bar=10',
            'baz|class:BAZ=20'
        ];

schema()

configure($config,$target)

The first argument should be a reference to a hash array of configuration options. The second should be a reference to a hash array or hash-based object into which the configuration values can be copied. If this is not specified then the method defaults to updating the $self object reference passed as the first implicit argument.

    sub init {
        my ($self, $config) = @_;
        $self->configure($config);
        return $self;
    }

configure_pkg()

configure_class()

configure_env()

configure_method()

configure_target()

fallback()