/ 
CGI-Application-Plugin-Config-Any-0.04
River stage zero No dependents
/ CGI::Application::Plugin::Config::Any

NAME

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

VERSION

Version 0.04

SYNOPSIS

In your CGI::Application-based module:

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

sub cgiapp_init {
    my $self = shift;

    # Set config file and other options
    $self->config->init(
        configdir => '/path/to/configfiles',
        files     => [ 'app.conf' ],
        name      => 'main',
        params    => {
            ## passed to Config::Any->load_files;
            ## see Config::Any for valid params
        }
    );
}

Later...

## get a complete config section as a hashref
$self->config->section( 'sectionname' );

## get a single config param
$self->config->param( 'sectionname.paramname' );

DESCRIPTION

This module allows to use Config::Any for config files inside a CGI::Application based application.

This module is "work in progress" and subject to change without warning!

(Config::Any provides a facility for Perl applications and libraries to load configuration data from multiple different file formats. It supports XML, YAML, JSON, Apache-style configuration, Windows INI files, and even Perl code.)

METHODS

init

Initializes the plugin.

$self->config->init(
    configdir => '/path/to/configfiles',
    files     => [ 'app.conf' ],
);

Valid params:

configdir SCALAR

Path where the config files reside in.

files ARRAY

A list of files to load.

name SCALAR

You can use more than one configuration at the same time by using config names. For example:

$self->config->init(
    name   => 'database',
    files  => [ 'db.conf' ],
);
$self->config->init(
    name   => 'template',
    files  => [ 'tpl.conf' ],
);

...

my $connection_options  = $self->config('database')->section('connection');
my $template_config     = $self->config('template')->param('file');
params HASHREF

Options to pass to Config::Any->load_files().

Example:

$self->config->init(
    files  => [ 'default.yml' ],
    params => {
        'use_ext' => 1,
    }
);

See Config::Any for details.

config

This method is exported to your C::A based application as an accessor to the configuration methods.

param

Retrieve a value from your configuration.

Examples:

$self->config->section('mysection')->param('mysetting');
# set the section to 'mysection' before retrieving 'mysetting'

$self->config->param('mysetting','mysection');
# more convenient way to do the same as above

$self->config->param('mysection.mysetting');
# another way to do the same as above

$self->config->param('mysetting');
# if no section name is given, the name of the last section
# named by ->section() or ->param(<section>.<attribute>) syntax
# is used; this may change in future, so don't rely on it!

section

Retrieve a complete section from your configuration, or set the name of the current "default section" for later use with ->param().

my $hash = $self->config->section('mysection');

getall

Get complete configuration as a hashref.

DEBUGGING

This module provides some internal debugging. Any debug messages go to STDOUT, so beware of enabling debugging when running in a web environment. (This will end up with "Internal Server Error"s in most cases.)

There are two ways to enable the debug mode:

In the module

Find line

$CGI::Application::Plugin::Config::Any::DEBUG = 0;

and set it to any "true" value. ("1", "TRUE", ... )

From outside the module

Add this line before calling new:

$CGI::Application::Plugin::Config::Any::DEBUG = 1;

AUTHOR

Bianka Martinovic, <mab at cpan.org>

BUGS/CAVEATS

This module is "work in progress" and subject to change without warning!

Complex data structures

At the moment, there is no way to require a key buried deep in the config data structure. Example for a more complex data structure (YAML syntax):

database_settings:
    dsn: dbi:mysql:cm4web2:localhost
    driver: mysql
    host: localhost
    port: 3306
    additional_args:
        ShowErrorStatement: 1

You can not require the key 'ShowErrorStatement' directly, 'cause it's a subkey of 'additional_args', but the param() method does not support nested section names.

Anyway, if CAP::Config::Any isn't able to find a required key in the current section, it walks through the complete config data structure to find it. So, the following works with this example:

my $param = $self->config->param('ShowErrorStatement');
## this will return '1'

There is no way to suppress this at the moment, so beware of having similar named keys in different sections of your configuration! You may not get what you expected.

SUPPORT

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

perldoc CGI::Application::Plugin::Config::Any

You can also look for information at:

DEPENDENCIES

Config::Any

ACKNOWLEDGEMENTS

This module was slightly inspired by CGI::Application::Plugin::Context. See http://search.cpan.org/perldoc?CGI::Application::Plugin::Config::Context for details.

COPYRIGHT & LICENSE

Copyright 2008 Bianka Martinovic, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.