Schema.pm

filter: Statementstmt 93.1% 123 / 132 Branchbran 66.6% 16 / 24 Conditioncond 87.5% 7 / 8 MC/DCmcdc 75.0% 3 / 4 Subroutinesub 100% 28 / 28 Podpod 60.0% 3 / 5 totaltotal 89.5% 180 / 201 CC 17 SCAR 12.7
CC
17
Cov
89%
new
9.7
start_element
4.8
end_element
4.0
CRAP 3.5
« Schema/Library.pm ↑ Summary Schema/Util.pm »
1 package XML::Validator::Schema;
2  
3 5 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 5 our $VERSION = '1.10';
8  
9 =head1 NAME
10  
11 XML::Validator::Schema - validate XML against a subset of W3C XML Schema
12  
13 =head1 SYNOPSIS
14  
15 use XML::SAX::ParserFactory;
16 use XML::Validator::Schema;
17  
18 #
19 # create a new validator object, using foo.xsd
20 #
21 $validator = XML::Validator::Schema->new(file => 'foo.xsd');
22  
23 #
24 # create a SAX parser and assign the validator as a Handler
25 #
26 $parser = XML::SAX::ParserFactory->parser(Handler => $validator);
27  
28 #
29 # validate foo.xml against foo.xsd
30 #
31 eval { $parser->parse_uri('foo.xml') };
32 die "File failed validation: $@" if $@;
33  
34 =head1 DESCRIPTION
35  
36 This module allows you to validate XML documents against a W3C XML
37 Schema. This module does not implement the full W3C XML Schema
38 recommendation (http://www.w3.org/XML/Schema), but a useful subset.
39 See the L<SCHEMA SUPPORT|"SCHEMA SUPPORT"> section below.
40  
41 B<IMPORTANT NOTE>: To get line and column numbers in the error
42 messages generated by this module you must install
43 L<XML::Filter::ExceptionLocator|XML::Filter::ExceptionLocator> and use
44 L<XML::SAX::ExpatXS|XML::SAX::ExpatXS> as your SAX parser. This
45 module is much more useful if you can tell where your errors are, so
46 using these modules is highly recommeded!
47  
48 =head1 INTERFACE
49  
50 =over 4
51  
52 =item *
53  
54 C<< XML::Validator::Schema->new(file => 'file.xsd', cache => 1) >>
55  
56 Call this method to create a new XML::Validator:Schema object. The
57 only required option is C<file> which must provide a path to an XML
58 Schema document.
59  
60 Setting the optional C<cache> parameter to 1 causes
61 XML::Validator::Schema to keep a copy of the schema parse tree in
62 memory. The tree will be reused on subsequent calls with the same
63 C<file> parameter, as long as the mtime on the schema file hasn't
64 changed. This can save a lot of time if you're validating many
65 documents against a single schema.
66  
67 Since XML::Validator::Schema is a SAX filter you will normally pass
68 this object to a SAX parser:
69  
70 $validator = XML::Validator::Schema->new(file => 'foo.xsd');
71 $parser = XML::SAX::ParserFactory->parser(Handler => $validator);
72  
73 Then you can proceed to validate files using the parser:
74  
75 eval { $parser->parse_uri('foo.xml') };
76 die "File failed validation: $@" if $@;
77  
78 Setting the optional C<debug> parameter to 1 causes
79 XML::Validator::Schema to output elements and associated attributes
80 while parsing and validating the XML document. This provides useful
81 information on the position where the validation failed (although not
82 at useful as the line and column numbers included when
83 XML::Filter::ExceptiionLocator and XML::SAX::ExpatXS are used).
84  
85 =back
86  
87 =head1 RATIONALE
88  
89 I'm writing a piece of software which uses Xerces/C++
90 ( http://xml.apache.org/xerces-c/ ) to validate documents against XML
91 Schema schemas. This works very well, but I'd like to release my
92 project to the world. Requiring users to install Xerces is simply too
93 onerous a requirement; few will have it already and the Xerces
94 installation system leaves much to be desired.
95  
96 On CPAN, the only available XML Schema validator is XML::Schema.
97 Unfortunately, this module isn't ready for use as it lacks the ability
98 to actually parse the XML Schema document format! I looked into
99 enhancing XML::Schema but I must admit that I'm not smart enough to
100 understand the code... One day, when XML::Schema is completed I will
101 replace this module with a wrapper around it.
102  
103 This module represents my attempt to support enough XML Schema syntax
104 to be useful without attempting to tackle the full standard. I'm sure
105 this will mean that it can't be used in all situations, but hopefully
106 that won't prevent it from being used at all.
107  
108 =head1 SCHEMA SUPPORT
109  
110 =head2 Supported Elements
111  
112 The following elements are supported by the XML Schema parser. If you
113 don't see an element or an attribute here then you definitely can't
114 use it in a schema document.
115  
116 You can expect that the schema document parser will produce an error
117 if you include elements which are not supported. However, unsupported
118 attributes I<may> be silently ignored. This should not be
119 misconstrued as a feature and will eventually be fixed.
120  
121 All of these elements must be in the http://www.w3.org/2001/XMLSchema
122 namespace, either using a default namespace or a prefix.
123  
124 <schema>
125  
126 Supported attributes: targetNamespace, elementFormDefault,
127 attributeFormDefault
128  
129 Notes: the only supported values for elementFormDefault and
130 attributeFormDefault are "unqualified." As such, targetNamespace
131 is essentially ignored.
132
133 <element name="foo">
134  
135 Supported attributes: name, type, minOccurs, maxOccurs, ref
136  
137 <attribute>
138  
139 Supported attributes: name, type, use, ref
140  
141 <sequence>
142  
143 Supported attributes: minOccurs, maxOccurs
144  
145 <choice>
146  
147 Supported attributes: minOccurs, maxOccurs
148  
149 <all>
150  
151 Supported attributes: minOccurs, maxOccurs
152  
153 <complexType>
154  
155 Supported attributes: name
156  
157 <simpleContent>
158  
159 The only supported sub-element is <extension>.
160  
161 <extension>
162  
163 Supported attributes: base
164  
165 Notes: only allowed inside <simpleContent>
166  
167 <simpleType>
168  
169 Supported attributes: name
170  
171 <restriction>
172  
173 Supported attributes: base
174  
175 Notes: only allowed inside <simpleType>
176  
177 <whiteSpace>
178  
179 Supported attributes: value
180  
181 <pattern>
182  
183 Supported attributes: value
184  
185 <enumeration>
186  
187 Supported attributes: value
188  
189 <length>
190  
191 Supported attributes: value
192  
193 <minLength>
194  
195 Supported attributes: value
196  
197 <maxLength>
198  
199 Supported attributes: value
200  
201 <minInclusive>
202  
203 Supported attributes: value
204  
205 <minExclusive>
206  
207 Supported attributes: value
208  
209 <maxInclusive>
210  
211 Supported attributes: value
212  
213 <maxExclusive>
214  
215 Supported attributes: value
216  
217 <totalDigits>
218  
219 Supported attributes: value
220  
221 <fractionDigits>
222  
223 Supported attributes: value
224  
225 <annotation>
226  
227 <documentation>
228  
229 Supported attributes: name
230  
231 <union>
232 Supported attributes: MemberTypes
233  
234 =head2 Simple Type Support
235  
236 Supported built-in types are:
237  
238 string
239  
240 normalizedString
241  
242 token
243  
244 NMTOKEN
245  
246 Notes: the spec says NMTOKEN should only be used for attributes,
247 but this rule is not enforced.
248  
249 boolean
250  
251 decimal
252  
253 Notes: the enumeration facet is not supported on decimal or any
254 types derived from decimal.
255  
256 integer
257  
258 int
259  
260 short
261  
262 byte
263  
264 unsignedInt
265  
266 unsignedShort
267  
268 unsignedByte
269  
270 positiveInteger
271  
272 negativeInteger
273  
274 nonPositiveInteger
275  
276 nonNegativeInteger
277  
278 dateTime
279  
280 Notes: Although dateTime correctly validates the lexical format it does not
281 offer comparison facets (min*, max*, enumeration).
282  
283 double
284  
285 Notes: Although double correctly validates the lexical format it
286 does not offer comparison facets (min*, max*, enumeration). Also,
287 minimum and maximum constraints as described in the spec are not
288 checked.
289  
290 float
291  
292 Notes: The restrictions on double support apply to float as well.
293  
294 duration
295  
296 time
297  
298 date
299  
300 gYearMonth
301  
302 gYear
303  
304 gMonthDay
305  
306 gDay
307  
308 gMonth
309  
310 hexBinary
311  
312 base64Binary
313  
314 anyURI
315  
316 QName
317  
318 NOTATION
319  
320 =head2 Miscellaneous Details
321  
322 Other known devations from the specification:
323  
324 =over
325  
326 =item *
327  
328 Patterns specified in pattern simpleType restrictions are Perl regexes
329 with none of the XML Schema extensions available.
330  
331 =item *
332  
333 No effort is made to prevent the declaration of facets which "loosen"
334 the restrictions on a type. This is a bug and will be fixed in a
335 future release. Until then types which attempt to loosen restrictions
336 on their base class will behave unpredictably.
337  
338 =item *
339  
340 No attempt has been made to exclude content models which are
341 ambiguous, as the spec demands. In fact, I don't see any compelling
342 reason to do so, aside from strict compliance to the spec. The
343 content model implementaton uses regular expressions which should be
344 able to handle loads of ambiguity without significant performance
345 problems.
346  
347 =item *
348  
349 Marking a facet "fixed" has no effect.
350  
351 =item *
352  
353 SimpleTypes must come after their base types in the schema body. For
354 example, this is ok:
355  
356 <xs:simpleType name="foo">
357 <xs:restriction base="xs:string">
358 <xs:minLength value="10"/>
359 </xs:restriction>
360 </xs:simpleType>
361 <xs:simpleType name="foo_bar">
362 <xs:restriction base="foo">
363 <xs:length value="10"/>
364 </xs:restriction>
365 </xs:simpleType>
366  
367 But this is not:
368  
369 <xs:simpleType name="foo_bar">
370 <xs:restriction base="foo">
371 <xs:length value="10"/>
372 </xs:restriction>
373 </xs:simpleType>
374 <xs:simpleType name="foo">
375 <xs:restriction base="xs:string">
376 <xs:minLength value="10"/>
377 </xs:restriction>
378 </xs:simpleType>
379  
380 =back
381  
382 =head1 CAVEATS
383  
384 Here are a few gotchas that you should know about:
385  
386 =over
387  
388 =item *
389  
390 No Unicode testing has been performed, although it seems possible that
391 the module will handle Unicode data correctly.
392  
393 =item *
394  
395 Namespace processing is almost entirely missing from the module.
396  
397 =item *
398  
399 Little work has been done to ensure that invalid schemas fail
400 gracefully. Until that is done you may want to develop your schemas
401 using a more mature validator (like Xerces or XML Spy) before using
402 them with this module.
403  
404 =back
405  
406 =head1 BUGS
407  
408 Please use C<rt.cpan.org> to report bugs in this module:
409  
410 http://rt.cpan.org
411  
412 Please note that I will delete bugs which merely point out the lack of
413 support for a particular feature of XML Schema. Those are feature
414 requests, and believe me, I know we've got a long way to go.
415  
416 =head1 SUPPORT
417  
418 This module is supported on the perl-xml mailing-list. Please join
419 the list if you have questions, suggestions or patches:
420  
421 http://listserv.activestate.com/mailman/listinfo/perl-xml
422  
423 =head1 CVS
424  
425 If you'd like to help develop XML::Validator::Schema you'll want to
426 check out a copy of the CVS tree:
427  
428 http://sourceforge.net/cvs/?group_id=89764
429  
430 =head1 CREDITS
431  
432 The following people have contributed bug reports, test cases and/or
433 code:
434  
435 Russell B Cecala (aka Plankton)
436 David Wheeler
437 Toby Long-Leather
438 Mathieu
439 h.bridge@fasol.fujitsu.com
440 michael.jacob@schering.de
441 josef@clubphoto.com
442 adamk@ali.as
443 Jean Flouret
444  
445 =head1 AUTHOR
446  
447 Sam Tregar <sam@tregar.com>
448  
449 =head1 COPYRIGHT AND LICENSE
450  
451 Copyright (C) 2002-2003 Sam Tregar
452  
453 This program is free software; you can redistribute it and/or modify
454 it under the same terms as Perl 5 itself.
455  
456 =head1 A NOTE ON DEVELOPMENT METHODOLOGY
457  
458 This module isn't just an XML Schema validator, it's also a test of
459 the Test Driven Development methodology. I've been writing tests
460 while I develop code for a while now, but TDD goes further by
461 requiring tests to be written I<before> code. One consequence of this
462 is that the module code may seem naive; it really is I<just enough>
463 code to pass the current test suite. If I'm doing it right then there
464 shouldn't be a single line of code that isn't directly related to
465 passing a test. As I add functionality (by way of writing tests) I'll
466 refactor the code a great deal, but I won't add code only to support
467 future development.
468  
469 For more information I recommend "Test Driven Development: By Example"
470 by Kent Beck.
471  
472 =head1 SEE ALSO
473  
474 L<XML::Schema>
475  
476 http://www.w3.org/XML/Schema
477  
478 http://xml.apache.org/xerces-c/
479  
480 =cut
481  
482 5 ▶use base qw(XML::SAX::Base); # this module is a SAX filter
Subroutine BEGIN: called CC=1 SCAR=0.0
483 5 ▶use Carp qw(croak); # make some noise
Subroutine BEGIN: called CC=1 SCAR=0.0
484 5 ▶use XML::SAX::Exception; # for real
Subroutine BEGIN: called CC=1 SCAR=0.0
485 5 ▶use XML::Filter::BufferText; # keep text together
Subroutine BEGIN: called CC=1 SCAR=0.0
486 5 ▶use XML::SAX::ParserFactory; # needed to parse the schema documents
Subroutine BEGIN: called CC=1 SCAR=0.0
487  
488 5 ▶use XML::Validator::Schema::Parser;
Subroutine BEGIN: called CC=1 SCAR=0.0
489 5 ▶use XML::Validator::Schema::ElementNode;
Subroutine BEGIN: called CC=1 SCAR=0.0
490 5 ▶use XML::Validator::Schema::ElementRefNode;
Subroutine BEGIN: called CC=1 SCAR=0.0
491 5 ▶use XML::Validator::Schema::RootNode;
Subroutine BEGIN: called CC=1 SCAR=0.0
492 5 ▶use XML::Validator::Schema::ComplexTypeNode;
Subroutine BEGIN: called CC=1 SCAR=0.0
493 5 ▶use XML::Validator::Schema::SimpleTypeNode;
Subroutine BEGIN: called CC=1 SCAR=0.0
494 5 ▶use XML::Validator::Schema::SimpleType;
Subroutine BEGIN: called CC=1 SCAR=0.0
495 5 ▶use XML::Validator::Schema::TypeLibrary;
Subroutine BEGIN: called CC=1 SCAR=0.0
496 5 ▶use XML::Validator::Schema::ElementLibrary;
Subroutine BEGIN: called CC=1 SCAR=0.0
497 5 ▶use XML::Validator::Schema::AttributeLibrary;
Subroutine BEGIN: called CC=1 SCAR=0.0
498 5 ▶use XML::Validator::Schema::ModelNode;
Subroutine BEGIN: called CC=1 SCAR=0.0
499 5 ▶use XML::Validator::Schema::Attribute;
Subroutine BEGIN: called CC=1 SCAR=0.0
500 5 ▶use XML::Validator::Schema::AttributeNode;
Subroutine BEGIN: called CC=1 SCAR=0.0
501  
502 5 ▶use XML::Validator::Schema::Util qw(_err);
Subroutine BEGIN: called CC=1 SCAR=0.0
503 5 our %CACHE;
504  
505 5 our $DEBUG = 0;
506  
507 # create a new validation filter
508 179 ▶sub new {
Subroutine new: called CC=9 SCAR=22.8
Pod undocumented
509 179 my $pkg = shift;
510 0 ▶ my $opt = (@_ == 1) ? { %{shift()} } : {@_};
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 ? : 0 179 179
511 179 my $self = bless $opt, $pkg;
512  
513 179 ▶ $self->{debug} = exists $self->{debug} ? $self->{debug} : $DEBUG;
Branch: 1 branch
BranchTrueFalseTotal
exists $self->{'debug'} ? : 0 179 179
514  
515 # check options
516 179 ▶ croak("Missing required 'file' option.") unless $self->{file};
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"file"} 0 179 179
517  
518 # if caching is on, check the cache
519 179 ▶ if ($self->{cache} and
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'cache'} and exists $XML::Validator::Schema::CACHE{$self->{'file'}} and $XML::Validator::Schema::CACHE{$self->{'file'}}{'mtime'} == (stat $self->{'file'})[9]) { } 127 52 179
Condition83%5/6
$self->{"cache"} and exists $XML::Validator::Schema::CACHE{$self->{"file"}} and $XML::Validator::Schema::CACHE{$self->{"file"}}{"mtime"} == (stat $self->{"file"})[9]
!ll&&!rl&&r
520127
$self->{"cache"} and exists $XML::Validator::Schema::CACHE{$self->{"file"}}
!ll&&!rl&&r
151127
MC/DC66%2/3
$self->{"cache"} and exists $XML::Validator::Schema::CACHE{$self->{"file"}} and $XML::Validator::Schema::CACHE{$self->{"file"}}{"mtime"} == (stat $self->{"file"})[9]
$self->{"cache"} exists $XML::Validator::Schema::CACHE{$self->{"file"}} $XML::Validator::Schema::CACHE{$self->{"file"}}{"mtime"} == (stat $self->{"file"})[9]
Truth table75%3/4
A and B and C
A= $self->{"cache"}B= exists $XML::Validator::Schema::CACHE{$self->{"file"}}C= $XML::Validator::Schema::CACHE{$self->{"file"}}{"mtime"} == (stat $self->{"file"})[9]
ABCresult
0XX0
10X0
1100
1111
520 exists $CACHE{$self->{file}} and
521 $CACHE{$self->{file}}{mtime} == (stat($self->{file}))[9]) {
522  
523 # load cached object
524 127 $self->{node_stack} = $CACHE{$self->{file}}{node_stack};
525  
526 # might have nodes on it leftover from failed validation,
527 # truncate to root
528 127 $#{$self->{node_stack}} = 0;
529  
530 # clean up any lingering state from the last use of this tree
531 $self->{node_stack}[0]->walk_down(
532 127 ▶ { callback => sub { shift->clear_memory; 1; } });
Subroutine __ANON__: called CC=1 SCAR=0.0
533  
534 } else {
535 # create an empty element stack
536 52 $self->{node_stack} = [];
537  
538 # load the schema, filling in the element tree
539 52 $self->parse_schema();
540  
541 # store to cache
542 38 ▶ if ($self->{cache}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"cache"}) 38 0 38
543 38 $CACHE{$self->{file}}{mtime} = (stat($self->{file}))[9];
544 38 $CACHE{$self->{file}}{node_stack} = $self->{node_stack};
545 }
546 }
547  
548 # buffer text for convenience
549 165 my $bf = XML::Filter::BufferText->new( Handler => $self );
550  
551 # add line-numbers and column-numbers to errors if
552 # XML::Filter::ExceptionLocator is available
553 165 eval { require XML::Filter::ExceptionLocator; };
554 165 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) { } 165 0 165
555 # no luck, just return the buffer-text handler
556 165 return $bf;
557 } else {
558 # create a new exception-locator and return it
559 0 my $el = XML::Filter::ExceptionLocator->new( Handler => $bf );
560 0 return $el;
561 }
562 }
563  
564 # parse an XML schema document, filling $self->{node_stack}
565 52 ▶sub parse_schema {
Subroutine parse_schema: called CC=3 SCAR=11.1
Pod undocumented
566 52 my $self = shift;
567  
568 _err("Specified schema file '$self->{file}' does not exist.")
569 52 ▶ unless -e $self->{file};
Branch: 1 branch
BranchTrueFalseTotal
unless -e $self->{"file"} 1 51 52
570
571 # initialize the schema parser
572 51 my $parser = XML::Validator::Schema::Parser->new(schema => $self);
573  
574 # add line-numbers and column-numbers to errors if
575 # XML::Filter::ExceptionLocator is available
576 51 eval { require XML::Filter::ExceptionLocator; };
577 51 ▶ unless ($@) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($@) 0 51 51
578 # create a new exception-locator and set it up above the parser
579 0 $parser = XML::Filter::ExceptionLocator->new( Handler => $parser );
580 }
581  
582 # parse the schema file
583 51 $parser = XML::SAX::ParserFactory->parser(Handler => $parser);
584 51 $parser->parse_uri($self->{file});
585 }
586  
587 # check element start
588 566 ▶sub start_element {
Subroutine start_element: called CC=4 SCAR=15.7
Pod documented
589 566 my ($self, $data) = @_;
590 566 my $name = $data->{LocalName};
591 566 my $node_stack = $self->{node_stack};
592 566 my $element = $node_stack->[-1];
593  
594 0 print STDERR " " x scalar(@{$node_stack}), " o ", $name, "\n"
595 566 ▶ if $self->{debug};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"debug"} 0 566 566
596  
597 # check that this alright
598 566 my $daughter = $element->check_daughter($name);
599  
600 # check attributes
601 545 $daughter->check_attributes($data->{Attributes});
602
603 534 ▶ if ($self->{debug}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"debug"}) 0 534 534
604 0 foreach my $att ( keys %{ $data->{Attributes} } ) {
605 0 print STDERR " " x (scalar(@{$node_stack}) + 2), " - ",
606 $data->{Attributes}->{$att}->{Name}, " = ",
607 0 $data->{Attributes}->{$att}->{Value}, "\n"
608 }
609 }
610  
611 # enter daughter node
612 534 push(@$node_stack, $daughter);
613  
614 534 $self->SUPER::start_element($data);
615 }
616  
617 # check character content
618 691 ▶sub characters {
Subroutine characters: called CC=1 SCAR=0.0
Pod documented
619 691 my ($self, $data) = @_;
620 691 my $element = $self->{node_stack}[-1];
621 691 $element->check_contents($data->{Data});
622 667 $element->{checked_content} = 1;
623  
624 667 $self->SUPER::characters($data);
625 }
626  
627 # finish element checking
628 472 ▶sub end_element {
Subroutine end_element: called CC=4 SCAR=13.9
Pod documented
629 472 my ($self, $data) = @_;
630 472 my $node_stack = $self->{node_stack};
631 472 my $element = $node_stack->[-1];
632  
633 # check empty content if haven't checked yet
634 $element->check_contents('')
635 472 ▶ unless $element->{checked_content};
Branch: 1 branch
BranchTrueFalseTotal
unless $element->{"checked_content"} 204 268 472
636 469 $element->{checked_content} = 0;
637  
638 # final model check
639 $element->{model}->check_final_model($data->{LocalName},
640 $element->{memory} || [])
641 469 ▶ if $element->{model};
Branch: 1 branch
BranchTrueFalseTotal
if $element->{"model"} 119 350 469
Condition100%2/2
$element->{'memory'} || []
l!l
1163
MC/DC100%1/1
$element->{'memory'} || []
$element->{'memory'}
Truth table100%2/2
A
A= $element->{'memory'}
Aresult
11
00
642  
643 # done
644 458 $element->clear_memory();
645 458 pop(@$node_stack);
646  
647 458 $self->SUPER::end_element($data);
648 }
649  
650 5 1;
« Schema/Library.pm ↑ Summary Schema/Util.pm »