NAME

Badger::Data::Facet - base class validation facet for simple data types

SYNOPSIS

TODO

PLEASE NOTE

This module is a work in progress. The implementation is subject to change and the documentation may be incomplete or incorrect in places.

DESCRIPTION

This module implements a base class validation facet for data types.

METHODS

init($config)

Custom initialisation method for data facets. Subclasses may redefine this method to do something different. Otherwise the default behaviour is as follows.

It first looks for any $ARGS package variables (in the current and any base classes) which denote the names of mandatory arguments for the data type.

    our $ARGS = ['foo', 'bar'];

It then asserts that each of these is defined in the $config and copies the value into $self.

Any optional parameters can be specified using the $OPTS package variable.

    our $OPTS = 'baz';              # single string is sugar for ['baz']

If any of these value(s) are defined in the $config then they will be copied into $self.

validate($value,$type)

This is the main validation method for facets. Subclasses must redefine this method to implement their own validation routine.

The first argument is a reference to the candidate value. For list and hash data types, this will be a reference to the list or hash respectively, as you would usually expect. If the value is a non-reference scalar (e.g. a number or text string) then a reference will also be passed. You may not be expecting this.

    $facet->validate(\$text);
    $facet->validate(\@list);
    $facet->validate(\%hash);

invalid($message)

This method is used internally (e.g. by the validate() method) to report invalid values.

    $self->invalid("The value specified is not valid");

invalid_msg($format,@args)

This method is used internally (e.g. by the validate() method) to report invalid values using a pre-defined message() format.

    our $MESSAGES = {
        not_orange => 'The colour specified is not orange: %s',
    };

    sub validate {
        my ($self, $value) = @_;
        
        return $$value eq 'orange'
            || $self->invalid_msg( not_orange => $$value );
    }

PACKAGE VARIABLES

$MESSAGES

Subclasses may defined their own message formats (for use with invalid_msg()) using the $MESSAGES package variable. This should be a reference to a hash array mapping short names to message formats. These formats are expanded using the "xprintf()|Badger::Utils/xprintf()" function in Badger::Utils. This is a wrapper around "sprintf()" with some extra syntactic sugar for handling positional arguments.

    our $MESSAGES = {
        # messages taking one and two parameters
        not_orange => 'The colour specified is not orange: %s',
        not_colour => 'The colour specified is not %s: %s',

        # message specifying parameters in a different order
        alt_colour => 'You specified the colour <2> but that is not <1>.',
    };

AUTHOR

Andy Wardley <http://wardley.org/>

COPYRIGHT

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

ACKNOWLEDGEMENTS

This module is derived from the XML::Schema::Facet module, also written by Andy Wardley under funding from Canon Research Europe Ltd.