view release on metacpan or  search on metacpan

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

package CGI::Application::Plugin::Config::General;

use warnings;
use strict;
require 5.006;

use base 'Exporter';
use CGI::Application;
use Config::General::Match;

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

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

our $CGIAPP_Namespace = '__CONFIG_GENERAL';

=head1 NAME

CGI::Application::Plugin::Config::General - Add Config::General Support to CGI::Application

=head1 VERSION

Version 0.08

=cut

our $VERSION = '0.08';

=head1 NOTE

This module is obsolete and has now been superceded by
L<CGI::Application::Plugin::Config::Context>.

=head1 SYNOPSIS

=head2 Simple Access to Configuration

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

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

    sub cgiapp_init {
        my $self = shift;

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

    sub my_run_mode {
        my $self = shift;

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

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

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

        # get underlying Config::General::Match object
        my $obj = $self->conf->obj;
    }

=head2 Configuration Based on URL or Module

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

# 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);
            if ($self->can('add_callback')) {
                $self->add_callback('teardown', \&_clear_all_current_configs, 'LAST');
            }

        }
        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);
            if ($self->can('add_callback')) {
                $self->add_callback('teardown', \&_clear_all_current_configs, 'LAST');
            }
        }
        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,
        '__CONFIG_OBJ'         => undef,
        '__CONFIG_OBJ_CREATED' => undef,
        '__CONFIG'             => undef,
    };

    # Force reference to CGI::Applcation 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 a config file:

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

The other paramters are described below:

=over 4

=item -ConfigFile

The path to the configuration file to be parsed.

=item -Options

Any additional L<Config::General::Match> options.  See the documentation
to L<Config::General> and L<Config::General::Match> for more details.

=item -CacheConfigFiles

Whether or not to cache configuration files.  Enabled, by default.
This option is only really useful in a persistent environment such as
C<mod_perl>.  See L<Config File Caching> under L<ADVANCED USAGE>,
below.

=item -StatConfig

If config file caching is enabled, this option controls how often the
config files are checked to see if they have changed.  The default is 60
seconds.  This option is only really useful in a persistent environment
such as C<mod_perl>.  See L<Config File Caching> under
C<ADVANCED USAGE>, below.

=item -SiteSectionName

Change the name of the C<< <Site> >> section to something else.  For
instance, to use sections named C<< <VirtualHost> >>, use:

    -SiteSectionName => 'VirtualHost'

=item -SiteVar

Change the name of the C<SITE_NAME> environment variable used to match
against C<< <Site> >> sections.  For instance To change this name to
C<HTTP_HOST>, use:

    -SiteVar => 'HTTP_HOST',

=item -NestingDepth

The number of levels deep that sections can be nested.  The default is
two levels deep.