NAME
    Config::Environment - Application Configuration via Environment
    Variables

VERSION
    version 0.000005

SYNOPSIS
        use Config::Environment;

        my $conf = Config::Environment->new('myapp');
        my $conn = $conf->param('db.1.conn' => 'dbi:mysql:dbname=foobar');
        my $user = $conf->param('db.1.user'); # via $ENV{MYAPP_DB_1_USER} or undef
        my $pass = $conf->param('db.1.pass'); # via $ENV{MYAPP_DB_1_PASS} or undef

        or

        my $info = $conf->param('db.1');
        say $info->{conn}; # outputs dbi:mysql:dbname=foobar
        say $info->{user}; # outputs the value of $ENV{MYAPP_DB_1_USER}
        say $info->{pass}; # outputs the value of $ENV{MYAPP_DB_1_PASS}

        likewise ...

        $conf->param('server' => {node => ['10.10.10.02', '10.10.10.03']});

        creates the following environment variables and assignments

        $ENV{MYAPP_SERVER_NODE_1} = '10.10.10.02';
        $ENV{MYAPP_SERVER_NODE_2} = '10.10.10.03';

        ... and the configuration can be retrieved using any of the following

        $conf->param('server');
        $conf->param('server.node');
        $conf->param('server.node.1');
        $conf->param('server.node.2');

        or

        my ($node1, $node2) = $conf->params(qw(server.node.1 server.node.2));

DESCRIPTION
    Config::Environment is an interface for managing application
    configuration using environment variables as a backend. Using
    environment variables as a means of application configuration is a great
    way of controlling which parts of your application configuration gets
    hard-coded and shipped with your codebase (and which parts do not).
    Using environment variables, application configuration can be set at the
    system, user, and/or application levels and easily overridden.

ATTRIBUTES
  autoload
    The autoload attribute contains a boolean value which determines whether
    the global ENV hash will be sourced during instantiation. This attribute
    is set to true by default.

  domain
    The domain attribute contains the environment variable prefix used as
    context to differentiate between other environment variables.

  lifecycle
    The lifecycle attribute contains a boolean value which if true restricts
    any environment variables changes to life of the class instance. This
    attribute is set to false by default.

  mirror
    The mirror attribute contains a boolean value which if true copies any
    configuration assignments to the corresponding environment variables.
    This attribute is set to true by default.

  override
    The override attribute contains a boolean value which determines whether
    parameters corresponding to an existing environment variable can have
    it's value overridden. This attribute is set to true by default.

METHODS
  load
    The load method expects a hashref which it parses and generates
    environment variables from whether they exist or not and registers the
    formatted environment structure. This method is called automatically on
    instantiation using the global ENV hash as an argument.

        my $hash = {
            APP_MODE => 'development',
            APP_USER => 'vagrant',
            APP_PORT => 9000
        };

        $self->load($hash);

  param
    The param method expects a key which it uses to locate the corresponding
    environment variable in the registered data structure. The key uses
    dot-notation to traverse hierarchical data in the registry. This method
    will return undefined if no element can be found matching the query. The
    method can also be used to set environment variables by passing an
    additional argument as the value in the form of a scalar, arrayref or
    hashref.

        my $item = $self->param($key);
        my $item = $self->param($key => $value);

        # load parsed data from another configuration source, e.g. a config file
        while (my($key, $val) = each(%$configuration) {
            $self->param($key => $val);
        }

  params
    The params method expects a list of keys which are used to locate the
    corresponding environment variables in the registered data structure.
    The keys use dot-notation to traverse hierarchical data in the registry
    and return a list of corresponding values in order specified. This
    method returns a list in list-context, otherwise it returns the first
    element found of the list of queries specified.

        my $item  = $self->params(@list_of_keys);
        my @items = $self->params(@list_of_keys);

  environment
    The environment method returns a hashref representing all environment
    variables specific to the instantiated object's domain and instance.

        my $environment = $self->environment;

  subdomain
    The subdomain method returns a copy of the class instance with a
    modified domain reference for easier access to nested configuration
    keys.

        my $db  = $self->subdomain('db');
        my $db1 = $db->subdomain('1');

        $db1->param('conn' => $connstring);
        $db1->param('user' => $username);
        $db1->param('pass' => $password);

AUTHOR
    Al Newkirk <anewkirk@ana.io>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Al Newkirk.

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

