File Coverage

blib/lib/XML/Toolkit.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             package XML::Toolkit;
2             {
3             $XML::Toolkit::VERSION = '0.15';
4             }
5 2     2   15198 use strict;
  2         5  
  2         83  
6 2     2   14 use XML::Toolkit::MetaDescription::Trait;
  2         6  
  2         78  
7              
8             1; # Magic true value required at end of module
9             __END__
10              
11             =head1 NAME
12              
13             XML::Toolkit - A suit of XML tools with Antlers.
14              
15             =head1 VERSION
16              
17             version 0.15
18              
19             =head1 SYNOPSIS
20              
21             use XML::Toolkit::App;
22             my $loader = XML::Toolkit::App->new( xmlns => { '' => 'MyApp' } )->loader;
23             $loader->parse_file( $file );
24             print join '', @{ $loader->render };
25              
26             or
27              
28             use XML::Toolkit::App;
29             my $builder = XML::Toolkit::App->new( xmlns => { '' => 'MyApp' } )->builder
30             $builder->parse_string($xml)
31             say $builder->render()
32              
33             Typically you would use the C<xmltk> command line script.
34              
35             xmltk generate --input mydocument.xml --xmlns ''=MyApp
36            
37             =head1 DESCRIPTION
38              
39             XML::Toolkit is a suite of tools that work to make handling XML easier.
40             It is designed to marshall XML documents into Moose classes and back
41             again with minimal changes.
42              
43             For example given a xml document like the following
44              
45             <?xml version="1.0"?>
46             <note>
47             <to>Tove</to>
48             <from>Jani</from>
49             <heading>Reminder</heading>
50             <body>Don't forget me this weekend!</body>
51             </note>
52              
53             C<XML::Toolkit> will generate classes for each of the elements. The
54             C< <note> > element's class would be something like
55              
56             package MyApp::Note;
57             use Moose;
58             use namespace::autoclean;
59             use XML::Toolkit;
60            
61             has 'to_collection' => (
62             isa => 'ArrayRef[MyApp::To]',
63             is => 'ro',
64             init_arg => 'tos',
65             traits => [qw(XML Array)],
66             lazy => 1,
67             auto_deref => 1,
68             default => sub { [] },
69             handles => { add_to => ['push'] }, description => {
70             Prefix => "",
71             LocalName => "to",
72             node_type => "child",
73             Name => "to",
74             NamespaceURI => "",
75             sort_order => 0,
76             },
77             );
78            
79             has 'from_collection' => (
80             isa => 'ArrayRef[MyApp::From]',
81             is => 'ro',
82             init_arg => 'froms',
83             traits => [qw(XML Array)],
84             lazy => 1,
85             auto_deref => 1,
86             default => sub { [] },
87             handles => { add_from => ['push'] }, description => {
88             Prefix => "",
89             LocalName => "from",
90             node_type => "child",
91             Name => "from",
92             NamespaceURI => "",
93             sort_order => 1,
94             },
95             );
96            
97             has 'body_collection' => (
98             isa => 'ArrayRef[MyApp::Body]',
99             is => 'ro',
100             init_arg => 'bodys',
101             traits => [qw(XML Array)],
102             lazy => 1,
103             auto_deref => 1,
104             default => sub { [] },
105             handles => { add_body => ['push'] }, description => {
106             Prefix => "",
107             LocalName => "body",
108             node_type => "child",
109             Name => "body",
110             NamespaceURI => "",
111             sort_order => 2,
112             },
113             );
114            
115             has 'heading_collection' => (
116             isa => 'ArrayRef[MyApp::Heading]',
117             is => 'ro',
118             init_arg => 'headings',
119             traits => [qw(XML Array)],
120             lazy => 1,
121             auto_deref => 1,
122             default => sub { [] },
123             handles => { add_heading => ['push'] }, description => {
124             Prefix => "",
125             LocalName => "heading",
126             node_type => "child",
127             Name => "heading",
128             NamespaceURI => "",
129             sort_order => 3,
130             },
131             );
132            
133             1;
134             __END__
135              
136             You can then use the set of classes to load the original document, or
137             create new documents that match this structure.
138              
139             my $document = MyApp::Note->new(
140             to_collection => [MyApp::To->new(text => 'Bob')],
141             from_collection => [MyApp::From->new(text => 'Alice')],
142             headings => [MyApp::Heading->new(text => 'Secret' )],
143             body_collection => [MyApp::Body->new(text=>'Shh!')],
144             )
145            
146             my $generator = XMLTK::App->new( xmlns => { '' => '' } )->generator;
147             $generator->render_object($root);
148             my $output = join( '', $generator->output );
149            
150             # output
151             #
152             # <note>
153             # <to>Bob</to>
154             # <from>Alice</from>
155             # <heading>Secret</heading>
156             # <body>Shhh!</body>
157             # </note>
158              
159             The original intention of XML::Toolkit was to round-trip XML documents
160             with an unkonwn schema through an editor and back out to disk with very
161             few semantic or structural changes.
162              
163             =head1 SEE ALSO
164              
165             L<PRANG|PRANG>, L<XML::Compile|XML::Compile> and L<XML::Pastor|XML::Pastor>
166             have similarities to C<XML::Toolkit> in scope if not design.
167              
168             =head1 DEPENDENCIES
169              
170             L<Devel::PackagePath|Devel::PackagePath>, L< Moose | Moose >,
171             L<MooseX::MetaDescription|MooseX::MetaDescription>,
172             L<MooseX::Types::Path::Class|MooseX::Types::Path::Class>,
173             L<MooseX::App::Cmd|MooseX::App::Cmd>, L<Template::Toolkit|Template::Toolkit>,
174             L<XML::SAX|XML::SAX>, L<XML::SAX::Writer|XML::SAX::Writer>,
175             L<Bread::Board|Bread::Board> and L<namespace::autoclean|namespace::autoclean>
176              
177             =head1 INCOMPATIBILITIES
178              
179             None reported.
180              
181             =head1 BUGS AND LIMITATIONS
182              
183             Currently XML::Toolkit only supports Auto-Discovery of class hierarchy from
184             XML instances, and does not know anything about DTDs, RelaxNG, XML-Schema or
185             anything else. Future work is being considered in this, and patches may be
186             accepted if they come with documentation and tests.
187              
188             Please report any bugs or feature requests to C<bug-xml-toolkit@rt.cpan.org>,
189             or through the web interface at L<http://rt.cpan.org>. Additional support may
190             be available via C<#xml-toolkit> on C<irc.perl.org>.
191              
192             =head1 AUTHORS
193              
194             Chris Prather C<< <chris@prather.org> >>
195             Robin Smidsrød C<< <robin@smidsrod.no> >>
196             Jesse Luehrs C<< <doy@cpan.org> >>
197              
198             =head1 LICENCE AND COPYRIGHT
199              
200             Copyright (c) 2008-2010, Chris Prather C<< <chris@prather.org> >>. Some
201             rights reserved.
202              
203             This module is free software; you can redistribute it and/or
204             modify it under the same terms as Perl itself. See L<perlartistic>.
205              
206             =head1 DISCLAIMER OF WARRANTY
207              
208             BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
209             FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
210             OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
211             PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
212             EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
213             WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
214             ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
215             YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
216             NECESSARY SERVICING, REPAIR, OR CORRECTION.
217              
218             IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
219             WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
220             REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
221             LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
222             OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
223             THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
224             RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
225             FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
226             SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
227             SUCH DAMAGES.