Bianka Martinovic > CGI-Application-Plugin-Config-Any-0.13 > CGI::Application::Plugin::Config::Any

Download:
CGI-Application-Plugin-Config-Any-0.13.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.13   Source   Latest Release: CGI-Application-Plugin-Config-Any-0.14

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/CAVEATS!

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

syntax highlighting: