Rx.pm

filter: Statementstmt 93.2% 69 / 74 Branchbran 73.5% 25 / 34 Conditioncond 50.0% 2 / 4 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 92.3% 12 / 13 Podpod 75.0% 6 / 8 totaltotal 84.4% 114 / 135 CC 23 SCAR 14.8
CC
23
Cov
86%
new
7.4
make_schema
6.0
register_type_plugin
5.0
CRAP 4.4
« Rx/CommonType.pm ↑ Summary Rx/CoreType/bool.pm »
1 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
2 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 package Data::Rx;
4 # ABSTRACT: perl implementation of Rx schema system
5 1 $Data::Rx::VERSION = '0.200007';
6 1 ▶use Data::Rx::Util;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 1 ▶use Data::Rx::TypeBundle::Core;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 #pod =head1 SYNOPSIS
10 #pod
11 #pod my $rx = Data::Rx->new;
12 #pod
13 #pod my $success = {
14 #pod type => '//rec',
15 #pod required => {
16 #pod location => '//str',
17 #pod status => { type => '//int', value => 201 },
18 #pod },
19 #pod optional => {
20 #pod comments => {
21 #pod type => '//arr',
22 #pod contents => '//str',
23 #pod },
24 #pod },
25 #pod };
26 #pod
27 #pod my $schema = $rx->make_schema($success);
28 #pod
29 #pod my $reply = $json->decode( $agent->get($http_request) );
30 #pod
31 #pod die "invalid reply" unless $schema->check($reply);
32 #pod
33 #pod =head1 COMPLEX CHECKS
34 #pod
35 #pod Note that a "schema" can be represented either as a name or as a definition.
36 #pod In the L</SYNOPSIS> above, note that we have both, '//str' and
37 #pod C<{ type =E<gt> '//int', value =E<gt> 201 }>.
38 #pod With the L<collection types|http://rx.codesimply.com/coretypes.html#collect>
39 #pod provided by Rx, you can validate many complex structures. See L</learn_types>
40 #pod for how to teach your Rx schema object about the new types you create.
41 #pod
42 #pod When required, see L<Data::Rx::Manual::CustomTypes> for details on creating a
43 #pod custom type plugin as a Perl module.
44 #pod
45 #pod =head1 SCHEMA METHODS
46 #pod
47 #pod The objects returned by C<make_schema> should provide the methods detailed in
48 #pod this section.
49 #pod
50 #pod =head2 check
51 #pod
52 #pod my $ok = $schema->check($input);
53 #pod
54 #pod This method just returns true if the input is valid under the given schema, and
55 #pod false otherwise. For more information, see C<assert_valid>.
56 #pod
57 #pod =head2 assert_valid
58 #pod
59 #pod $schema->assert_valid($input);
60 #pod
61 #pod This method will throw an exception if the input is not valid under the schema.
62 #pod The exception will be a L<Data::Rx::FailureSet>. This has two important
63 #pod methods: C<stringify> and C<failures>. The first provides a string form of the
64 #pod failure. C<failures> returns a list of L<Data::Rx::Failure> objects.
65 #pod
66 #pod Failure objects have a few methods of note:
67 #pod
68 #pod error_string - a human-friendly description of what went wrong
69 #pod stringify - a stringification of the error, data, and check string
70 #pod error_types - a list of types for the error; like tags
71 #pod
72 #pod data_string - a string describing where in the input the error occured
73 #pod value - the value found at the data path
74 #pod
75 #pod check_string - a string describing which part of the schema found the error
76 #pod
77 #pod =head1 SEE ALSO
78 #pod
79 #pod L<http://rx.codesimply.com/>
80 #pod
81 #pod =cut
82  
83 sub _expand_uri {
84 119 ▶ my ($self, $str) = @_;
Subroutine _expand_uri: called CC=4 SCAR=14.2
85 119 ▶ return $str if $str =~ /\A\w+:/;
Branch: 1 branch
BranchTrueFalseTotal
if $str =~ /\A\w+:/ 7 112 119
86  
87 112 ▶ if ($str =~ m{\A/(.*?)/(.+)\z}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($str =~ m[\A/(.*?)/(.+)\z]) 112 0 112
88 112 my ($prefix, $rest) = ($1, $2);
89
90 112 my $lookup = $self->{prefix};
91 Carp::croak "unknown prefix '$prefix' in type name '$str'"
92 112 ▶ unless exists $lookup->{$prefix};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $lookup->{$prefix} 0 112 112
93  
94 112 return "$lookup->{$prefix}$rest";
95 }
96  
97 0 Carp::croak "couldn't understand Rx type name '$str'";
98 }
99  
100 #pod =method new
101 #pod
102 #pod my $rx = Data::Rx->new(\%arg);
103 #pod
104 #pod This returns a new Data::Rx object.
105 #pod
106 #pod Valid arguments are:
107 #pod
108 #pod prefix - optional; a hashref of prefix pairs for type shorthand
109 #pod type_plugins - optional; an arrayref of type or type bundle plugins
110 #pod no_core_types - optional; if true, core type bundle is not loaded
111 #pod sort_keys - optional; see the sort_keys section.
112 #pod
113 #pod The prefix hashref should look something like this:
114 #pod
115 #pod {
116 #pod 'pobox' => 'tag:pobox.com,1995:rx/core/',
117 #pod 'skynet' => 'tag:skynet.mil,1997-08-29:types/rx/',
118 #pod }
119 #pod
120 #pod =cut
121  
122 sub new {
123 54 ▶ my ($class, $arg) = @_;
Subroutine new: called CC=7 SCAR=20.0
Pod documented
124 54 ▶ $arg ||= {};
Condition50%1/2
$arg ||= {}
l!l
540
MC/DC0%0/1
$arg ||= {}
$arg
Truth table50%1/2
A
A= $arg
Aresult
11
00
125 54 ▶ $arg->{prefix} ||= {};
Condition50%1/2
$arg->{"prefix"} ||= {}
l!l
054
MC/DC0%0/1
$arg->{"prefix"} ||= {}
$arg->{"prefix"}
Truth table50%1/2
A
A= $arg->{"prefix"}
Aresult
11
00
126  
127 54 ▶ my @plugins = @{ $arg->{type_plugins} || [] };
Branch: 1 branch
BranchTrueFalseTotal
$arg->{"type_plugins"} or [] 54 0 54
128 54 ▶ unshift @plugins, $class->core_bundle unless $arg->{no_core_bundle};
Branch: 1 branch
BranchTrueFalseTotal
unless $arg->{"no_core_bundle"} 54 0 54
129  
130 my $self = {
131 prefix => { },
132 handler => { },
133 sort_keys => !!$arg->{sort_keys},
134 54 };
135  
136 54 bless $self => $class;
137  
138 54 $self->register_type_plugin($_) for @plugins;
139  
140 54 $self->add_prefix($_ => $arg->{prefix}{ $_ }) for keys %{ $arg->{prefix} };
141  
142 54 return $self;
143 }
144  
145 #pod =method make_schema
146 #pod
147 #pod my $schema = $rx->make_schema($schema);
148 #pod
149 #pod This returns a new schema checker method for the given Rx input. This object
150 #pod will have C<check> and C<assert_valid> methods to test data with.
151 #pod
152 #pod =cut
153  
154 sub make_schema {
155 121 ▶ my ($self, $schema) = @_;
Subroutine make_schema: called CC=6 SCAR=17.9
Pod documented
156  
157 121 ▶ $schema = { type => "$schema" } unless ref $schema;
Branch: 1 branch
BranchTrueFalseTotal
unless ref $schema 23 98 121
158  
159 121 ▶ Carp::croak("no type name given") unless my $type = $schema->{type};
Branch: 1 branch
BranchTrueFalseTotal
unless my $type = $schema->{"type"} 1 119 120
160  
161 119 my $type_uri = $self->_expand_uri($type);
162 119 ▶ die "unknown type uri: $type_uri" unless exists $self->{handler}{$type_uri};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{"handler"}{$type_uri} 2 117 119
163  
164 117 my $handler = $self->{handler}{$type_uri};
165  
166 117 my $schema_arg = {%$schema};
167 117 delete $schema_arg->{type};
168  
169 117 my $checker;
170  
171 117 ▶ if (ref $handler) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $handler) { } 2 115 117
172 2 ▶ if (keys %$schema_arg) {
Branch: 1 branch
BranchTrueFalseTotal
if (keys %$schema_arg) 0 2 2
173 0 Carp::croak("composed type does not take check arguments");
174 }
175 2 $checker = $self->make_schema($handler->{'schema'});
176 } else {
177 115 $checker = $handler->new_checker($schema_arg, $self, $type);
178 }
179  
180 103 return $checker;
181 }
182  
183 #pod =method register_type_plugin
184 #pod
185 #pod $rx->register_type_plugin($type_or_bundle);
186 #pod
187 #pod Given a type plugin, this registers the plugin with the Data::Rx object.
188 #pod Bundles are expanded recursively and all their plugins are registered.
189 #pod
190 #pod Type plugins must have a C<type_uri> method and a C<new_checker> method.
191 #pod See L<Data::Rx::Manual::CustomTypes> for details.
192 #pod
193 #pod =cut
194  
195 sub register_type_plugin {
196 54 ▶ my ($self, $starting_plugin) = @_;
Subroutine register_type_plugin: called CC=5 SCAR=16.1
Pod documented
197  
198 54 my @plugins = ($starting_plugin);
199 54 ▶ PLUGIN: while (my $plugin = shift @plugins) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $plugin = shift @plugins) 810 54 864
200 810 ▶ if ($plugin->isa('Data::Rx::TypeBundle')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($plugin->isa('Data::Rx::TypeBundle')) { } 54 756 810
201 54 my %pairs = $plugin->prefix_pairs;
202 54 $self->add_prefix($_ => $pairs{ $_ }) for keys %pairs;
203  
204 54 unshift @plugins, $plugin->type_plugins;
205 } else {
206 756 my $uri = $plugin->type_uri;
207  
208 Carp::confess("a type plugin is already registered for $uri")
209 756 ▶ if $self->{handler}{ $uri };
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"handler"}{$uri} 0 756 756
210
211 756 $self->{handler}{ $uri } = $plugin;
212 }
213 }
214 }
215  
216 #pod =method learn_type
217 #pod
218 #pod $rx->learn_type($uri, $schema);
219 #pod
220 #pod This defines a new type as a schema composed of other types.
221 #pod
222 #pod For example:
223 #pod
224 #pod $rx->learn_type('tag:www.example.com:rx/person',
225 #pod { type => '//rec',
226 #pod required => {
227 #pod firstname => '//str',
228 #pod lastname => '//str',
229 #pod },
230 #pod optional => {
231 #pod middlename => '//str',
232 #pod },
233 #pod },
234 #pod );
235 #pod
236 #pod =cut
237  
238 sub learn_type {
239 4 ▶ my ($self, $uri, $schema) = @_;
Subroutine learn_type: called CC=3 SCAR=11.0
Pod documented
240  
241 Carp::confess("a type handler is already registered for $uri")
242 4 ▶ if $self->{handler}{ $uri };
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"handler"}{$uri} 0 4 4
243  
244 die "invalid schema for '$uri': $@"
245 4 ▶ unless eval { $self->make_schema($schema) };
Branch: 1 branch
BranchTrueFalseTotal
unless eval { do { $self->make_schema($schema) } } 2 2 4
246  
247 2 $self->{handler}{ $uri } = { schema => $schema };
248 }
249  
250 #pod =method add_prefix
251 #pod
252 #pod $rx->add_prefix($name => $prefix_string);
253 #pod
254 #pod For example:
255 #pod
256 #pod $rx->add_prefix('.meta' => 'tag:codesimply.com,2008:rx/meta/');
257 #pod
258 #pod =cut
259  
260 sub add_prefix {
261 109 ▶ my ($self, $name, $base) = @_;
Subroutine add_prefix: called CC=2 SCAR=7.1
Pod documented
262  
263 Carp::confess("the prefix $name is already registered")
264 109 ▶ if $self->{prefix}{ $name };
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"prefix"}{$name} 0 109 109
265  
266 109 $self->{prefix}{ $name } = $base;
267 }
268  
269 #pod =method sort_keys
270 #pod
271 #pod $rx->sort_keys(1);
272 #pod
273 #pod When sort_keys is enabled, causes Rx checkers for //rec and //map to
274 #pod sort the keys before validating. This results in failures being
275 #pod produced in a consistent order.
276 #pod
277 #pod =cut
278  
279 sub sort_keys {
280 80 ▶ my $self = shift;
Subroutine sort_keys: called CC=2 SCAR=7.1
Pod documented
281  
282 80 ▶ $self->{sort_keys} = !!$_[0] if @_;
Branch: 1 branch
BranchTrueFalseTotal
if @_ 0 80 80
283  
284 80 return $self->{sort_keys};
285 }
286  
287 sub core_bundle {
288 54 ▶ return 'Data::Rx::TypeBundle::Core';
Subroutine core_bundle: called CC=1 SCAR=0.0
Pod undocumented
289 }
290  
291 sub core_type_plugins {
292 0 ▶ my ($self) = @_;
Subroutine core_type_plugins: not called CC=1 SCAR=6.9
Pod undocumented
293  
294 0 Carp::cluck("core_type_plugins deprecated; use Data::Rx::TypeBundle::Core");
295  
296 0 Data::Rx::TypeBundle::Core->type_plugins;
297 }
298  
299 1 1;
300  
301 __END__
« Rx/CommonType.pm ↑ Summary Rx/CoreType/bool.pm »