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.

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);

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

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

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 );
}

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>.',
};