NAME

OpenInteract::Config -- centralized configuration information

SYNOPSIS

 use OpenInteract::Config;

 my $config = OpenInteract::Config::PerlFile->new();
 $config->read_file( '/path/to/dbi-config.info' );
 $config->{debugging} = 1;

 my $dbh = DBI->connect( $config->{db_dsn},
                         $config->{db_username},
                         $config->{db_password}
                         { RaiseError => 1 } );

 if ( my $debug = $config->{DEBUG} ) {
     print $LOG "Trace level $debug: fetching user $user_id...";
     if ( my $user = $self->fetch( $user_id ) ) {
         print $LOG "successful fetching $user_id\n";
     }
     else {
         print $LOG "No such user with ID $user_id";
     }
 }

DESCRIPTION

Allows you to embed a configuration object that responds to get/set requests. Different from just using key/value pairs within your object since you do not have to worry about writing get/set methods, cluttering up your AUTOLOAD routine, or things like that. It also allows us to create configuration objects per module, or even per module instance, as well as create one for the entire program/project by putting it in the always-accessible Request object.

Very simple interface and idea: information held in key/value pairs. You can either retrieve the information using the get() method or by referring to the config object like a hashref. For instance, to retrieve the information related to DBI, you could do:

 my ( $dsn, $uid, $pass ) = ( $config->{db_dsn},
                              $config->{db_username},
                              $config->{db_password} );

or you could do:

 my ( $dsn, $uid, $pass ) = $config->get( 'db_dsn', 'db_username', 'db_password' );

Setting values is similarly done:

 my $font_face = $config->{font_face} = 'Arial, Helvetica';

or:

 my $font_face = $config->set( font_face => 'Arial, Helvetica' );

Note that you might want to use the get/set method calls more frequently for the sake of clarity. Or not. TMTOWTDI.

METHODS

A description of each method follows:

instance( $type, @params )

Unknown. Depends on what is being configured.

Create the Config object. Just bless an anonymous hash and stick every name/value pair passed into the method into the hash.

Note: we should probably lower case all arguments passed in, but getting/setting parameters and values should only be done via the interface. So, in theory, we should not allow the user to set anything here...

Parameters:

• type ($)

  Type of configuration file to create. Currently the only supported type is 'perl', which keeps the configuration information in a perl data structure.

Returns: Configuration object.

flatten_action_config()

Copies information from the default action into all the other action (except the default action and those beginning with '_', which are presumably private.)

Returns: an arrayref of action keys (tags) for which information was set.

param_set( $key, [ $value ] )

The first parameter is the config key, the optional second parameter is the value we would like to set the key to. Simply set the value if it is passed in, then return whatever the value is.

Possible modifications: allow the use of a third parameter, 'force', that enables you to blank out a value. Currently this is not possible.

get( @keys )

Return a list of values for each $key passed in. If only one key is passed in, we return a single value, not a list consisting of a single value.

Possible modifications: use wantarray to see if we should return a list.

set( %params )

Parameters are config key => config/value pairs

Set the config key to its value for each pair passed in. Return a hash of the new key/value pairs, or a single value if only one pair was passed in.

Possible modifications: Use wantarray to see if we should return a hash or a single value. Use 'force' parameter to ensure that blank (or undef) values passed in are reflected properly.

get_dir( 'directory-tag' )

Retrieves the directory name for 'directory-tag', which within the Config object may depend on other settings. For instance, you could have:

 $c->set( 'base_dir', '/home/cwinters/work/cw' );
 $c->set( 'html_dir', '$BASE_DIR/html' );
 $c->set( 'image_dir', '$HTML_DIR/images' );

and call:

 $c->get_dir( 'image_dir' );

and receive:

 '/home/cwinters/work/cw/html/images'

in return.

We should probably generalize this to other types of settings, but this Config object is probably on its last legs anyway.

ABSTRACT METHODS

These are methods meant to be overridden by subclasses, so they do not really do anything here. Useful for having a template to see what subclasses should do, however.

read_config()

Abstract method for subclasses to override with their own means of reading in config information (from DBI, file, CGI, whatever).

Returns: $config_obj on success; undef on failure

save_config()

Abstract method for subclasses to override with their own means of writing config to disk/eleswhere.

Returns: true on success; undef on failure.

TODO

Permanent Configuration Values

Future work should include setting configuration values permanently for future uses of the module. We could instantiate the configuration object with an argument giving it a file to read the keys/values from. A DESTROY routine could then save all changed values to the file. This would also allow us to change looks very easily...

BUGS

Remove Configuration Values

Need to determine a way to remove a value for a configuration item. Since we test for the existence of a value to determine if we are getting or setting, a non-existent value will simply return what is there. Not a big deal currently.

See Possible modifications entries for both set() and param_set().

COPYRIGHT

Copyright (c) 2001-2002 intes.net, inc.. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>

cpanm OpenInteract

perl -MCPAN -e shell
install OpenInteract