NAME

WebApp::Config - WebApp Configuration File Interface

VERSION

  Time-stamp: <2006-04-25 14:04:03 mailto:attila@stalphonsos.com>
  $Id: Config.pm,v 1.13 2006/04/26 03:52:02 attila Exp $

SYNOPSIS

 use WebApp::Config;

 # The last WebApp::Config object constructed is cached, and
 # can be queried implicitly or explicitly, via Get.

 # Query cached config
 my $somevar = WebApp::Get(undef,"SomeSection","somevar","somedefault");

 # Query a config object, although if it is undef, we fall back to the
 # cached case
 my $somevar = WebApp::Get($somecfg,"SomeSection","somevar","somedefault");

 # The normal OO case
 my $somevar = $somecfg->get("SomeSection","somevar","somedefault");

DESCRIPTION

WebApp configuration front end to Config::IniFiles, which knows about some basic config sections we always want to be there, and provides a general framework for filtering configuration data.

OVERVIEW

Export tags:

:all

Export everything

DETAILED DOCUMENTATION

Dump [$fh]

names [$sect]

If no argument is given, the names of all top-level config sections are returned. If an argument is given, the names of all the parameters in the named section are returned.

In either case, we return the number of items in a scalar context, and the actual list in an array context.

get $section,$param[,$default]

Get the value for $param in config section $section; if $default is supplied, and there is no such config var, it is returned.

isset $section,$param

Returns true if the given parameter in the given section is defined, and false otherwise.

new [args=>vals]

Constructor. The very first Config object created will be cached in a global variable for use by the Get class method, so that you can have code access an applications configuration data without having to pass an extra parameter around, if you like...

Takes the following named args

file => filename

Filename to load; defaults to @APP_NAME@.config

dir => dir

Directory to look for file in

DONT_CACHE => 1|0

If non-zero, we do not cache this config object if there is none cached already.

Get [$cfg,]$stanza,$name[,$default]

Class method that can be used to get configuration information regardless of what form it is in.

WebApp::Config::Get behaves slightly differently depending on its initial argument. If it is a WebApp::Config object, then it is shifted off of the argument list, and the normal get method is invoked on it using whatever arguments are left. If it is anything else, and at least one WebApp::Config object has been created (and, generally, only one is created in the life of a webapp), then the get method is invoked on the cached global configuration object with all of the arguments to Get.

The upshot of this is that you can write code like:

  $allow_lusers = WebApp::Config::Get("Options","lusers",1);

which reads fairly naturally, or you can do

  $config_object = new WebApp::Config();
  ...
  $allow_lusers = WebApp::Config::Get($config_object,"Options","lusers",1);

which is equivalent to

  $allow_lusers = $config_object->get("Options","lusers",1);

which is equivalent to

  $allow_lusers = $config_object->Get("Options","lusers",1);

which is equivalent to

  $allow_lusers = WebApp::Config::Get(undef,"Options","lusers",1);

This last thing is an odd special case, so that you can have a variable that might have your config object or might be undef, depending on what point in time things are happening, and stuff will still work. For instance, a method that takes an optional argument for a WebApp::Config object might do something like

  sub foo {
    my %args = @_;
    my $cfg = $args{cfg};
    my $allow_lusers = WebApp::Config::Get($cfg,"Options","lusers",1);
    ...
  }

If the caller sends a cfg argument, then Get will use it, otherwise it will use the global config, otherwise it will return the default.

AUTHOR

Sean Levy <mailto:snl@cluefactory.com>

COPYRIGHT AND LICENSE

(C) 2002-2006 by Sean Levy <mailto:snl@cluefactory.com>. all rights reserved.

This code is released under a BSD license. Please see the LICENSE file that came with the source distribution, or visit http://cluefactory.com/oss/WebApp/license.html.

TODO/BUGS

We here at the agency have no sense of humor that we are aware of, Ma'am.