- NAME
- VERSION
- SYNOPSIS
- METHODS
- COMPLEX CHECKS
- SCHEMA METHODS
- SEE ALSO
- AUTHOR
- CONTRIBUTORS
- COPYRIGHT AND LICENSE
NAME
Data::Rx - perl implementation of Rx schema system
VERSION
version 0.200007
SYNOPSIS
my $rx = Data::Rx->new;
my $success = {
type => '//rec',
required => {
location => '//str',
status => { type => '//int', value => 201 },
},
optional => {
comments => {
type => '//arr',
contents => '//str',
},
},
};
my $schema = $rx->make_schema($success);
my $reply = $json->decode( $agent->get($http_request) );
die "invalid reply" unless $schema->check($reply);
METHODS
new
my $rx = Data::Rx->new(\%arg);
This returns a new Data::Rx object.
Valid arguments are:
prefix - optional; a hashref of prefix pairs for type shorthand
type_plugins - optional; an arrayref of type or type bundle plugins
no_core_types - optional; if true, core type bundle is not loaded
sort_keys - optional; see the sort_keys section.
The prefix hashref should look something like this:
{
'pobox' => 'tag:pobox.com,1995:rx/core/',
'skynet' => 'tag:skynet.mil,1997-08-29:types/rx/',
}
make_schema
my $schema = $rx->make_schema($schema);
This returns a new schema checker method for the given Rx input. This object will have check
and assert_valid
methods to test data with.
register_type_plugin
$rx->register_type_plugin($type_or_bundle);
Given a type plugin, this registers the plugin with the Data::Rx object. Bundles are expanded recursively and all their plugins are registered.
Type plugins must have a type_uri
method and a new_checker
method. See Data::Rx::Manual::CustomTypes for details.
learn_type
$rx->learn_type($uri, $schema);
This defines a new type as a schema composed of other types.
For example:
$rx->learn_type('tag:www.example.com:rx/person',
{ type => '//rec',
required => {
firstname => '//str',
lastname => '//str',
},
optional => {
middlename => '//str',
},
},
);
add_prefix
$rx->add_prefix($name => $prefix_string);
For example:
$rx->add_prefix('.meta' => 'tag:codesimply.com,2008:rx/meta/');
sort_keys
$rx->sort_keys(1);
When sort_keys is enabled, causes Rx checkers for //rec and //map to sort the keys before validating. This results in failures being produced in a consistent order.
COMPLEX CHECKS
Note that a "schema" can be represented either as a name or as a definition. In the "SYNOPSIS" above, note that we have both, '//str' and { type => '//int', value => 201 }
. With the collection types provided by Rx, you can validate many complex structures. See "learn_types" for how to teach your Rx schema object about the new types you create.
When required, see Data::Rx::Manual::CustomTypes for details on creating a custom type plugin as a Perl module.
SCHEMA METHODS
The objects returned by make_schema
should provide the methods detailed in this section.
check
my $ok = $schema->check($input);
This method just returns true if the input is valid under the given schema, and false otherwise. For more information, see assert_valid
.
assert_valid
$schema->assert_valid($input);
This method will throw an exception if the input is not valid under the schema. The exception will be a Data::Rx::FailureSet. This has two important methods: stringify
and failures
. The first provides a string form of the failure. failures
returns a list of Data::Rx::Failure objects.
Failure objects have a few methods of note:
error_string - a human-friendly description of what went wrong
stringify - a stringification of the error, data, and check string
error_types - a list of types for the error; like tags
data_string - a string describing where in the input the error occured
value - the value found at the data path
check_string - a string describing which part of the schema found the error
SEE ALSO
AUTHOR
Ricardo SIGNES <rjbs@cpan.org>
CONTRIBUTORS
Hakim Cassimally <hakim@mysociety.org>
Ronald J Kimball <rjk@tamias.net>
Ronald J Kimball <rkimball@pangeamedia.com>
Ronald J Kimball <rkimball@snapapp.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2015 by Ricardo SIGNES.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.