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

       Copyright (C) 2001-2009 Andy Wardley.  All Rights Reserved.

       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.

SEE ALSO

       Badger::Data::Type::Simple