view release on metacpan or  search on metacpan

lib/CGI/Application/Plugin/Config/Context.pm  view on Meta::CPAN

package CGI::Application::Plugin::Config::Context;

use warnings;
use strict;
require 5.006;

use base 'Exporter';
use CGI::Application;
use Config::Context;

use Carp;
use File::Spec;
use Scalar::Util qw(weaken isweak);
use Cwd;

use vars '@EXPORT';
@EXPORT = qw(conf);

our $CGIAPP_Namespace = '__CONFIG_CONTEXT';

=head1 NAME

CGI::Application::Plugin::Config::Context - Hierarchical, context-based configuration support for CGI::Application

=head1 VERSION

Version 0.18

=cut

our $VERSION = '0.18';

=head1 SYNOPSIS

=head2 Simple Access to Configuration

In your L<CGI::Application>-based module:

    use base 'CGI::Application';
    use CGI::Application::Plugin::Config::Context;

    sub cgiapp_init {
        my $self = shift;

        # Set config file and other options
        $self->conf->init(
            file   => 'app.conf',
            driver => 'ConfigGeneral',
        );
    }

    sub my_run_mode {
        my $self = shift;

        # get entire configuration
        my %conf = $self->conf->context;

        # get entire configuration (as a reference)
        my $conf = $self->conf->context;

        # get single config parameter
        my $value = $self->conf->param('some_value');

        # get raw configuraion (pre-context-matching)
        my $raw_config = $self->conf->raw;
        my %raw_config = $self->conf->raw;
    }

=head2 Configuration Based on URL or Module

You can match a configuration section to the request URL, or to the
module name.  For instance, given the following configuration file:

lib/CGI/Application/Plugin/Config/Context.pm  view on Meta::CPAN

I<accidentally leaking these data into your web pages.>


=head1 METHODS

=cut

# The 'conf' method is the only sub exported into the cgiapp namespace all
# other methods are called through the object returned by this method.
#
# 'conf' checks to see if an object of the requested name (or the default,
# unnamed object) already exists in the webapp object.
#
# If it exists it returns a reference to it
#
# If it doesn't exist, it creates it and returns a reference to it
#
#
# Note that at the moment, subclasses of this plugin are probably not
# possible because of the call to __PACKAGE__->new.


sub conf {
    my ($self, $conf_name) = @_;

    if (defined $conf_name) {
        # Named config
        if (not exists $self->{$CGIAPP_Namespace}->{'__NAMED_CONFIGS'}->{$conf_name}) {
            $self->{$CGIAPP_Namespace}->{'__NAMED_CONFIGS'}->{$conf_name} = __PACKAGE__->_new($self, $conf_name);

        }
        return $self->{$CGIAPP_Namespace}->{'__NAMED_CONFIGS'}->{$conf_name};
    }
    else {
        # Default config
        if (not exists $self->{$CGIAPP_Namespace}->{'__DEFAULT_CONFIG'}) {
            $self->{$CGIAPP_Namespace}->{'__DEFAULT_CONFIG'} = __PACKAGE__->_new($self);
        }
        return $self->{$CGIAPP_Namespace}->{'__DEFAULT_CONFIG'};
    }
}

sub _new {
    my ($proto, $webapp, $conf_name) = @_;

    my $class = ref $proto || $proto;

    my $package = ref $webapp;

    my $self = {
        '__CONFIG_NAME'     => $conf_name,
        '__CALLERS_PACKAGE' => $package,
        '__CGIAPP_OBJ'      => $webapp,
        '__CONFIG'          => undef,
        '__RAW_CONFIG'      => undef,
        '__CONFIG_OBJ'      => undef,
    };

    # Force reference to CGI::Application object to be weak to avoid
    # circular references
    weaken($self->{'__CGIAPP_OBJ'});

    return bless $self, $class;
}

=head2 init

Initializes the plugin.  The only required parameter is the source of
the configuration, either C<file>, C<string> or C<hash>.

    $self->conf->init(
        file => 'app.conf',
    );

The other paramters are described below:

=over 4

=item file

The path to the configuration file to be parsed.

=item string

A string containing configuration data to be parsed.

=item hash

A Perl data structure containing containing the pre-parsed config data.

=item driver

Which L<Config::Context> driver should parse the config.  Currently
supported drivers are:

    driver            module name
    ------            -----------
    ConfigGeneral     Config::Context::ConfigGeneral
    ConfigScoped      Config::Context::ConfigScoped
    XMLSimple         Config::Context::XMLSimple

The default driver is C<ConfigGeneral>.

=item driver_options

Options to pass directly on to the driver.  This is a multi-level hash,
where the top level keys are the driver names:

    my $conf = Config::Context->new(
        driver => 'ConfigScoped',
        driver_options => {
           ConfigGeneral => {
               -AutoLaunder => 1,
           },
           ConfigScoped = > {
               warnings => {
                   permissions  => 'off',
               }
           },
        },
    );