/ 
Data-Rx-0.200007
River stage two • 9 direct dependents • 11 total dependents
⭐ Starred 213 GitHub stars
/ Data::Rx

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

http://rx.codesimply.com/

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.