/ 
App-Framework-0.92
River stage one • 1 direct dependent • 1 total dependent
/ App::Framework::Feature::Config

NAME

App::Framework::Feature::Config - Configuration file read/write

SYNOPSIS

use App::Framework '+Config' ;

DESCRIPTION

Provides a standard interface for reading/writing application configuration files. When this feature is included into an application, it attempts to read a configuration file for the application (which may be stored in one of severeal places). If found, the configuartion file is processed and may update the application options (see App::Framework::Feature::Options).

Also, an application may create one or more extra instances of the feature to read addtional configuration files.

Configuration File Definition

Configuration files are text files containing variable / value pairs. Optionally these variable/value pairs may be gouped into 'sections' (see "sections").

Simple format

The simplest format consists of an optional description line followed immediately by a variable/value setting:

# description
var=value

(NOTE: There can be no empty lines between the description "comment" and the variable).

Extended format

An alternative to the simple format is as shown below. This contains additional information useful for checking the value setting.

## Summary:  Configuration for Apache 2
## Type:     s
#
# Here you can name files, separated by spaces, that should be Include'd from 
# httpd.conf. 
#
# This allows you to add e.g. VirtualHost statements without touching 
# /etc/apache2/httpd.conf itself, which makes upgrading easier. 
#
apache_include_files="mod_dav"

The lines prefixed by ## are extra information about the variable and are used to specify a summary, and a variable type. The extra information prefixed by # is used as the description. The above example will be shown in the application man page as:

-apache_include_files <string> [Default: "mod_dav"]
        Config option:Here you can name files, separated by spaces, that
        should be Include'd from httpd.conf. This allows you to add e.g.
        VirtualHost statements without touching /etc/apache2/httpd.conf
        itself, which makes upgrading easier.

Any configuration variables specified in this manner will automatically be put into the application's options, but will also be available via the application's 'Config' feature.

Sections

Each section is defined by a string contained within '[]'. Where there are multiple sections with the same name, they are added to an array. All variables defined before the sections are treated as "global".

global=string

[top]
a=1

[instance]
a=11

[instance]
a=22

The above example will be stored as the HASH:

{
    global => 'string'
    top => [
        {
            a => 1
        }
    ]
    instance => [
        {
            a => 11
        },
        {
            a => 22
        }
    ],
}

Even if a section has only one instance, it is always stored as an array.

Configuration as Options

As stated above, any variables defined in the configuration file before the sections are treated as "global" (see "Sections"). These global variables have the additional property that they are automatically treated like options definitions (see App::Framework::Feature::Options).

This means that the global variables are indistinguishable from options (in fact all of the options variables appear in the global area of the configurations and vice versa). Also, you do not need to specify options in the application script - you can just define them once in the configuration file (although see "Writing").

File Paths

The configuration file is searched for using the path specification. This path is actually one or more paths, specified in the order in which to search for the configuration file. The search is stopped as soon as the first valid file is found.

The application configuration search path is set to the following default, unless it is over-ridden by either the application script or by the user (via command line options):

  • $HOME/$app_dir

    User-specific configuration. $HOME is replaced with the user's home directory, and $app_dir is replaced by ".name" (or "name" on Windows) where name is the name of the script.

    This allows users to set up their own settings.

  • $SYSTEM/$name

    System configuration. $SYSTEM is replaced with "/etc" (or "C:" on Windows), and $name is replaced by the name of the script.

    This allows sysadmins to set up a common set of settings.

  • $app_path/config

    Application-specific configuration. $app_path is replaced by the path to the installed script.

    This allows script developers to bundle their settings with the installed script.

As an example, the script 'test_script' installed on a Linux under '/usr/local/bin' will, by default, have the following search path:

$HOME/.test_script
/etc/test_script
/usr/local/bin/config

In addition to the search path described above, there is also a write search path. This path is searched until a file (and it's path) can be written to by the script user. It is set, by default, to:

  • $HOME/$app_dir

    User-specific configuration. $HOME is replaced with the user's home directory, and $app_dir is replaced by ".name" (or "name" on Windows) where name is the name of the script.

    This allows users to set up their own settings.

  • $SYSTEM/$name

    System configuration. $SYSTEM is replaced with "/etc" (or "C:" on Windows), and $name is replaced by the name of the script.

    This allows sysadmins to set up a common set of settings.

(i.e. the same as the read path, but without the application-bundle directory).

Uses App::Framework::Base::SearchPath to provide the path search.

Creating Config Files

You can, of course, just write your config files from scratch. Alternatively, if you predominantly use "global" settings, then you specify them as application options (App::Framework::Feature::Options). Run your script with '-config_write' and it will automatically create a formatted configuration file (see "ADDITIONAL COMMAND LINE OPTIONS" for other command line settings).

Addtional Config Instances

In addition to having the application tied in with it's own configuration file, you can create multiple extra configuration files and read/write then using this feature. To do this, create a new App::Framework::Feature::Config object instance per configuration file. You can then access the contents of the file using the object's methods.

For example:

sub app
{
    my ($app, $opts_href, $args_href) = @_ ;
 
    ## use application config object to create a new one
    my $new_cfg = $app->feature('Config')->new(
        'filename'        => 'some_file.conf',
        'path'            => '$HOME,/etc/new_config',
        'write_path'    => '$HOME',
    ) ;
    $new_cfg->read() ;

    # do stuff with configuration
    ...
 
    # (debug) show configuration
    $app->prt_data("Readback config=", $new_cfg->config) ;
     
    ## write out file
    $new_cfg->write() ;
}

Raw Configuration HASH

Configuration files are stored in a HASH, where the keys are the variable names and the values are a HASH of information for that variable:

'summary'        => Summary string
'default'        => Default value
'description'    => Description string
'type'           => Variable option type (s, i, f)
'value'          => Variable value

FIELDS

The following fields should be defined either in the call to 'new()', as part of a 'set()' call, or called by their accessor method (which is the same name as the field):

filename - Name of config file

User-specified config filename. This is searched for using the search path

path - search path

A comma seperated list (in scalar context), or an ARRAY ref list of paths to be searched (for a file).

write_path - search path for writing

A comma seperated list (in scalar context), or an ARRAY ref list of paths to be searched (for a file) when writing. If not set, then path is used.

file_path - configuration file path

Created when config file is read. Full path of configuration file accessed in last read or write.

sections - section names list

Created when config file is read. ARRAY ref list of any section names.

config - configuration HASH ref

Created when config file is read. This is a HASH ref to the raw configuration file entries

ADDITIONAL COMMAND LINE OPTIONS

This feature adds the following additional command line options to any application:

-config_path - Config file path

Comma/semicolon separated list of search paths for the config file

-config_writepath - Config file write path

Comma/semicolon separated list of paths for writing the config file. Uses -config_path setting if not specified.

-config - Config filename

Specify the configuration filename to use

-config_write - Write config file

When specified, writes the configuration file using the write path

CONSTRUCTOR

new([%args])

Create a new Config object.

The %args are specified as they would be in the set method, for example:

'mmap_handler' => $mmap_handler

The full list of possible arguments are :

'fields'	=> Either ARRAY list of valid field names, or HASH of field names with default values

CLASS METHODS

init_class([%args])

Initialises the Config object class variables.

OBJECT DATA METHODS

set(%args)

Overrides the parent 'set()' method to send the parameters off to the App::Framework::Base::SearchPath object as well as itself.

OBJECT METHODS

go_entry()

Application hook: When application calls go() set up config options.

getopts_entry()

Application hook: When application calls getopts() initialise the object and read config.

application_entry()

Application hook: When application calls application() check options.

read([%args])

Read in the config file (located somewhere in the searchable path). Expects the filename and path fields to already have been set. Optionally can specify these setting as part of the %args hash.

Updates the field 'file_path' with the full path to the read config file.

Returns the top-level HASH ref.

write()

Writes the configuration information to the specified file.

Updates the field 'file_path' with the full path to the written config file.

add_config(%config)

Adds the contents of the specified HASH to the current configuration settings.

clear_config()

Clear out the current configuration settings.

get_hash([$name])

Returns a "flat" HASH (of variable/value pairs) where any arrays are removed. If the $name is specified, returns the HASH that the named key refers to, unrolling it if it is an array.

Returns an empty HASH if $name does not exist.

get_array([$name])

Returns an ARRAY of HASHes of variable/value pairs. If the $name is specified, returns the ARRAY that the named key refers to. In either case, if the item is not an array, then it is rolled into a single entry ARRAY.

Returns an empty ARRAY if $name does not exist.

get_raw_hash([$name])

Returns a "flat" HASH (containing full config entry) where any arrays are removed. If the $name is specified, returns the HASH that the named key refers to, unrolling it if it is an array.

Returns an empty HASH if $name does not exist.

get_raw_array([$name])

Returns an ARRAY of HASHes (containing full config entry). If the $name is specified, returns the ARRAY that the named key refers to. In either case, if the item is not an array, then it is rolled into a single entry ARRAY.

Returns an empty ARRAY if $name does not exist.

raw_to_vals($href)

Given a HASH ref containing hashes of full config entries, convert into a hash of variable/value pairs

DIAGNOSTICS

Setting the debug flag to level 1 prints out (to STDOUT) some debug messages, setting it to level 2 prints out more verbose messages.

AUTHOR

Steve Price <sdprice at cpan.org>

BUGS

None that I know of!