File Coverage

blib/lib/Data/Domain/Dependencies.pm

Criterion	Covered	Total	%
statement	44	44	100.0
branch	7	10	70.0
condition	3	6	50.0
subroutine	14	14	100.0
pod	4	4	100.0
total	72	78	92.3

package Data::Domain::Dependencies;

use strict;
use warnings;

use Params::Validate::Dependencies qw(:_of exclusively);
use Scalar::Util qw(blessed);
use Exporter qw(import);

use base qw(Data::Domain);

use vars qw($VERSION @EXPORT @EXPORT_OK %EXPORT_TAGS);
$VERSION = '1.30';

@EXPORT = ();
@EXPORT_OK = (
  @{$Params::Validate::Dependencies::EXPORT_TAGS{_of}},
  qw(exclusively Dependencies)
);
%EXPORT_TAGS = (all => \@EXPORT_OK);

=head1 NAME

Data::Domain::Dependencies

=head1 DESCRIPTION

A sub-class of Data::Domain which provides functions and objects
to let Data::Domain use the same
functions as Params::Validate::Dependencies.

NB now this only works on perl 5.10 and higher as Data::Domain started
using some features of more modern perls.

=head1 SYNOPSIS

This creates a domain which, when passed a hashref to inspect, will
check that it contains at least one of an 'alpha' or 'beta' key, or
both of 'foo' and 'bar'.

  use Data::Domain::Dependencies qw(:all);

  my $domain = Dependencies(
    any_of(
      qw(alpha beta),
      all_of(qw(foo bar))
    )
  );

  my $errors = $domain->inspect(\%somehash);

=head1 SUBROUTINES and EXPORTS

Nothing is exported by default, but you can export any of the *_of
functions of Params::Validate::Dependencies, and the 'Dependencies'
and 'exclusively' functions. They are all available under the 'all' tag.

=head2 Dependencies

This takes a code-ref argument as returned by the *_of functions.

It returns an object which is a sub-class of Data::Domain::Dependencies
and so has an 'inspect' method that you can use to check for errors
when passing it a hash-ref.

=cut

sub Dependencies {
  my $sub = shift;
  __PACKAGE__->new($sub);
}

=head2 new

'Dependencies' above is really just a thin wrapper around this
constructor.  You are encouraged to not call this directly.

=cut

sub new {
  my($class, $sub) = @_;
  die("$class constructor must be passed a Params::Validate::Dependencies object or a code-ref\n")
    unless(ref($sub) =~ /CODE/ || (blessed($sub) && $sub->isa('Params::Validate::Dependencies::Documenter')));
  if(blessed($sub)) {
    my $target_class = "${class}::".$sub->name();
    no strict 'refs';
    unless(@{"${target_class}::ISA"}) {
      # multiple inheritance so we can get at Data::Domain->inspect()
      # and Params::Validate::Dependencies::Documenter->_document()
      @{"${target_class}::ISA"} = (
        'Data::Domain::Dependencies',
        blessed($sub)
      );
    }
    return bless sub { $sub->(@_) }, $target_class;
  } else {
    return bless sub { $sub->(@_) }, $class;
  }
}

=head2 generate_documentation

This is an additional method, not found in Data::Domain, which
generates vaguely readable
documentation for the domain.  Broadly speaking, it spits out the
source code.

=cut

sub generate_documentation {
  my $self = shift;
  $self->_document();
}

# this is where the magic happens ...
sub inspect {
  my $sub = shift;
  my $data = shift;
  return __PACKAGE__." can only inspect hashrefs\n"
    unless(ref($data) =~ /HASH/i);

  return $sub->($data) ? () : __PACKAGE__.": validation failed";
}

=head1 LIES

Some of the above is incorrect.  If you really want to know what's
going on, look at L.

=head1 BUGS, LIMITATIONS, and FEEDBACK

I like to know who's using my code.  All comments, including constructive
criticism, are welcome.

Please report any bugs either by email or using L
or at L.

Bug reports should contain enough detail that I can replicate the
problem and write a test.  The best bug reports have those details
in the form of a .t file.  If you also include a patch I will love
you for ever.

=head1 SEE ALSO

L

L

=head1 SOURCE CODE REPOSITORY

L

L

=head1 COPYRIGHT and LICENCE

Copyright 2011 David Cantrell EFE

This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.

=head1 CONSPIRACY

This module is also free-as-in-mason.

=cut

1;