NAME

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

VERSION

version 0.011

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.

PERL VERSION SUPPORT

This code is effectively abandonware. Although releases will sometimes be made to update contact info or to fix packaging flaws, bug reports will mostly be ignored. Feature requests are even more likely to be ignored. (If someone takes up maintenance of this code, they will presumably remove this notice.)

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

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). It is also handed a hashref of relevant information, most importantly field_name.

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
  input  - the input given to the consume method
  field_name - the field name

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.

AUTHOR

Ricardo SIGNES <rjbs@semiotic.systems>

COPYRIGHT AND LICENSE

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

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.