Generator/Essex.pm

filter: Statementstmt 90.2% 74 / 82 Branchbran 65.6% 21 / 32 Conditioncond 47.8% 11 / 23 MC/DCmcdc 21.4% 3 / 14 Subroutinesub 90.4% 19 / 21 Podpod 100% 12 / 12 totaltotal 76.0% 140 / 184 CC 26 SCAR 19.9
CC
26
Cov
77%
put
12.7
get_handler
12.0
finish
12.0
CRAP 7.3
« Handler/Essex.pm ↑ Summary Essex/Constants.pm »
1 package XML::Generator::Essex;
2  
3 7 $VERSION = 0.000_1;
4  
5 =head1 NAME
6  
7 XML::Generator::Essex - Generate XML with Essex
8  
9 =head1 SYNOPSIS
10  
11 package My::Generator;
12  
13 use XML::Generator::Essex;
14 @ISA = qw( XML::Generator::Essex );
15  
16 use strict;
17  
18 sub main { # Called by XML::Generator::Essex->generate().
19 my $self = shift;
20 }
21  
22 ## And, to use:
23  
24 my $g = MY::Generator->new( Handler => $h );
25 $g->generate( ... );
26  
27 =head1 DESCRIPTION
28  
29 Provides Essex output primitives like C<put()> and constructors for
30 essex events.
31  
32 =for test_script XML-Filter-Essex.t
33  
34 =cut
35  
36 7 ▶use XML::Essex::Constants qw( EOD );
Subroutine BEGIN: called CC=1 SCAR=0.0
37  
38 7 ▶use XML::Essex::Base (); # Don't import things.
Subroutine BEGIN: called CC=1 SCAR=0.0
39 7 ▶use XML::Essex::Model ();
Subroutine BEGIN: called CC=1 SCAR=0.0
40 7 ▶use XML::SAX::Base ();
Subroutine BEGIN: called CC=1 SCAR=0.0
41  
42 7 ▶no warnings "once";
Subroutine BEGIN: called CC=1 SCAR=0.0
43  
44 7 @ISA = qw( XML::Essex::Base XML::SAX::Base );
45  
46 ## This is duplicated in XML::Essex
47 7 @event_ctors = qw(
48 characters
49 chars
50 end_document
51 end_doc
52 end_element
53 end_elt
54 end
55 start_document
56 start_doc
57 start_element
58 start_elt
59 start
60 xml_decl
61 );
62  
63 7 @EXPORT = (
64 qw(
65 get_handler
66 output_monitor
67 set_handler
68  
69 put
70 ),
71 @event_ctors,
72 );
73  
74 7 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
75 7 ▶use NEXT;
Subroutine BEGIN: called CC=1 SCAR=0.0
76 7 ▶use XML::Essex::Filter::OutputMonitor;
Subroutine BEGIN: called CC=1 SCAR=0.0
77  
78 34 ▶sub _init { ## Called by new()
Subroutine _init: called CC=1 SCAR=0.0
79 34 my $self = shift;
80  
81 34 $self->SUPER::set_handler(
82 XML::Essex::Filter::OutputMonitor->new(
83 Handler => $self->SUPER::get_handler
84 )
85 );
86  
87 34 $self->NEXT::_init( @_ );
88 }
89  
90  
91 43 ▶sub reset { ## Called by execute()
Subroutine reset: called CC=1 SCAR=0.0
Pod documented
92 43 my $self = shift;
93 43 $self->output_monitor->reset;
94 43 $self->NEXT::reset( @_ );
95 }
96  
97  
98 43 ▶sub finish { ## Called by execute()
Subroutine finish: called CC=9 SCAR=24.8
Pod documented
99 43 my $self = shift;
100 43 my ( $ok, $x ) = @_;
101  
102 43 my $om = $self->output_monitor;
103  
104 43 ▶ unless ( $ok ) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ok) 7 36 43
105 7 ▶ if ( $x eq EOD . "\n" ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($x eq "end of XML document\n") 7 0 7
106 7 ▶ return ( 1, $om->end_document_result )
Branch: 1 branch
BranchTrueFalseTotal
if $om->end_document_result_has_been_set 7 0 7
107 if $om->end_document_result_has_been_set;
108  
109 0 ▶ return ( 1, undef )
Branch: 1 branch
BranchTrueFalseTotal
unless $om->start_document_seen 0 0 0
110 unless $om->start_document_seen;
111  
112 0 my $eod = EOD;
113 0 $x =~ s/^$eod/$eod and no result set by $self/o;
114 }
115 0 die $x;
116 }
117  
118 36 $self->output_monitor->finish;
119  
120 36 ▶ die "incomplete document emitted by $self\n"
Branch: 1 branch
BranchTrueFalseTotal
if $om->start_document_seen and not $om->end_document_seen 0 36 36
Condition66%2/3
$om->start_document_seen and not $om->end_document_seen
!ll&&!rl&&r
5310
MC/DC0%0/2
$om->start_document_seen and not $om->end_document_seen
$om->start_document_seen not $om->end_document_seen
Truth table66%2/3
A and not(B)
A= $om->start_document_seenB= not $om->end_document_seen
ABresult
0X0
100
111
121 if $om->start_document_seen && ! $om->end_document_seen;
122  
123 36 $self->NEXT::finish( @_ );
124 36 ▶ return ( 1, $om->end_document_result )
Branch: 1 branch
BranchTrueFalseTotal
if $om->end_document_result_has_been_set 31 5 36
125 if $om->end_document_result_has_been_set;
126  
127 5 ▶ die "no result set by $self\n"
Branch: 1 branch
BranchTrueFalseTotal
if $om->start_document_seen 0 5 5
128 if $om->start_document_seen;
129  
130 5 return ();
131 }
132  
133  
134 =head2 Methods
135  
136 =over
137  
138 =item put
139  
140 Example What's emitted
141 ======= ==============
142 put; ## (whatever's in $_: event, characters, etc)
143 put "text<"; ## text&lt;
144 put [ a => "foo" ] ## <a>foo</a>
145 put comment "foo"; ## <!--foo-->
146 put $event; ## an event (see constructors below)
147 put $data; ## Emit a data structure
148 put @list; ## Emit multiple events and / or data structures
149  
150 Emits one or more data structures as XML. Returns the result of
151 emitting the last event (ie the result from the next SAX processor).
152  
153 Most of the things you can pass to put (strings, constructed events) are
154 relatively self evident.
155  
156 For instance, you can pass any events you construct, so an Essex script
157 to make sure all character data is emitted in CDATA sections might look
158 like:
159  
160 get( "text()" ), put cdata $_ while 1;
161  
162 A less obvious feature is that you can pass a (possibly nested) Perl
163 ARRAY that defines an XML tree to emit:
164  
165 put [
166 root => { id => 1 }, ## HASHes contain attributes
167 "root content",
168 [ a => "a content" ],
169 "more root content",
170 [ b => { id => 2 }, "b content" ],
171 ];
172  
173 will emit the SAX events corresponding to the XML (whitespace added for
174 legibility):
175  
176 <root id="1">
177 root content
178 <a>a content</a>
179 more root content
180 <b id="2">b content</b>
181 </root>
182  
183 NOTE: this does not allow you to control attribute order.
184  
185 By using the DOM constructors, you could also write the above as:
186  
187 put elt(
188 root => { id => 1 }, ## HASHes contain attributes
189 "root content",
190 elt( a => "a content" ),
191 "more root content",
192 elt( b => { id => 2 }, "b content" ),
193 ];
194  
195 to emit the XML C<< <root id="1"><!--comment-->content</root> >>.
196  
197 You can actually pass any blessed object to C<put()> that provides a
198 C<generate_SAX()> method. This will be called with the results of
199 $self->get_handler() (which may be undefined) and should return
200 a TRUE if the handler is undefined or if no events are sent. If any
201 events are sent, it should return the result of the last event.
202  
203 See XML::Essex::Model for some more examples.
204  
205 C<put()> is a bit DWIMy: it will fill in the name of end_elements for
206 you if you leave them out:
207  
208 put start "foo";
209 ...
210 put end;
211  
212 It will also C<die()> if you emit the wrong end_elt for the currently
213 open element (it keeps a stack), or if you emit and end_document
214 without emitting end_elements. You can catch this error and C<put()> the
215 proper end_element events if you like.
216  
217 If the filter exits after half-emitting a document and does not
218 set a result, an error is emitted. This is to notify you that a
219 document was half-emitted. die() to get around this.
220  
221 Note that downstream filters are free to cache things you send, so don't
222 modify events once they're sent. If you need to do that, send a copy
223 and modify the original.
224  
225 =cut
226  
227 110 ▶sub put {
Subroutine put: called CC=12 SCAR=25.4
Pod documented
228 110 ▶ my $self = @_ && UNIVERSAL::isa( $_[0], __PACKAGE__ )
Branch: 1 branch
BranchTrueFalseTotal
@_ && UNIVERSAL::isa($_[0], __PACKAGE__) ? : 29 81 110
Condition100%3/3
@_ and UNIVERSAL::isa($_[0], __PACKAGE__)
!ll&&!rl&&r
305129
MC/DC100%2/2
@_ and UNIVERSAL::isa($_[0], __PACKAGE__)
@_ UNIVERSAL::isa($_[0], __PACKAGE__)
Truth table100%3/3
A and B
A= @_B= UNIVERSAL::isa($_[0], __PACKAGE__)
ABresult
0X0
100
111
229 ? shift
230 : $XML::Essex::Base::self;
231  
232 110 my $om = $self->output_monitor;
233  
234 110 ▶ if ( ! $om->get_handler
Branch: 1 branch
BranchTrueFalseTotal
if (not $om->get_handler or $om->get_handler->isa("XML::SAX::Base::NoHandler") and $self->{"Writer"}) 2 108 110
Condition66%4/6
not $om->get_handler or $om->get_handler->isa("XML::SAX::Base::NoHandler") and $self->{"Writer"}
l!l&&r!l&&!r
02108
$om->get_handler->isa("XML::SAX::Base::NoHandler") and $self->{"Writer"}
!ll&&!rl&&r
10802
MC/DC33%1/3
not $om->get_handler or $om->get_handler->isa("XML::SAX::Base::NoHandler") and $self->{"Writer"}
not $om->get_handler $om->get_handler->isa("XML::SAX::Base::NoHandler") $self->{"Writer"}
Truth table50%2/4
not(A) or B and C
A= not $om->get_handlerB= $om->get_handler->isa("XML::SAX::Base::NoHandler")C= $self->{"Writer"}
ABCresult
1XX1
0111
00X0
0100
235 || $om->get_handler->isa( "XML::SAX::Base::NoHandler" )
236 && $self->{Writer}
237 ) {
238 2 $om->set_handler( $self->{Writer}->() );
239 }
240
241 110 my $r;
242 110 ▶ for ( @_ ? @_ : $_ ) {
Branch: 1 branch
BranchTrueFalseTotal
@_ ? : 80 30 110
243 253 ▶ if ( ! ref $_ ) {
Branch: 3 branches
BranchTrueFalseTotal
if (not ref $_) { } 16 237 253
elsif (UNIVERSAL::can($_, 'generate_SAX')) { } 234 3 237
elsif (ref $_ eq 'ARRAY') { } 3 0 3
244 16 $r = $om->characters( { Data => $_ } );
245 }
246 elsif ( UNIVERSAL::can( $_, "generate_SAX" ) ) {
247 234 $r = $_->generate_SAX( $om );
248 }
249 elsif ( ref $_ eq "ARRAY" ) {
250 3 $r = XML::Essex::Event::element->new( @$_ )->generate_SAX( $om );
251 }
252 else {
253 0 ▶ Carp::croak "Unable to put() ", ref $_ || "'$_'";
Condition0%0/2
ref $_ || "'${_}'"
l!l
00
MC/DC0%0/1
ref $_ || "'${_}'"
ref $_
Truth table0%0/2
A
A= ref $_
Aresult
11
00
254 }
255 }
256  
257 110 return $r;
258 }
259  
260 =item output_monitor
261  
262 Returns a handle to the output monitor. See
263 L<XML::Essex::Filter::OutputMonitor> for details.
264  
265 =cut
266  
267 28 ▶sub set_handler {
Subroutine set_handler: called CC=3 SCAR=13.1
Pod documented
268 28 ▶ my $self = @_ && UNIVERSAL::isa( $_[0], __PACKAGE__ )
Branch: 1 branch
BranchTrueFalseTotal
@_ && UNIVERSAL::isa($_[0], __PACKAGE__) ? : 28 0 28
Condition33%1/3
@_ and UNIVERSAL::isa($_[0], __PACKAGE__)
!ll&&!rl&&r
0028
MC/DC0%0/2
@_ and UNIVERSAL::isa($_[0], __PACKAGE__)
@_ UNIVERSAL::isa($_[0], __PACKAGE__)
Truth table33%1/3
A and B
A= @_B= UNIVERSAL::isa($_[0], __PACKAGE__)
ABresult
0X0
100
111
269 ? shift
270 : $XML::Essex::Base::self;
271 28 $self->output_monitor->set_handler( @_ );
272 }
273  
274 0 ▶sub get_handler {
Subroutine get_handler: not called CC=3 SCAR=24.8
Pod documented
275 0 ▶ my $self = @_ && UNIVERSAL::isa( $_[0], __PACKAGE__ )
Branch: 1 branch
BranchTrueFalseTotal
@_ && UNIVERSAL::isa($_[0], __PACKAGE__) ? : 0 0 0
Condition0%0/3
@_ and UNIVERSAL::isa($_[0], __PACKAGE__)
!ll&&!rl&&r
000
MC/DC0%0/2
@_ and UNIVERSAL::isa($_[0], __PACKAGE__)
@_ UNIVERSAL::isa($_[0], __PACKAGE__)
Truth table0%0/3
A and B
A= @_B= UNIVERSAL::isa($_[0], __PACKAGE__)
ABresult
0X0
100
111
276 ? shift
277 : $XML::Essex::Base::self;
278 0 $self->output_monitor->get_handler( @_ );
279 }
280  
281 260 ▶sub output_monitor {
Subroutine output_monitor: called CC=3 SCAR=13.1
Pod documented
282 260 ▶ my $self = @_ && UNIVERSAL::isa( $_[0], __PACKAGE__ )
Branch: 1 branch
BranchTrueFalseTotal
@_ && UNIVERSAL::isa($_[0], __PACKAGE__) ? : 260 0 260
Condition33%1/3
@_ and UNIVERSAL::isa($_[0], __PACKAGE__)
!ll&&!rl&&r
00260
MC/DC0%0/2
@_ and UNIVERSAL::isa($_[0], __PACKAGE__)
@_ UNIVERSAL::isa($_[0], __PACKAGE__)
Truth table33%1/3
A and B
A= @_B= UNIVERSAL::isa($_[0], __PACKAGE__)
ABresult
0X0
100
111
283 ? shift
284 : $XML::Essex::Base::self;
285 260 $self->SUPER::get_handler
286 }
287  
288 =back
289  
290 =head2 Event Constructors
291  
292 Each event can be constructed by calling the appropriate function or
293 abbreviated function.
294  
295 =over
296  
297 =cut
298  
299 =item start_document
300  
301 aka: start_doc
302  
303 start_doc \%values; ## SAX does not define any %values.
304  
305 =cut
306  
307 13 ▶sub start_document { XML::Essex::Event::start_document->new( @_ ) }
Subroutine start_document: called CC=1 SCAR=0.0
Pod documented
308 7 *start_doc = \&start_document;
309  
310 =item end_document
311  
312 aka: end_doc
313  
314 end_doc \%values; ## SAX does not define any %values.
315  
316 =cut
317  
318 13 ▶sub end_document { XML::Essex::Event::end_document->new( @_ ) }
Subroutine end_document: called CC=1 SCAR=0.0
Pod documented
319 7 *end_doc = \&end_document;
320  
321 =item xml_decl
322  
323 aka: no abbreviated form
324  
325 xml_decl
326 Version => 1,
327 Encoding => "UTF-8",
328 Standalone => "yes";
329  
330 xml_decl {
331 Version => 1,
332 Encoding => "UTF-8",
333 Standalone => "yes"
334 };
335  
336 =cut
337  
338 0 ▶sub xml_decl { XML::Essex::Event::xml_decl->new( @_ ) }
Subroutine xml_decl: not called CC=1 SCAR=6.9
Pod documented
339  
340 =item start_element
341  
342 aka: start_elt, start
343  
344 my $e = start "foo", { "attr" => "va1", ... };
345 my $e = start $start_elt; ## copy constructor
346 my $e = start $elt;
347 my $e = start $end_elt;
348  
349 Stringifies like: C<< <foo attr="val"> >>
350  
351 =cut
352  
353 13 ▶sub start_element { XML::Essex::Event::start_element->new( @_ ) }
Subroutine start_element: called CC=1 SCAR=0.0
Pod documented
354 7 *start_elt = \&start_element;
355 7 *start = \&start_element;
356  
357 =item end_element
358  
359 aka: end_elt, end
360  
361 my $e = end "foo";
362 my $e = end $end_elt; ## copy constructor
363 my $e = end $start_elt; ## end for a given start_elt
364 my $e = end $elt; ## elt deconstructor
365  
366 Stringifies like: C<< </foo> >>
367  
368 =cut
369  
370 13 ▶sub end_element { XML::Essex::Event::end_element->new( @_ ) }
Subroutine end_element: called CC=1 SCAR=0.0
Pod documented
371 7 *end_elt = \&end_element;
372 7 *end = \&end_element;
373  
374 =item characters
375  
376 aka: chars
377  
378 my $e = chars "foo", "bar";
379  
380 Stringifies like the string it is: C<< foobar >>
381  
382 NOTE: the stringified form is not XML escaped.
383  
384 =cut
385  
386 4 ▶sub characters { XML::Essex::Event::characters->new( @_ ) }
Subroutine characters: called CC=1 SCAR=0.0
Pod documented
387 7 *chars = \&characters;
388  
389 =back
390  
391  
392 =head1 LIMITATIONS
393  
394 =head1 COPYRIGHT
395  
396 Copyright 2002, R. Barrie Slaymaker, Jr., All Rights Reserved
397  
398 =head1 LICENSE
399  
400 You may use this module under the terms of the BSD, Artistic, oir GPL licenses,
401 any version.
402  
403 =head1 AUTHOR
404  
405 Barrie Slaymaker <barries@slaysys.com>
406  
407 =cut
408  
409 7 1;
« Handler/Essex.pm ↑ Summary Essex/Constants.pm »