NAME

Rose::Conf::FileBased - File-based configuration module base class.

SYNOPSIS

# File: My/System/Conf.pm
package My::System::Conf;

use Rose::Conf::FileBased;

our @ISA = qw(Rose::Conf::FileBased);

our %CONF = 
(
  KEY1 => 'value1',
  KEY2 => 'value2',
  ...
);
...


# File: My/System.pm
use My::System::Conf qw(%SYS_CONF); # import hash
...


# File: My/System/Foo.pm
use My::System::Conf; # do not import hash
...


# File: $ENV{'ROSE_CONF_FILE_ROOT'}/local.conf
CLASS My::System::Conf
KEY1 = "new value"
KEY2 = "new two"
...


# File: $ENV{'ROSE_CONF_FILE_ROOT'}/My::System::Conf.conf
KEY1 = "the final value"
...


# File: somefile.pl
use My::System::Conf qw(%SYS_CONF);

print $SYS_CONF{'KEY1'}; # prints "the final value"
print $SYS_CONF{'KEY2'}; # prints "new two"

DESCRIPTION

Rose::Conf::FileBased inherits from Rose::Conf and provides the same functionality, with the additional ability to read and incorporate text configuration files which override the values hard-coded into the configuration module.

Text configuration files must be located in the file-based configuration file root ("conf root") directory. This directory is set as follows:

If the environment variable ROSE_CONF_FILE_ROOT exists, it is used to set the conf root. The Rose::Conf::Root module is the recommended way to set this environment variable from within Perl code. Setting thee environment variable directly from within Perl code may become unsupported at some point in the future.

If ROSE_CONF_FILE_ROOT is not set and if running in a mod_perl 1.x environment, the conf root is set to the "conf/perl" directory relative to the web server's "server root" directory. That is:

Apache->server_root_relative('conf/perl')

If no conf root is defined, Rose::Conf::FileBased behaves like Rose::Conf, except that trying to access a nonexistent parameter name through a hash alias or reference to the conf hash results in a fatal error.

CONFIGURATION FILES

There are two types of configuration files: "combined" and "class-specific." As described above, all configuration files must be stored in the "conf root" directory. In cases of conflict, entries in a "class-specific" configuration file override entries in a "combined" configuration file.

THE "COMBINED" CONFIGURATION FILE

The "combined" configuration file must be named "local.conf". This file name is case sensitive. The format of the "local.conf" file is as follows:

CLASS Some::Package::Conf
KEY1 = "value1"
KEY2 = 'value2'
KEY3 = 5

# This is a comment

CLASS Some::Other::Package::Conf
KEY1 = "value1"
KEY2 = 'value2'
KEY3 = 5

The CLASS directive sets the context for all the key/value pairs that follow it. The KEYs are keys in CLASS's %CONF hash.

Values may or may not be enclosed in quotes. Only simple scalar values are supported at this time, and the values must be on one line. Blank lines, lines that begin with the comment character "#", and leading and trailing spaces are ignored.

"CLASS-SPECIFIC" CONFIGURATION FILES

"Class-specific" configurations file must have a name equal to the concatenation of the configuration package name and ".conf". For example, the class-specific configuration file for the My::Class::Conf package would be "My::Class::Conf.conf". This file name is case sensitive.

If your operating system or volume format does not allow ":" characters in file names, you can use "-" instead: "My-Class-Conf.conf"

The format of each class-specific configuration file is as follows:

# This is a comment

KEY1 = "value1"
KEY2 = 'value2'
KEY3 = 5

The KEYs are keys into the class's %CONF hash. Values may or may not be enclosed in quotes. Only simple scalar values are supported at this time, and the values must be on one line. Blank lines, lines that begin with the comment character "#", and leading and trailing spaces are ignored.

COMPLEX VALUES

Lists, hashes, and other values that are not simple scalars may be supported in the future. For now, if you need to include such values, it's a simple matter to add code to "inflate" the values as necessary. Example:

# File: local.conf
CLASS My::Conf

# Scalar value will be expanded into an array ref later
NAMES = 'Tom,Dick,Harry'
...


# File: My/Conf.pm
package My::Conf;

use Rose::Conf::FileBased;
our @ISA = qw(Rose::Conf::FileBased);

our %CONF =
(
  COLOR => 'blue',
  NAMES => [ 'Sue', 'Joe', 'Pam' ],
);

# Override refresh method and auto-expand non-scalar values
# according to whatever format or convention we choose
sub refresh
{
  shift->SUPER::refresh(@_);

  # Expects a string of comma-separated values,
  # then expands it into an array reference
  $CONF{'NAMES'} = [ split(',', $CONF{'NAMES'}) ]
    unless(ref $CONF{'NAMES'});
}
...


# Some other code somewhere...
use My::Conf;

$names = My::Conf->param('NAMES');
print join(' ', @$names); # 'Tom Dick Harry'

CLASS METHODS

Unless overridden below, all of Rose::Conf's class methods are inherited by Rose::Conf::FileBased.

local_conf_keys

Returns an unsorted list of configuration keys whose values have been set or overridden by one or more configuration files.

local_conf_value KEY

Returns the value of the configuration setting KEY if and only if KEY's value has been set or overridden by a configuration file. Returns false otherwise.

refresh

Refreshes the configuration values in the class by re-reading any configuration files.

AUTHOR

John C. Siracusa (siracusa@mindspring.com)

COPYRIGHT

Copyright (c) 2004 by John C. Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Rose::Conf

perl -MCPAN -e shell
install Rose::Conf