NAME

Data::InputMonster - consume data from multiple sources, best first; om nom nom!

VERSION

version 0.003

DESCRIPTION

This module lets you describe a bunch of input fields you expect. For each field, you can specify validation, a default, and multiple places to look for a value. The first valid value found is accepted and returned in the results.

FIELD DEFINITIONS

Each field is defined by a hashref with the following entries:

    sources - an arrayref of sources; see below; required
    filter  - a coderef to preprocess candidate values
    check   - a coderef to validate candidate values
    store   - a coderef to store accepted values
    default - a value to use if no source provides an acceptable value

Sources may be given in one of two formats:

    [ source_name => $source, ... ]
    [ $source_1, $source_2, ... ]

In the second form, sources will be assigned unique names.

The source value is a coderef which, handed the $input argument to the consume method, returns a candidate value (or undef).

A filter is a coderef that works by altering $_.

If given, check must be a coderef that inspects $_ and returns a true if the value is acceptable.

Store is called if a value is accepted. It is passed the monster and a hashref with the following entries:

    value  - the value accepted
    source - the name of the source from which the value was accepted

If default is given, it must be a simple scalar (in which case that is the default) or a coderef that will be called to provide a default value as needed.

METHODS

new

    my $monster = Data::InputMonster->new({
      fields => {
        field_name => \%field_spec,
        ...
      },
    });

This builds a new monster. For more information on the %field_spec parameters, see below.

consume

    my $result = $monster->consume($input, \%arg);

This method processes the given input and returns a hashref of the finally accepted values. $input can be anything; it is up to the field definitions to expect and handle the data you plan to feed the monster.

Valid arguments are:

    no_default_for - a field name or arrayref of field names for which to NOT
                     fall back to default values

AUTHOR

  Ricardo SIGNES <rjbs@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2008 by Ricardo SIGNES.

This is free software; you can redistribute it and/or modify it under the same terms as perl itself.