/ 
Config-Strict-0.02
River stage zero No dependents
/ Config::Strict

NAME

Config::Strict - Add strict type-checking to configuration data

VERSION

0.02 (alpha release)

SYNOPSIS

use Config::Strict;
use Declare::Constraints::Simple -All;               # For custom checks

# A comprehensive example
my $config = Config::Strict->new( {
    name   => "Example",                             # Type system name
    params => {                                      # Parameter types & names
        Bool     => [ qw( my_bool1 my_bool2 ) ],     # Multiple parameters
        Int      => 'my_i',                          # Single parameter
        Num      => 'my_n',
        Str      => [ qw( my_str1 my_str2 ) ],
        Regexp   => 'my_re',
        ArrayRef => 'my_aref',
        HashRef  => 'my_href',
        CodeRef  => 'my_cref',
        Enum     => { my_enum => [ qw( v1 v2 ), undef ] },
        Custom   => {                                # Custom routines
            # Bare coderef:
            my_pos1 => sub { $_[ 0 ] > 0 },          # Positive number
            # Declare::Constraints::Simple code profiles:
            my_pos2 => And( IsNumber, Matches( qr/^[^-]+$/ ) ),
                                                     # Equivalent to my_pos1
            my_nest => IsA( 'Config::Strict' ),      # Nested configuration
        }
    },
    required => [ qw( my_bool1 my_n ) ],             # Required parameters
    defaults => {                                    # Default values
        my_bool1    => 1,
        my_str2     => 'str',
        my_enum     => 'e2',
        my_n        => -1.1,
        my_pos1     => 1_000,
        my_pos1     => 3.3
    },
} );

# Access and change the data

# Retrieve a single value
$config->get_param( 'my_n' );

# Retrieve a list of values
$config->get_param( qw( my_bool1 my_str2 ) );

# Set multiple parameters
$config->set_param( 'my_pos1' => 1, 'my_pos2' => 2 );

# The following will die
$config->get_param( 'bad_name' );           # bad_name doesn't exist in the configuration
$config->set_param( 'my_i' => 2.2 );        # my_i must be an integer
$config->set_param( 'my_pos2' => -5 );      # my_pos2 must be positive

DESCRIPTION

Config::Strict utilizes Declare::Constraints::Simple to enable strict parameter type-checking to configuration data. Both built-in and custom types can be used to build a validation profile for the entire configuration.

A typical workflow would be:

1. Use some configuration module to parse a configuration file.
2. Construct a Config::Strict type system for your configuration data.
3. Load the parsed configuration hash into the Config::Strict object using set_param.
4. Use get_param in your program to access configuration values.
5. Write any changes back to disk using some module.

See Declare::Constraints::Simple::Library for an index to available constraints and the parent documentation for defining your own constraints and scoping.

This is a Moose module.

CONSTRUCTING A TYPE SYSTEM

Declare the type system during construction:

Config::Strict->new( \%opts )

%opts is a multi-level hash with the following top-level keys:

name (Required)

Points to the name of the type system. This name is appended to "Config::Strict::Params::" for proper namespacing of the Moose HashRef subtype that uniquely describes the entire configuration data structure. See Moose::Meta::TypeConstraint for more details.

params (Required)

Points to the hash of parameter types and names, where the keys are the built-in Config::Strict types (more below).

The values are either a single parameter name or an arrayref of parameter names, with the exception of the special types Enum and Custom which point to a uniquely defined hashref.

Any parameter not named here cannot be added later - any attempt to access a parameter not provided in the constructor will result in an error.

Parameter Types And Values:

Bool

Those parameters which must take the value 0 or 1.

Int

Integer parameters.

Num

Generic number parameters.

Str

Generic string parameters.

Enum

Enumerated parameters. The Enum key points to a hashref with $parameter_name => $values pairs, where $values is an arrayref of valid values for the enum $parameter_name.

Regexp

Compiled regexp parameters (with qr//).

ArrayRef

Generic list parameters.

HashRef

Generic hash parameters.

CodeRef

Generic code parameters.

Custom

Custom validation code. The Custom key points to a hashref with $parameter_name => $coderef pairs, where $coderef is an anonymous subroutine that validates a single argument and returns true or false (1 or 0) if the given value is a valid one for that parameter.

$coderef can be either literal (sub { my $val = $_[0]; ... }) or a Declare::Constraints::Simple "profile." These code profiles will actually return a Declare::Constraints::Simple::Result which evaluate properly in boolean context but give more information (see the documentation for details).

required (Optional)

Points to a arrayref of parameter names that must have valid values at all times. These parameters must also be given a default value.

The special value '_all' will require all parameters to be required.

defaults (Optional)

Points to a hashref of default values to any number of parameters. Those parameters listed in required must be present in this section.

GETTING AND SETTING PARAMETER VALUES

These methods will die with a stack trace if a parameter doesn't exist in the configuration profile, or if an attempt is made to set a parameter with an invalid value.

$obj->get_param( parameter, parameter, ... )

Returns the list of values corresponding to each parameter.

$obj->set_param( parameter => value, parameter => value, ... )

Sets each parameter-value configuration pair.

OTHER METHODS

$obj->param_exists( $param )

Returns true if $param can be get/set.

$obj->param_set( $param )

Returns true if $param has been set.

$obj->get_profile( $param )

Returns the coderef "profile" used to validate $param. It takes a single argument and returns true if the passed argument would be a valid value for $param. If it's a Declare::Constraints::Simple profile (true for all cases except custom bare coderefs) it will more specifically return a Declare::Constraints::Simple::Result.

$obj->all_params()

Returns the list of all parameter names.

EXTENDING THE DEFAULT TYPES

There are several ways to make your type system even more strict than the provided parameter types:

1. Using the Custom key and combining any number of Declare::Constraints::Simple routines, and/or your own.
2. Using the Custom key and defining your own validation coderefs.
3. Subclassing Config::Strict and augmenting the _get_check and _set_check validation methods to add your own general validation semantics. These methods are executed before get_param and set_param, respectively, and receive the same arguments in @_.

See also "INNER_AND_AUGMENT" in Moose::Manual::MethodModifiers.

TODO

SEE ALSO

Declare::Constraints::Simple

CAVEATS

This is an alpha release - the API is subject to change.

AUTHOR

Blake Willmarth

bwillmarth at gmail.com

BUGS

Please report any bugs or feature requests to bug-config-strict at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-Strict. I will be notified, and then you'll automatically be notified of progress on your bug as changes are made.

LICENSE AND COPYRIGHT

Copyright 2010 Blake Willmarth.

This program is free software; you can redistribute it and/or modify it under the terms of either:

  • the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

  • the Artistic License version 2.0.