view release on metacpan or  search on metacpan

lib/Badger/Data/Facet.pm  view on Meta::CPAN

    }

    @optional = $class->list_vars(OPTS);
    @$self{ @optional } = @$config{ @optional };
    
    $self->{ name } ||= do {
        my $pkg = ref $self;
        $pkg =~ /.*::(\w+)$/;
        $1;
    };
    
    return $self;
}


sub validate {
    shift->not_implemented;
}


sub invalid {
    shift->error(@_);
}


sub invalid_msg {
    my $self = shift;
    $self->invalid( $self->message( @_ ) );
}


1;

__END__

=head1 NAME

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

=head1 SYNOPSIS

TODO

=head1 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.

=head1 DESCRIPTION

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

=head1 METHODS

=head2 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 C<$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 C<$config> and copies
the value into C<$self>.

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

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

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

=head2 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 I<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 I<reference> will also be passed.  You may
not be expecting this.

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

=head2 invalid($message)

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

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

=head2 invalid_msg($format,@args)

This method is used internally (e.g. by the L<validate()> method) to report
invalid values using a pre-defined L<message()|Badger::Base/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 );
    }

=head1 PACKAGE VARIABLES

=head2 $MESSAGES

Subclasses may defined their own message formats (for use with 
L<invalid_msg()>) using the C<$MESSAGES> package variable.  This should
be a reference to a hash array mapping short names to message formats.