/ 
Config-Simple-Extended-0.09
River stage one • 1 direct dependent • 1 total dependent
/ Config::Simple::Extended

NAME

Config::Simple::Extended - Extend Config::Simple w/ Configuration Inheritance, chosen by URL

VERSION

Version 0.09

SYNOPSIS

my $url = $cgi->url(); my $cfg_file_path = parse_url_for_config_path($url); my $cfg_base_path = '/etc/app_name/sites'; my $cfg_path = "$cfg_base_path/$cfg_file_path";

my $installation_cfg = Config::Simple->new( file => '$cfg_path/app_name.ini' );

my $client_cfg = Config::Simple::Extended->inherit( base_config => $installation_cfg, filename => '$cfg_path/client_name/app_name.ini', );

my $job_cfg = Config::Simple::Extended->inherit( base_config => $client_cfg, filename => '$cfg_path/client_name/app_job_id.ini', );

EXAMPLES

For details on accessing configuration parameters, read perldoc Config::Simple, which is well documented. In short, even if you wanted to bypass the published methods, everything seems to be found at: $cfg->{'_DATA'}->{$stanza}->{$key}, which then takes an anonymous list of whatever you feed it. The notes below focus on how to set up overloading configuration files How to write a constructor which will use them, how to share configuration hashes among modules in an application, etc.

These configuration hashes can be shared around with other objects which need them, like this:

my $object = My::New::Module->new({ 'cfg' => $self->{'cfg'} });

assuming that you are inside an object method whose constructor stored the configuration hash at its own 'cfg' key, as I tend to do.

or to needlessly duplicate the object in your memory overhead, as I did it when I was first digging around in the innards of Config::Simple, and learning how to use it:

my $new_object = My::New::Module->new({ 
   'config_file' => $self->{'cfg'}->{'_FILE_NAME'} });

Now I can write a constructor like this:

    package My::New::Module;

sub new {
  my $class = shift;
  my $defaults = shift;
  my $self = {};

  if(defined($defaults->{'config_file'})){
    $self->{'cfg'} = Config::Simple->new(
      $defaults->{'config_file'} );
  } elsif(defined($defaults->{'config_files'})){
    my $cfg;
    undef($cfg);
    foreach my $file (@{$defaults->{'config_files'}}){
      $cfg = Config::Simple::Extended->inherit({
            base_config => $cfg,
               filename => $file });
    }
    $self->{'cfg'} = $cfg;
  } else {
    die "Constructor invoked with no Confirguration File."
  }

  my $db = $self->{'cfg'}->get_block('db');
  # print STDERR Dumper(\$db);
  $self->{'dbh'} = My::New::Module::DB->connect($db);

  bless $self, $class;
  return $self;
}

Making it possible to use it like so:

my $new_object = My::New::Module->new({ 
       'config_files' => [ '/etc/my_app/base_configuration.ini',
                           '/etc/my_app/client/client_configuration.ini',
                           '/etc/my_app/client/job_id.ini' ]  });

with the job config over-writing the client config, over-writing the base config. If you let untrusted users write their own job configuration files, you probably want to reverse the order of the array, so that your base configuration file ultimately overwrites the final object with your sanity checks and security barriers in place.

METHODS

$cfg_file_path = parse_url_for_config_path($url);

This converts a url into a configuration file path, in a manner similar to the way that drupal lays out its configuration files, permitting a single code installation to host multiple instances of the same application. Each url is aliased to the same code installation, and this method sorts out which configuration to provide it.

->Config::Simple::Extended->inherit();

This is copied verbatim from ->Config::Simple::Inherit->inherit(); And this module's version number is taken from that module, as well.

->inherit()

This module only offers this one method, but I trust you'll find it useful. It returns a Config::Simple object, when given a reference to a hash, of which it only recognizes two keys: 'base_config' and 'filename'. The 'base_config' ought to be left undefined or set to a 'Config::Simple' object created with either this method or the ->new() method provided by Config::Simple. When 'base_config' is given a Config::Simple object, it walks every configuration parameter defined in the filename, and uses the new value to update the value for the respective parameterin the 'base_config' object, inheriting values from it, but overloading the configuration with the new values.

I envision essentially two ways this module might be used:

(1) to provide a means for getting more specific with a configuration by first creating an installation-wide configuration, then a client specific configuration, then job specific configuration, each overloading the more general values provided by the configuration before it.

(2) to enforce client, and installation security controls and sanity checks on a configuration prepared by an untrusted user. Say you had an application which permitted a local user to create a configuration file for a job. By loading the user created configuration first, then using the installation default configuration to overwrite it, it would be possible to prevent abuse and enforce system wide constraints.

AUTHOR

Hugh Esco, <hesco at campaignfoundations.com>

BUGS

On January 2nd, 2012 I resolved a long standing documentation bug which I believe (but have in no way confirmed) was introduced by an interface change to Config::Simple.

Please report any bugs or feature requests to bug-config-simple-inherit at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-Simple-Extended. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

I also do business as CampaignFoundations.com, where we host an issues que, available at: http://www.campaignfoundations.com/project/Config-Simple-Extended

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Config::Simple::Extended

You can also look for information at:

ACKNOWLEDGEMENTS

Sherzod B. Ruzmetov, author of Config::Simple, which I've come to rely on as the primary tool I use to manage configuration for the applications I write.

COPYRIGHT & LICENSE

Copyright 2008-2012 Hugh Esco, all rights reserved.

This program is released under the following license: Gnu Public License.

SEE ALSO

Config::Simple which handles ini, html and simple formats. Config::Simple::Extended returns a Config::Simple object, and the accessors (and other methods) for its configuration are documented by Mr. Ruzmetov in the perldoc for his module.

If you need some combination of json, yaml, xml, perl, ini or Config::General formats, take a look at: Config::Merge, which I learned of after releasing version 0.03 of this module to cpan.