IO.Config

IO.Config: Static, per-Module, per-Application Key-Values

Module API

• IO.Config provides (key, value) tuples to modules on demand.

• Modules call Config->register with a definition of keys and defaults. When values are supplied via a BConf.pm, .pm, command line, or Config->introduce_values, the Module's handle_config is given a copy of all its values with defaults filled in. It's up to the module to validate and copy the values, and store them in a global variable for later use.

• An excerpt from PetShop.BConf:

Bivio::Biz::Model::UserCreateForm' => {
    unapproved_applicant_mode => 1,
},
'Bivio::Biz::Model::MailReceiveDispatchForm' => {
    filter_spam => 1,
},
'Bivio::Ext::DBI' => {
    database => 'pet',
    user => 'petuser',
    password => 'petpass',
    connection => 'Bivio::SQL::Connection::Postgres',
},

• Package names are the outermost key, and point to hash_refs containing values for that module.

• IO.Config is the second module to be initialized after Bivio.UNIVERSAL (the base class of all BOP modules)

• Excerpt from MailReceiveDispatchForm:

my($_C) = b_use('IO.Config');
$_C->register(my $_CFG = {
    ignore_dashes_in_recipient => $_C->if_version(5),
    filter_spam => 0,
    duplicate_threshold_seconds => 3600,
});

• if_version is an interface for serializing non-backwards compatible features.

• Excerpt from Delegate.Cookie:

sub handle_config {
    my(undef, $cfg) = @_;
    b_die($cfg->{domain}, ': domain must begin with dot (.)')
        if defined($cfg->{domain}) && $cfg->{domain} !~ /^^\./;
    $cfg->{session_update_seconds} = int($cfg->{session_timeout_seconds}/20)
        if $cfg->{session_timeout_seconds}
        && !defined($cfg->{session_update_seconds});
    $_CFG = {%{$cfg}, tag => uc($cfg->{tag})};
    return;
}

Config files

• Every application has a BConf, e.g. Bivio::PetShop::BConf to set reasonable production, test, and development defaults.

• Bivio::BConf provides a set of reasonable development defaults, and a convenience routine for the .bconf files, which is the starting point for configuration values.

• A sample pet.bconf:

use strict;
use Bivio::PetShop::BConf;
Bivio::PetShop::BConf->dev(8000, {
    'Bivio::Ext::DBI' => {
        database => 'petrjn',
    },
    'Bivio::UI::Facade' => {
        local_file_root => '/home/nagler/src/perl/Bivio/PetShop/files',
    },
    'Bivio::UI::HTML::Widget::SourceCode' => {
        source_dir => '/home/nagler/src/perl/',
    },
});

• The BConf->dev routine returns a hash_ref which is returned to IO.Config by a "do".

• IO.Config will look for a sub-directory named "bconf.d" in the directory in which the .bconf resides. All the readable files in the bconf.d are read, and the values are merged along with the original .bconf file in alphabetic priority order, that is, files that begin with "a" override values in files that begin with "z".

• BConf.pm's base class values override Bivio::BConf's values, which in turn override the defaults supplied by the module itself.

• Values on the command line override all values:

--Bivio::EXxt::DBI.database=pet

• /etc/bivio.bconf is the default configuration. Normally, the the value of $BCONF environment variable contains the file to be used.

• A variety of methods available to support merging configuration: merge_class_loader, merge, default_merge_overrides, dev_overrides, merge_dir, merge_http_log, and merge_realm_role_category_map.