NAME
Class::DBI::Factory::Config - an AppConfig-based configuration mechanism for Class::DBI::Factory
SYNOPSIS
$config = Class::DBI::Factory::Config->new({
-file =>
});
my @classes = $config->classes;
my $tdir = $config->get('template_dir');
my @referers = $config->get('allowed_referer');INTRODUCTION
This is just a thin bit of glue that sits between AppConfig and Class::DBI::Factory. Its main purpose is to define the skeleton of parameters that AppConfig uses, but it also provides some useful shorthands for accessing commonly-needed parameters.
In the normal course of events you will never need to work with or subclass this module, or indeed know anything about it. The factory class will take care of constructing and maintaining its own configuration object and following the instructions contained therein.
AppConfig was chosen primarily because it is used by the Template Toolkit and therefore already loaded by my applications. If you're not using TT you may prefer to substitute some other configuration mechanism. You can also subclass more selectively, of course.
DATA SKELETON
The skeleton defined by this module is used by AppConfig to parse configuration files. It details the variables that we are expecting and what to do with each one. Simple variables don't need to be mentioned, but anything with multiple values or more than one level should be prescribed here.
skeleton()
This method returns a hashref that describes the configuration data it expects to encounter. You can refer to the documentation for AppConfig for details of how this works, but for most purposes you should only need to work with the list_parameters, hash_parameters and default_values methods.
You can subclass the whole skeleton() method, but for most purposes it will probably suffice to override some of the methods it calls:
list_parameters
Returns a list of parameter names that should be handled as lists of values rather than as simple scalars.
extra_list_parameters
If you want to extend the standard list of list parameters, rather than replacing it, then override this method and return your additions as a list of parameter names.
hash_parameters
Returns a list of parameter names that should be handled as hashes - ie the configuration files will specify both key and value.
extra_hash_parameters
If you want to extend the standard list of hash parameters, rather than replacing it, then override this method and return your additions as a list of parameter names.
default_values
Returns a hash of (parameter name => value), in which the value may be simple, a list or a hash. Its treatment will depend on what your data skeleton specifies for that parameter.
extra_defaults
If you want to extend the standard list of default values, rather than replacing it, then override this method and return your additions as a hash of name => default value pairs. The default values can be scalars, or references to lists or hashes as appropriate.
CONSTRUCTION AND MAINTENANCE
In which configuration files are sought, objects are built up and everything kept up to date.
new()
$config = Class::DBI::Factory::Config->new('/path/to/file');Should optionally take a file path parameter and pass it to file(): otherwise, just creates an empty configuration object ready for use but not yet populated.
_build()
This one does the real work of reading in all the configuration files we can find.
config_files()
Accessor for the list of config files that will be read. This list can't be set after construction, but you can always call file() to read more files in.
This method will always return the list of files that was supposed to be read on construction. Call files() if you would like the list of files (successfully) read during the lifetime of the config object.
extra_prep()
Placeholder for any configuration-loading steps you want to include.
This method is called after config files have been read, so settings here will override defaults.
file()
$config->file('/path/to/file', '/path/to/otherfile');Reads configuration files from the supplied addresses, and stores their addresses and modification dates in case of a later refresh() or rebuild().
refresh()
$config->refresh();
$config->refresh('/path/to/file');Checks the modification date for each of the configuration files that have been read: if any have changed since we read it, the whole configuration object is dropped and rebuilt.
By default this will revisit the whole set of read configuration files, but if you supply a list of files, refresh() will confine itself to looking at the intersection of your list and the list of files already read. Either way, configuration files are always read back in in the same order as we originally encountered them.
Note that if a configuration file is missing at startup it will not be looked for later: this only refreshes the files that were successfully read.
rebuild()
This will drop all configuration information and start again by re-reading all the configuration files. Any other changes your application has made, eg by setting values directly, will be lost.
files()
Returns a list in date order of all the configuration files successfully read during the lifetime of this object.
timestamp()
A possibly-useful read-only method that returns the epoch time at which this object read in its configuration files (ie when it was built, or last rebuilt).
ACCESS TO SETTINGS
CDF::Config uses the same conventions as AppConfig. If there's no clash with a method name, you can retrieve settings like this:
$address = $config->admin_email;
@views = $config->permitted_view;
[% FOREACH user IN config.sin_bin %]or like this, which is the syntax you'll have to use if either CDFC or AppConfig provides a method with the same name as your parameter:
$rebuild = $config->get('rebuild');And you can set values the same two ways:
$config->your_manager_for_today( $person->id );
$config->set( your_manager_for_today => $person->id );There are two big fat red flags to consider when setting values this way:
- If a configuration file is updated on disk, the configuration object will be torn down and rebuilt. Any changes you have made by calling set() will be lost.
You can call the tethered AppConfig object directly through $config->ac, if you must.
get()
Gets the named value.
set()
Sets the named value.
all()
returns a simple list of all the variable names held.
classes()
returns the list of classes we're supposed to load. This is just for readability: all it does is call get('class'), but it allows us to write:
$factory->config->classesinstead of the rather misleading:
$factory->config->classtemplate_path()
It's normal for a subclass to add lots of custom lookup methods that combine configuration settings in useful ways. This is the only one we need at this level. It returns a reference to an array of directories in which to look for TT templates.
These can be defined in two ways: directly, with a 'template_dir' parameter, or in two stages, with a 'template_root' and one or more 'template_subdir' parameters.
Sequence is important, since the first encountered instance of a template will be used. The order of definition is preserved (so site file > package file > global file), except that all template_dir values are given priority over all template_subdir values: the former would normally be defined by a standard package, the latter by local site configuration.
_new_ac()
Forces the creation of a new, empty AppConfig object. This should only ever be called during a build or rebuild.
SEE ALSO
AppConfig Class::DBI Class::DBI::Factory Class::DBI::Factory::Handler Class::DBI::Factory::List
AUTHOR
William Ross, wross@cpan.org
COPYRIGHT
Copyright 2001-4 William Ross, spanner ltd.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.