NAME

SQL::Translator::Validate - Validate that a data structure is correct

SYNOPSIS

use Test::More plan tests => 1;
use SQL::Translator;
use SQL::Translator::Validator;

my $tr = SQL::Translator->new(parser => "My::Swell::Parser");

# Default producer passes the data structure through unchanged
my $parsed = $tr->translate($datafile);

ok(validate($parsed), "data structure conformance to definition");

DESCRIPTION

When writing a parser module for SQL::Translator, it is helpful to have a tool to automatically check the return of your module, to make sure that it is returning the Right Thing. While only a full Producer and the associated database can determine if you are producing valid output, SQL::Translator::Validator can tell you if the basic format of the data structure is correct. While this will not catch many errors, it will catch the basic ones.

SQL::Translator::Validator can be used as a development tool, a testing tool (every SQL::Translator install will have this module), or, potentially, even as a runtime assertion for producers you don't trust:

$tr->producer(\&paranoid_producer, real_producer => "MySQL");
sub paranoid_producer {
    my ($tr, $data) = @_;
    validate($data) or die "You gave me crap!" 

    # Load real producer, and execute it
    $tr->producer($tr->producer_args->{'real_producer'});
    return $tr->produce($data);
}

SQL::Translator::Validator can also be used as a reporting tool. When validate is called in a list context, the second value returned (assuming the data structure is well-formed) is a summary of the table's information. For example, the following table definition (MySQL format):

CREATE TABLE random (
  id  int(11) not null default 1,
  seed char(32) not null default 1
);

CREATE TABLE session (
  foo char(255),
  id int(11) not null default 1 primary key
) TYPE=HEAP;

Produces the following summary:

Contains 2 tables.
Table 1: random
        Type: not defined
        Indices: none defined
        Fields:
                id int (11)
                        Default: 1
                        Null: no
                seed char (32)
                        Default: 1
                        Null: no
Table 2: session
        Type: HEAP
        Indices:
                (unnamed) on id
        Fields:
                foo char (255)
                        Null: yes
                id int (11)
                        Default: 1
                        Null: no

EXPORTED FUNCTIONS

SQL::Translator::Validator exports a single function, called validate, which expects a data structure as its only argument. When called in scalar context, it returns a 1 (valid data structure) or 0 (not a valid data structure). In list context, validate returns a 2 element list: the first element is a 1 or 0, as in scalar context, and the second value is a reason (for a malformed data structure) or a summary of the data (for a well-formed data structure).

TODO

• color, either via Term::ANSI, or something along those lines, or just plain $RED = "\033[31m" type stuff.

AUTHOR

darren chamberlain <darren@cpan.org>