The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CGI-Application-Plugin-Config-Any-0.14
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.13

SYNOPSIS

There are two ways to initialize this module.

In your instance script:

    my $app = WebApp->new(
        PARAMS => {
            config_dir    => '/path/to/configfiles',
            config_files  => [ 'app.conf' ],
            config_name   => 'main',
            config_params => {
                ## passed to Config::Any->load_files;
                ## see Config::Any for valid params
            }
        }
    );
    $app->run();

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(
            config_dir    => '/path/to/configfiles',
            config_files  => [ 'app.conf' ],
            config_name   => 'main',
            config_params => {
                ## passed to Config::Any->load_files;
                ## see Config::Any for valid params
            }
        );
    }

Later...

    ## get a complete config section as a hashref
    my $section = $self->config_section( 'sectionname' );
    
    ## get a single config param
    my $param = $self->config( '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.)

EXPORTS

By default, only the config() method is exported.

The following methods are only exported on demand:

config_init
config_name
config_section
config_read

You can import them explicitly, or use ':all':

    use CGI::Application::Plugin::Config::Any qw( :all );

METHODS

config

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

There are several ways to retrieve a config param:

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

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

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

    $self->config('mysetting');
    # let the module find a param named 'mysetting' without
    # knowing or bothering the section name

See also BUGS!

config_init

Initializes the plugin.

    $self->config_init(
        config_dir   => '/path/to/configfiles',
        config_files => [ 'app.conf' ],
    );

Valid params:

config_dir SCALAR

Path where the config files reside in.

config_files ARRAY

A list of files to load.

config_name SCALAR

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

    $self->config_init(
        config_name   => 'database',
        config_files  => [ 'db.conf' ],
    );
    $self->config_init(
        config_name   => 'template',
        config_files  => [ 'tpl.conf' ],
    );

    ...

    my $connection_options  = $self->config_section('connection', name => 'database' );
    my $template_file       = $self->config( 'file', name => 'template' );
config_names HASHREF
config_params HASHREF

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

Example:

    $self->config_init(
        config_files  => [ 'default.yml' ],
        config_params => {
            'use_ext' => 1,
        }
    );

See Config::Any for details.

config_name

Set the name of the config to use.

config_section

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

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

config_read

Get complete configuration as a hashref.

    my $config = $self->config_read();

std_config

For CGI::Application::Standard::Config compatibility. Just returns 'TRUE'.

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

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('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.