John Siracusa > Rose-Conf > Rose::Conf::FileBased

Download:
Rose-Conf-0.021.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.02   Source  

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.

syntax highlighting: