File Coverage

blib/lib/PRANG.pm
Criterion Covered Total %
statement 6 6 100.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 8 8 100.0


line stmt bran cond sub pod time code
1              
2             package PRANG;
3             $PRANG::VERSION = '0.20';
4 7     7   16770 use strict;
  7         14  
  7         170  
5 7     7   28 use warnings;
  7         13  
  7         229  
6              
7             our $EMIT_CDATA = 0;
8              
9             1;
10              
11             __END__
12              
13             =encoding utf8
14              
15             =head1 NAME
16              
17             PRANG - XML graph engine - XML to Moose objects and back!
18              
19             =head1 SYNOPSIS
20              
21             # step 1. define a common role for nodes in your XML language
22             package XML::Language::Node;
23             use Moose::Role;
24             sub xmlns { "http://example.com/language/1.0" }
25              
26             # step 2. define the root node(s) of your language
27             package XML::Language;
28             use Moose;
29             use PRANG::Graph;
30             sub root_element {
31             "envy"
32             };
33             has_attr 'laziness' =>
34             is => "ro",
35             isa => "Str",
36             ;
37             has_element 'lust' =>
38             is => "ro",
39             isa => "XML::Language::Lust",
40             ;
41             with 'PRANG::Graph', 'XML::Language::Node';
42              
43             # step 3. define further elements in your schema
44             package XML::Language::Lust;
45             use Moose;
46             use PRANG::Graph;
47             use PRANG::XMLSchema::Types;
48              
49             has_attr 'gluttony' =>
50             is => "ro",
51             isa => "PRANG::XMLSchema::byte",
52             ;
53             has_element 'sins' =>
54             is => "ro",
55             isa => "ArrayRef[XML::Language::Lust|Str]",
56             xml_nodeName => {
57             'lust' => 'XML::Language::Lust',
58             'anger' => 'Str',
59             },
60             ;
61             has_element 'greed' =>
62             is => "ro",
63             isa => "Bool",
64             ;
65             with 'XML::Language::Node';
66              
67             # step 4a. parse!
68             my $object = XML::Language->parse(<<XML);
69             <envy laziness="Very">
70             <lust gluttony="127">
71             <anger>You wouldn't like me when I'm angry</anger>
72             <lust>
73             <anger>You've done it now!</anger>
74             <greed />
75             </lust>
76             </lust>
77             </envy>
78             XML
79              
80             # Parsing the above would give you the same structure as this:
81             XML::Language->new(
82             laziness => "Very",
83             lust => XML::Language::Lust->new(
84             gluttony => 127,
85             sins => [
86             "You wouldn't like me when I'm angry",
87             XML::Language::Lust->new(
88             sins => [ "You've done it now!" ],
89             greed => 1,
90             ),
91             ],
92             )
93             );
94              
95             # step 4b. emit!
96             $format = 1;
97             print $object->to_xml($format);
98              
99             =head1 DESCRIPTION
100              
101             PRANG is an B<XML Graph> engine, which provides B<post-schema
102             validation objects> (PSVO).
103              
104             It is designed for implementing XML languages for which a description
105             of the valid sets of XML documents is available - for example, a DTD,
106             W3C XML Schema or Relax specification. With PRANG (and, like
107             L<XML::Toolkit>), your class structure I<is> your XML Graph.
108              
109             XML namespaces are supported, and the module tries to make many XML
110             conventions as convenient as possible in the generated classes. This
111             includes XML data (elements with no attributes and textnode contents),
112             and presence elements (empty elements with no attributes which
113             indicate something). It also supports mixed and unprocessed portions
114             of the XML, and "pluggable" specifications.
115              
116             Currently, these must be manually constructed as in the example -
117             details on this are to be found on the L<PRANG::Graph::Meta::Element>
118             and L<PRANG::Graph::Meta::Attr> perldoc. There is also a cookbook of
119             examples - see L<PRANG::Cookbook>.
120              
121             However, eventually it should be possible to automatically process
122             schema documents to produce a class structure (see L</KNOWN
123             LIMITATIONS>).
124              
125             Once the L<PRANG::Graph> has been built, you can:
126              
127             =over
128              
129             =item B<marshall XML in>
130              
131             The L<PRANG::Marshaller> takes any well-formed document parsable by
132             L<XML::LibXML>, and constructs a corresponding set of Moose objects.
133              
134             A shortcut is available via the C<parse> method on the starting point
135             of the graph (indicated by using the role 'L<PRANG::Graph>').
136              
137             You can also parse documents which have multiple start nodes, by
138             defining a role which the concrete instances use.
139              
140             eg, for the example in the SYNOPSIS; define a role
141             'XML::Language::Family' - the root node will be parsed by the class
142             with a matching C<root_element> (and C<xmlns>) value.
143              
144             package XML::Language::Family;
145             use Moose::Role;
146             with 'PRANG::Graph';
147              
148             package XML::Language;
149             use Moose;
150             with 'XML::Language::Family';
151              
152             # later ...
153             my $marshaller = PRANG::Marshaller->get("XML::Language::Family");
154             my $object = $marshaller->parse($xml);
155              
156             B<note> the C<PRANG::Marshaller> API will probably go away in a future
157             release, once the "parse" role method is made to work correctly.
158              
159             =item B<marshall XML out>
160              
161             A L<PRANG::Graph> structure also has a C<to_xml> method, which emits
162             XML (optionally indented).
163              
164             =back
165              
166             =head1 Global Options
167              
168             There are some (well, one at the moment) global options which can be
169             set via:
170              
171             $PRANG::OPTION = 'value';
172              
173             =item B<EMIT_CDATA>
174              
175             Setting this to true will emit all text nodes as CDATA elements rather
176             than just text. Default is false.
177              
178             Note, for parsing, CDATA and text are treated as the same.
179              
180             =back
181              
182             =head1 Why "XML Graph"?
183              
184             The term B<XML Graph> is from the paper, "XML Graphs in Program
185             Analysis", Møller and Schwartzbach (2007).
186              
187             L<http://www.brics.dk/~amoeller/papers/xmlgraphs/>
188              
189             The difference between an B<Graph> and a B<Tree>, is that a Graph can
190             contain cycles, whereas a Tree cannot - there is only one correct way
191             to follow a tree, whereas there can be many correct ways to follow a
192             graph.
193              
194             So, XML documents are considered to be trees, and the mechanisms which
195             describe allowable forms for those trees XML graphs.
196              
197             They are graphs, because they can contain cycles - cycles in an XML
198             graph might point back to the same element (indicating an "any number
199             of this element" condition), or point to a different element closer to
200             the initial element (indicating an arbitrary level of nesting).
201              
202             =head1 KNOWN LIMITATIONS
203              
204             Support for these features will be considered as tuits allow. If you
205             can create a patch for any of these features which meets the coding
206             standards, they are very likely to be accepted. The authors will
207             provide guidance and/or assistance through this process, time and
208             patience permitting.
209              
210             =head2 Creating XML Graphs from Schema documents
211              
212             Validating/Parsing schema documents, and transforming those
213             to a L<PRANG::Graph> structure, could well be a valid approach to
214             address these issues and may be addressed by later releases and/or
215             modules which implement those XML languages using PRANG.
216              
217             =head2 Creating XML Graphs from example documents
218              
219             This is a bit more shonky an approach, but can be very useful for
220             I<ad-hoc> XML conventions for which no rigid definition can be found.
221             Currently, L<XML::Toolkit> is the best module for this.
222              
223             =head2 Validating Indeterminate Graphs
224              
225             It's possible that at a given point in time, a graph may be followed
226             in more than one direction, and the correct direction cannot be
227             determined based on the currently input token. However, few if any
228             XML languages are this indeterminate, so while many schema languages
229             may allow this to be specified, they should (hopefully) not correspond
230             to major standards.
231              
232             =head1 SOURCE, SUBMISSIONS, SUPPORT
233              
234             Source code is available from Catalyst:
235              
236             git://git.catalyst.net.nz/PRANG.git
237              
238             And Github:
239              
240             git://github.com/catalyst/PRANG.git
241              
242             Please see the file F<SubmittingPatches> for information on preferred
243             submission format.
244              
245             Suggested avenues for support:
246              
247             =over
248              
249             =item *
250              
251             Moose user's mailing list - see the L<Moose> perldoc for more
252             information. Please check with the latest release of PRANG - if there
253             is sufficient interest, a separate list may have been created.
254              
255             =item *
256              
257             Contact the author and ask either politely or commercially for help.
258              
259             =item *
260              
261             Log a ticket on L<http://rt.cpan.org/>
262              
263             =back
264              
265             =head1 AUTHOR AND LICENCE
266              
267             Development commissioned by NZ Registry Services, and carried out by
268             Catalyst IT - L<http://www.catalyst.net.nz/>
269              
270             Copyright 2009, 2010, NZ Registry Services. This module is licensed
271             under the Artistic License v2.0, which permits relicensing under other
272             Free Software licenses.
273              
274             =cut