File Coverage

lib/Config/Simple/Extended.pm

Criterion	Covered	Total	%
statement	77	80	96.2
branch	11	18	61.1
condition	3	5	60.0
subroutine	11	11	100.0
pod	3	3	100.0
total	105	117	89.7

package Config::Simple::Extended;

use warnings;
use strict;
use base qw( Config::Simple );
use FindBin;
use Data::Dumper;

use lib "$FindBin::Bin/../../../local/lib/perl5";
use File::PathInfo;

our $VERSION = '0.15';

=head1 NAME

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

=head1 VERSION

Version 0.15

=cut

=head1 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',
);

  This is intended to provide, before this is complete
    ->inherit() to inherit configurations, done;
    ->parse_config_directory() choosing configuration by url;
    ->heredoc() to parse heredoc configurations (still pending);
    anything else?

=head1 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 used
to do, or in a ->cfg attribute as I tend to do these days now
that Moose has come along.

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'} });

But don't do that.  It will make your dumpers needlessly confusing.

Now I can write a constructor like this:

=over

    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;
    }

=back

or, with Moose, perhaps adapt that as a ->_build_cfg() method
to populate a ->cfg() attribute.  That is how I've used this
module since I started using Moose.

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.

=cut

=head1 METHODS

=head2  $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.

=cut

sub parse_url_for_config_path {
  my $self = shift;
  my($url)=@_;
  my $scriptpath = $0;
  my $scriptname = $0;
  my $default_domain = 'localhost.supporters';
  $scriptname =~ s/^(.*)\///;
  $scriptpath =~ s/$scriptname//;
  $url =~ s/https:\/\///;
  $url =~ s/http:\/\///;
  $url =~ s/\//./g;
  # print STDERR "The scriptname is: ",$scriptname,"\n";
  # print STDERR "The scriptpath is: ",$scriptpath,"\n";
  $url =~ s/$scriptname$//;
  $url =~ s/\.$//;
  # account for command line tests
  if($url eq 'localhost'){
    $url = $default_domain;
    $scriptpath =~ s/t\///;
  }
  $url = $scriptpath."conf.d/".$url;
  # print STDERR "The \$url is $url.\n";
  # $self->{'conf_path'} = $url;
  # print STDERR "The conf_path is $self->{'conf_path'}.\n";
  # print STDERR Dumper(\$self);
  return $url;
} # END parse_url_for_config_path

=head2 ->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.

=head2 ->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.

=cut

sub inherit {
  my $class = shift;
  my $args = shift;
  my $f = new File::PathInfo;

  # print STDERR Dumper(\$args);
  { no strict 'refs';
    unless(defined($args->{'base_config'}) &&
        UNIVERSAL::isa($args->{'base_config'},'Config::Simple')) {
      print "the base_config undef, return Config::Simple object \n"
          if( $args->{'debug'} );
      return Config::Simple->new( filename => $args->{'filename'} );
    }
  }
  my @cfg_filenames;
  my $cfg = $args->{'base_config'};
  print "The base_config exists and includes this data: "
      . Dumper( $cfg->{'_DATA'} ) if( $args->{'debug'} && 0 );
  if(defined($cfg->{'_FILE_NAMES'})){
    push @cfg_filenames, @{$cfg->{'_FILE_NAMES'}};
    push @cfg_filenames, $args->{'filename'};
  } elsif(defined($cfg->{'_FILE_NAME'})) {
    push @cfg_filenames, $cfg->{'_FILE_NAME'};
    push @cfg_filenames, $args->{'filename'};
  } else {
    die "We have a Config::Simple object, without an initial '_FILE_NAME' value.\n";
  }
  $cfg->{'_FILE_NAMES'} = \@cfg_filenames;
  $f->set( $args->{'filename'} ) or die('file does not exist');
  my $cfg_file = $f->abs_path;
  my $cfg_overload = Config::Simple->new( $cfg_file );
  print 'Our $cfg_overload applies this file: '
      . $args->{'filename'}
      . ' and looks like this: '
      . Dumper( $cfg_overload )
          if( $args->{'debug'} );

  my $stanzas = get_stanzas($cfg_overload);
  foreach my $stanza ( @{$stanzas} ){
    my %stanza = %{$cfg_overload->get_block( $stanza )};
    foreach my $param_key (keys %stanza){
      print "\t$stanza.$param_key being overloaded with "
          . $cfg_overload->param("$stanza.$param_key")
          . "\n" if( $args->{'debug'} );
      $cfg->param( "$stanza.$param_key", $cfg_overload->param("$stanza.$param_key") );
    }
  }

  return $cfg;
}

=head2 my $array_ref = get_stanzas( $cfg );

If you use a hierarchical configuration file structure, with values
assigned to keys inside of stanzas, you can use this method to
pull a reference to a list of the stanzas currently defined
in your configuration file.  In an ini files this would be
denoted as [stanza_name], as if it were a one element arrayref.

=cut

sub get_stanzas {
  my $cfg = shift;
  my @stanzas;
  my %stanza_keys;
  my %config = $cfg->vars();
  foreach ( keys %config ){
    $_ =~ s/\..*//;
    $stanza_keys{$_} = 1;
  }
  @stanzas = keys %stanza_keys;
  return \@stanzas;
}

=head1 AUTHOR

Hugh Esco, C<<  >>

=head1 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.

On January 11th, 2013, I hardened this module by using the
interface, rather than the internals of Config::Simple.

It seems that ->inherit will not overwrite a configuration
value for a key which does not already exist in the inherited
from ->cfg object.  That is something which should be easy to
rectify but which seems barely outside the scope of this evening's
work when I'm supposed to be working on something else which
depends on these changes.  I had not noticed this prior to these
revisions and this may represent regression.  Hope this does not
break production installations for others.  I will try to watch
the smoke tests and RT and respond if I see these recent enhancements
make problems for folks.

Please report any bugs or feature requests to
C, or through the web interface at
L.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.

=head1 SUPPORT

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

    perldoc Config::Simple::Extended

You can also look for information at:

=over 4

=item * AnnoCPAN: Annotated CPAN documentation

L

=item * CPAN Ratings

L

=item * RT: CPAN's request tracker

L

I also watch for bug reports at:

L

=item * Search CPAN

L

=back

=head1 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.

=head1 COPYRIGHT & LICENSE

Copyright 2008-2013 Hugh Esco, all rights reserved.

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

=head1 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.

=cut

1; # End of Config::Simple::Extended