/ 
Data-Schema-0.03
/ Data::Schema

NAME

Data::Schema - Validate nested data structures with nested structure

VERSION

Version 0.03

SYNOPSIS

# OO interface
use Data::Schema;
my $validator = Data::Schema->new();
my $schema = [array => {min_len=>2, max_len=>4}];
my $data = [1, 2, 3];
my $res = $validator->validate($data, $schema);
print "valid!" if $res->{success}; # prints 'valid!'

# procedural interface
use Data::Schema;
my $sch = ["hash",
           {keys =>
                {name => "str",
                 age  => ["int", {required=>1, min=>18}]
                }
            }
          ];
my $r;
$r = ds_validate({name=>"Lucy", age=>18}, $sch); # success
$r = ds_validate({name=>"Lucy"         }, $sch); # fail: missing age
$r = ds_validate({name=>"Lucy", age=>16}, $sch); # fail: underage

DESCRIPTION

NOTE: THIS IS A PRELIMINARY RELEASE. I have pinned down more or less the general code structure, user interface, and schema syntax which I want, as well as implemented a fairly complete set of types and type attributes. Also you already can create new types by using schema or by writing Perl type handlers. In short, it's already usable in term of validation task (and I am about to use it in production code). However there are other stuffs like handling of default values, variable substitution, filters, etc. which will be implemented in future releases.

There are already a lot of data validation modules on CPAN. However, most of them do not validate nested data structures. And of the rest, either I am not really fond of the syntax, or the validator/schema system is not simple/flexible/etc enough for my taste. Thus Data::Schema (DS) is born.

With DS, you validate a nested data structure with a schema, which is also a nested data structure. This makes the schema more easily reusable in other languages. Also, in DS you can define new types (or subtypes, actually) using schema itself. This makes your validation "routine" even more reusable.

Potential application of DS: validating configuration, function parameters, command line arguments, etc.

To get started, see Data::Schema::Manual::Basics.

FUNCTIONS

ds_validate($data, $schema)

Non-OO wrapper for validate(). Exported by default. See validate() method.

ATTRIBUTES

config

Configuration hashref. See CONFIG section.

METHODS

merge_attr_hashes($attr_hashes)

Merge several attribute hashes if there are hashes that can be merged (i.e. contains merge prefix in its keys). Used by DST::Base and DST::Schema. As DS user, normally you wouldn't need this.

init_validation_state()

Initialize validation state. Used internally by validate(). As DS user, normally you wouldn't need this.

save_validation_state()

Save validation state (position in data, position in schema, number of errors, etc) into a stack, so that you can start using the validator to validate a new data with a new schema, even in the middle of validating another data/schema. Used internally by validate() and DST::Schema. As DS user, normally you wouldn't need this.

See also: restore_validation_state().

restore_validation_state()

Restore the last validation state into a stack. Used internally by validate() and DST::Schema. As DS user, normally you wouldn't need this.

See also: save_validation_state().

log_error($message)

Add an error when in validation process. Will not add if there are already too many errors (too_many_errors attribute is true). Used by type handlers. As DS user, normally you wouldn't need this.

log_warning($message)

Add a warning when in validation process. Will not add if there are already too many warnings (too_many_warnings attribute is true). Used by type handlers. As DS user, normally you wouldn't need this.

check_type_name($name)

Checks whether $name is a valid type name. Returns true if valid, false if invalid. By default it requires that type name starts with a lowercase letter and contains only lowercase letters, numbers, and underscores. Maximum length is 64.

You can override this method if you want stricter/looser type name criteria.

register_type($name, $class|$obj)

Register a new type, along with a class name ($class) or the actual object ($obj) to handle the type. If $class is given, the class will be require'd (if not already require'd) and instantiated to become object.

Any object can become a type handler, as long as it has:

* a validator() rw property to store/set validator object; * handle_type() method to handle type checking; * zero or more handle_attr_*() methods to handle attribute checking.

See Data::Schema::Manual::TypeHandler for more details on writing a type handler.

register_plugin($class|$obj)

Register a new plugin. Accept a plugin object or class. If $class is given, the class will be require'd (if not already require'd) and instantiated to become object.

Any object can become a plugin, you don't need to subclass from anything, as long as it has:

* a validator() rw property to store/set validator object; * zero or more handle_*() methods to handle some events/hooks.

See Data::Schema::Manual::Plugin for more details on writing a plugin.

call_handler($name, [@args])

Try handle_*() method from each registered plugin until one returns 0 or 1. If a plugin return -1 (decline) then we continue to the next plugin. Returns the status of the last plugin. Returns -1 if there's no handler to invoke.

get_type_handler($name)

Try to get type handler for a certain type. If type is not found, invoke handle_unknown_type() in plugins to give plugins a chance to load the type. If type is still not found, return undef.

normalize_schema($schema)

Normalize a schema into the third form (hash form) ({type=>..., attr_hashes=>..., def=>...) as well as do some sanity checks on it. Returns an error message string if fails.

register_schema_as_type($schema, $name)

Register schema as new type. $schema is a normalized schema. Return {success=>(0 or 1), error=>...}. Fails if type with name $name is already defined, or if $schema cannot be parsed. Might actually register more than one type actually, if the schema contains other types in it (hash form of schema can define types).

validate($data[, $schema])

Validate a data structure. $schema must be given unless you already give the schema via the schema attribute.

Returns {success=>0 or 1, errors=>[...], warnings=>[...]}. The 'success' key will be set to 1 if the data validates, otherwise 'errors' and 'warnings' will be filled with the details.

CONFIG

Configuration is set like this:

my $validator = new Data::Schema;
$validator->config->{CONFIGVAR} = 'VALUE';
# ...

Available configuration variables:

max_errors => INT

Maximum number of errors before validation stops. Default is 10.

max_warnings => INT

Maximum number of warnings before warnings will not be added anymore. Default is 10.

schema_search_path => [...]

A list of places to look for schemas. If you use DSP::LoadSchema::YAMLFile, this will be a list of directories to search for YAML files. If you use DSP::LoadSchema::Hash, this will be the hashes to search for schemas. This is used if you use schema types (types based on schema).

See <Data::Schema::Type::Schema> for more details.

gettext_function => \&func

If set to a coderef, then this will be used to get custom error message when errmsg attribute suffix is used. For example, if schema is:

[str => {regex=>'/^\w+$/', 'regex.errmsg'=>'alphanums_only'}]

then your function will be called with 'alphanums_only' as the argument.

SEE ALSO

Data::Schema::Manual::Basics, Data::Schema::Manual::Schema, Data::Schema::Manual::TypeHandler, Data::Schema::Manual::Plugin

Some other data validation modules on CPAN: Data::FormValidator, Data::Rx, Kwalify.

AUTHOR

Steven Haryanto, <steven at masterweb.net>

BUGS

Please report any bugs or feature requests to bug-data-schema at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-Schema. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Data::Schema

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2009 Steven Haryanto, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.