When skipping a test due to a rule, note this with the proper logging
[irspy-moved-to-github.git] / lib / ZOOM / XML / Simple.pm
1
2 package ZOOM::XML::Simple;
3
4 use 5.008;
5 use strict;
6 use warnings;
7
8 use XML::LibXML;
9
10
11 =head1 NAME
12
13 ZOOM::XML::Simple - read XML files into memory and play them out again
14
15 =head1 SYNOPSIS
16
17  $doc = ZOOM::XML::Simple::XMLin("foo.xml");
18  $doc->[0]->{beenRead} = 1;
19  print ZOOM::XML::Simple::XMLout($doc);
20
21 =head1 DESCRIPTION
22
23 Ever used the C<XML::Simple> module?  That's what I wanted.  Read its
24 manual for details, but basically it lets you read a document into a
25 nice, simple in-memory format, fiddle with it to your heart's content,
26 then render it back out again.  This is nice because the in-memory
27 format is so very much simpler than a DOM tree.
28
29 Unfortunately, it turns out that C<XML::Simple> messes with your data
30 too much to be used if your XML needs to conform to a fixed pattern,
31 such as a DTD or XML Schema.  Some of its damage can be prevented by
32 passing a hatful of attributes to its C<XMLin()> and C<XMLout()>
33 methods, but I've not found any way to prevent it from reordering the
34 subelements of each element into alphabetical order, which is of
35 course completely unacceptable in many cases.
36
37 For the IRSpy project's C<ZOOM::IRSpy::Record> module, I need
38 something like C<XML::Simple> to handle the ZeeRex records -- but it
39 has to keep elements in their original order.  Hence this module.
40 Because of its ordering requirement, it has to make a different
41 data-structure from the original.  It also implements only a tiny
42 subset of the full C<XML::Simple> functionality - the parts that I
43 need, natch.
44
45 =cut
46
47 # But will what I make actually be all that much simpler than DOM?
48 #
49 # For now, this effort is abandoned, and I am using DOM directly.
50
51 #use XML::Simple qw(:strict);
52 #my %attr = (KeyAttr => [], KeepRoot => 1);
53 #my $config = XMLin("foo.xml", %attr, ForceArray => 1, ForceContent => 1);
54 #print XMLout($config, %attr);
55
56
57 =head1 SEE ALSO
58
59 XML::Simple - the module that I hoped I'd be able to use, but wasn't
60 able to, hence my having had to write this one.
61
62 ZOOM::IRSpy::Record - the module I was writing that I wanted to use
63 XML::Simple for, and found that it wouldn't do.
64
65 The ZeeRex XML format is described at
66 http://explain.z3950.org/
67
68 =head1 AUTHOR
69
70 Mike Taylor, E<lt>mike@indexdata.comE<gt>
71
72 =head1 COPYRIGHT AND LICENSE
73
74 Copyright (C) 2006 by Index Data ApS.
75
76 This library is free software; you can redistribute it and/or modify
77 it under the same terms as Perl itself, either Perl version 5.8.7 or,
78 at your option, any later version of Perl 5 you may have available.
79
80 =cut
81
82 1;