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

NAME

Config::Strict - Add strict typing to your configuration management

VERSION

0.01 (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',
        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 );

# Dies
$config->set_param( 'my_pos2' => -5 );      # my_pos2 must be positive

DESCRIPTION

Config::Strict leaps on the back of Declare::Constraints::Simple to make it easy to add strict parameter typing to your configuration management system.

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 parameters.
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 subtype (the parent Moose type is HashRef). 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.

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 list of parameter names that must have valid values at all times. These parameters must also be given a default value.

defaults (Optional)

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

GETTING AND SETTING PARAMETER VALUES

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

Returns the list of values corresponding to each parameter.

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

Sets each key-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->param_validator( $param )

Returns the coderef used to validate $param. It takes a single argument and returns true if the passed argument would be a valid value for $param.

$obj->all_params()

Returns the list of all parameter names.

EXTENDING THE DEFAULTS

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.