/ 
Rose-Conf-0.021
River stage zero No dependents
++
 / Rose::Conf

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',
      PORTS =>
      {
        ssh => 22,
        ftp => 21,
      },
      ...
    );

    ...

    # 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
    $port = $SYS_CONF{'PORTS'}{'ssh'}; # get nested
    $SYS_CONF{'PORTS'}{'ssh'} = 2200;  # set nested

    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
    # get/set nested values
    $port = My::System::Conf->param('PORTS')->param{'ssh'};
    My::System::Conf->param('PORTS')->param{'ssh' => 2200};

    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
    $port = $conf->{'PORTS'}{'ssh'}; # get nested
    $conf->{'PORTS'}{'ssh'} = 2200;  # set nested

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',
      PORTS =>
      {
        main => 80,
        ssl  => 443,
      },
      ...
    );

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
    $port = $SITE_CONF{'PORTS'}{'main'}; # get nested
    $SITE_CONF{'PORTS'}{'main'} = 8000;  # set nested

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

Calls to the param() method can be chained in order to access configuration values in nested hashes. Example:

    # get/set nested values
    $port = Site::Conf->param('PORTS')->param('ssh');
    Site::Conf->param('PORTS')->param('ssh' => 2200);

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
    $port = $conf->{'PORTS'}{'ssl'}; # get nested
    $conf->{'PORTS'}{'ssl'} = 4430;  # set nested

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, top-level 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.

Calls to param() can be chained in order to access configuration values in nested hashes. Example:

    # get/set nested values
    $port = Site::Conf->param('PORTS')->param('ssh');
    Site::Conf->param('PORTS')->param('ssh' => 2200);

If VALUE is a reference to a hash, it is blessed into an undocumented class that you should not be concerned with. It is safe to simply treat the now-blessed reference as a regular hash reference, just be aware that calling ref() on it will not return "HASH".

param_exists NAME

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

Calls to param_exists() can be placed at the end of a chain of calls to param() in order to check for the existence of configuration values in nested hashes. Example:

    Site::Conf->param('PORTS')->param_exists('ssh');

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.