/ 
Data-Rx-0.200008
River stage two • 9 direct dependents • 11 total dependents
/ Data::Rx

NAME

Data::Rx - perl implementation of Rx schema system

VERSION

version 0.200008

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);

PERL VERSION

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

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 <cpan@semiotic.systems>

CONTRIBUTORS

  • Daniel Lucraft <dan@fluentradical.com>

  • Hakim Cassimally <hakim@mysociety.org>

  • Jeremy Vonderfecht <CesiumLifeJacket@gmail.com>

  • Ricardo Signes <rjbs@semiotic.systems>

  • Ronald J Kimball <rjk@tamias.net>

  • Vonderfecht <vond085@we19772.pnl.gov>

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 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.