The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Rose-Conf-0.021
River stage zero No dependents
++
/ Rose::Conf::FileBased

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',
      KEY3 =>
      {
        foo => 5,
        bar => 6,
      }
      ...
    );
    ...


    # 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"
    KEY3:foo = 55
    KEY3:bar = 66
    ...


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


    # 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"
    print $SYS_CONF{'KEY3'}{'foo'}; # prints "55"
    print $SYS_CONF{'KEY3'}{'bar'}; # prints "10"

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 the environment variable directly using the %ENV hash 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 optionally be enclosed in single or double quotes. Only simple scalar values are supported at this time, and the values must be on one line.

If a value is in double quotes and contains a backslash character ("\"), then it is eval()ed as a string. Example:

    # This value will contain an actual newline
    KEY1 = "one\ntwo"

    # These will both contain a literal backslash and an "n"
    KEY2 = 'one\ntwo'
    KEY2 = one\ntwo

Blank lines, lines that begin with the comment character "#", and leading and trailing spaces are ignored.

If a parameter name contains a ":" character, it must be escaped with a backslash:

    CLASS My::Conf

    # $My::Conf::CONF{'FOO:BAR'} = 5
    FOO\:BAR = 5

Backslash characters in parameter names must be escaped as well:

    CLASS My::Conf

    # $My::Conf::CONF{'A\B'} = 10
    A\\B = 10

Any other character in a parameter name also may be safely escaped with a backslash:

    CLASS My::Conf

    # $My::Conf::CONF{'hello'} = 20
    h\e\l\lo = 20

Unescaped ":" characters are used to address nested hashes:

    CLASS My::Conf

    # $My::Conf::CONF{'KEY'}{'subkey'} = 123
    KEY:subkey = 123

Keys can be nested to an arbitrary depth using a series of ":" characters:

    # $My::Conf::CONF{'A'}{'b'}{'c'}{'d'}{'e'} = 456
    A:b:c:d:e = 456

In order to avoid conflicting with any future "special" characters like ":", key names should contain only letters, numbers, and underscores. Any other characters may take on special meaning in future versions of this module and may therefore need to be backslash-escaped in configuration files like "local.conf".

"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 identical to that of the "local.conf" file (described above) except that the CLASS declaration is invalid.

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" simple scalar 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. The keys are returned as they would appear in a configuration file. That means they are escaped as necessary, and nested hash keys use the ":"-separated syntax. See the "CONFIGURATION FILES" section for more information.

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.

The KEY argument must be provided in the same syntax as it would appear in a configuration file. That means that literal ":" characters must be escaped, and nested hash values must be addressed using the ":"-separated syntax. See the "CONFIGURATION FILES" section for more information.

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.