NAME

Rose::Conf - Configuration module base class.

SYNOPSIS

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

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

our %CONF =
(
  COLOR => 'blue',
  SIZE  => 'big',
  ...
);

...

# File: My/System.pm

# Import conf hash under name of your choice
use My::System::Conf qw(%SYS_CONF);
...
$color = $SYS_CONF{'COLOR'}; # get
$SYS_CONF{'COLOR'} = 'red';  # set

or

# File: My/System.pm
use My::System::Conf; # Don't import any symbols
...
$color = My::System::Conf->param('COLOR'); # get
My::System::Conf->param(COLOR => 'red');   # set

or

# File: My/System.pm
use My::System::Conf; # Don't import any symbols
...
$conf  = My::System::Conf->conf_hash;
$color = $conf->{'COLOR'}; # get
$conf->{'COLOR'} = 'red';  # set

DESCRIPTION

Traditionally, module configuration information is stored in package globals or lexicals, possibly with class methods as accessors. This system works, but it also means that looking up configuration information requires loading the entire module.

Rose::Conf is a base class that promotes the collect all configuration information for a module into a separate, lighter-weight module. Configuration information may be imported as a hash into other packages under any desired name, accessed via a param() class method, or through a reference to the configuration hash returned by the conf_hash() class method.

This strategy will make even more sense once you read about Rose::Conf::FileBased and the (currently unreleased) build and configuration system that leverages it.

Configuration modules should inherit from Rose::Conf and define a package global %CONF hash. Example:

package Site::Conf;

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

our %CONF =
(
  NAME => 'MySite',
  HOST => 'mysite.com',
  IP   => '123.123.123.123',
  ...
);

Modules or scripts that want to import this configuration have three choices: importing a hash, using the param() class method, or using the conf_hash() class method.

IMPORTING A HASH

To import the configuration hash, use the configuration module and provide the name of the hash that will be used to access it. Examples:

# Alias %SITE_CONF to %Site::Conf::CONF
use Site::Conf qw(%SITE_CONF);

# Alias %REMOTE_CONF to %Remote::Conf::CONF
use Remote::Conf qw(%REMOTE_CONF);

$site_name = $SITE_CONF{'NAME'}; # get
$REMOTE_CONF{'NAME'} = 'Remote'; # set

USING THE param() CLASS METHOD

To use the param() class method, use the configuration module without any arguments, then call param() with one argument to get a value, and two arguments to set a value. Example:

use Site::Conf;
...
$name = Site::Conf->param('NAME');      # get
Site::Conf->param(NAME => 'MyNewSite'); # set

USING THE conf_hash() CLASS METHOD

To use the conf_hash() class method, use the configuration module without any arguments, then call conf_hash() to retrieve a reference to the configuration hash. Example:

use Site::Conf;
...
$conf = Site::Conf->conf_hash;

$name = $conf->{'NAME'};       # get
$conf->{'NAME'} = 'MyNewSite'; # set

WHICH METHOD SHOULD I USE?

Each methods has its advantages. The biggest advantage of using param() is that it will croak if you try to access a nonexistent configuration parameter (see class method documentation below). Directly accessing the configuration hash by importing it, or through the hash reference returned by conf_hash, is faster than calling the param() method, but offers no safeguards for nonexistent configuration parameters (it will autovivify them just like a regular hash).

CONVENTIONS

The convention for naming a configuration class is to take the name of the module being configured and add "::Conf" to the end. So the configuration module for My::Class would be My::Class::Conf.

By convention, configuration parameter names should use uppercase letters. (e.g., "COLOR" or "SIZE", not "color" or "Size")

CLASS METHODS

conf_hash

Returns a reference to the configuration hash.

param NAME [, VALUE]

When passed a single NAME argument, returns the value of that configuration parameter, or croaks if the parameter does not exist.

If an optional VALUE argument is passed, the configuration parameter specified by NAME is set to VALUE. The parameter is created if it does not already exist. The new value is returned.

param_exists NAME

Returns true if a configuration parameter named NAME exists, false otherwise.

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