Zoom.pm

filter: Statementstmt 82.8% 77 / 93 Branchbran 81.2% 13 / 16 Conditioncond 50.0% 1 / 2 MC/DCmcdc 0.0% 0 / 1 Subroutinesub 78.5% 22 / 28 Podpod 88.2% 15 / 17 totaltotal 81.5% 128 / 157 SCAR 25.5
CC
12
Cov
82%
then
6.0
to_stream
4.0
AUTOLOAD
3.0
CRAP 12.8
« Zoom/Parser/BuiltIn.pm ↑ Summary Zoom/StreamUtils.pm »
1 package HTML::Zoom;
2  
3 15 ▶use strictures 1;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 15 ▶use HTML::Zoom::ZConfig;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 15 ▶use HTML::Zoom::ReadFH;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 15 ▶use HTML::Zoom::Transform;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 15 ▶use HTML::Zoom::TransformBuilder;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 15 ▶use Scalar::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 15 our $VERSION = '0.009008_01';
12  
13 15 $VERSION = eval $VERSION;
14  
15 sub new {
16 63 ▶ my ($class, $args) = @_;
Subroutine new: called CC=2 SCAR=7.0
Pod documented
17 63 my $new = {};
18 63 ▶ $new->{zconfig} = HTML::Zoom::ZConfig->new($args->{zconfig}||{});
Condition50%1/2
$args->{'zconfig'} || {}
l!l
063
MC/DC0%0/1
$args->{'zconfig'} || {}
$args->{'zconfig'}
Truth table50%1/2
A
A= $args->{'zconfig'}
Aresult
11
00
19 63 bless($new, $class);
20 }
21  
22 284 ▶sub zconfig { shift->_self_or_new->{zconfig} }
Subroutine zconfig: called CC=1 SCAR=0.0
Pod documented
23  
24 sub _self_or_new {
25 578 ▶ ref($_[0]) ? $_[0] : $_[0]->new
Subroutine _self_or_new: called CC=2 SCAR=6.9
Branch: 1 branch
BranchTrueFalseTotal
ref $_[0] ? : 516 62 578
26 }
27  
28 sub _with {
29 135 ▶ bless({ %{$_[0]}, %{$_[1]} }, ref($_[0]));
Subroutine _with: called CC=1 SCAR=0.0
30 }
31  
32 sub from_events {
33 63 ▶ my $self = shift->_self_or_new;
Subroutine from_events: called CC=1 SCAR=0.0
Pod documented
34 63 $self->_with({
35 initial_events => shift,
36 });
37 }
38  
39 sub from_html {
40 61 ▶ my $self = shift->_self_or_new;
Subroutine from_html: called CC=1 SCAR=0.0
Pod documented
41 61 $self->from_events($self->zconfig->parser->html_to_events($_[0]))
42 }
43  
44 sub from_file {
45 0 ▶ my $self = shift->_self_or_new;
Subroutine from_file: not called CC=1 SCAR=6.9
Pod documented
46 0 my $filename = shift;
47 0 $self->from_html(do { local (@ARGV, $/) = ($filename); <> });
48 }
49  
50 sub to_stream {
51 63 ▶ my $self = shift;
Subroutine to_stream: called CC=4 SCAR=13.9
Pod documented
52 die "No events to build from - forgot to call from_html?"
53 63 ▶ unless $self->{initial_events};
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"initial_events"} 0 63 63
54 63 my $sutils = $self->zconfig->stream_utils;
55 63 my $stream = $sutils->stream_from_array(@{$self->{initial_events}});
56 63 ▶ $stream = $_->apply_to_stream($stream) for @{$self->{transforms}||[]};
Branch: 1 branch
BranchTrueFalseTotal
$self->{"transforms"} or [] 6 57 63
57 60 $stream
58 }
59  
60 sub to_fh {
61 2 ▶ HTML::Zoom::ReadFH->from_zoom(shift);
Subroutine to_fh: called CC=1 SCAR=0.0
Pod documented
62 }
63  
64 sub to_events {
65 1 ▶ my $self = shift;
Subroutine to_events: called CC=1 SCAR=0.0
Pod undocumented
66 1 [ $self->zconfig->stream_utils->stream_to_array($self->to_stream) ];
67 }
68  
69 sub run {
70 1 ▶ my $self = shift;
Subroutine run: called CC=1 SCAR=0.0
Pod documented
71 1 $self->to_events;
72 return
73 1 }
74  
75 sub apply {
76 0 ▶ my ($self, $code) = @_;
Subroutine apply: not called CC=1 SCAR=6.9
Pod documented
77 0 local $_ = $self;
78 0 $self->$code;
79 }
80  
81 sub apply_if {
82 2 ▶ my ($self, $predicate, $code) = @_;
Subroutine apply_if: called CC=2 SCAR=6.9
Pod documented
83 2 ▶ if($predicate) {
Branch: 1 branch
BranchTrueFalseTotal
if ($predicate) { } 1 1 2
84 1 local $_ = $self;
85 1 $self->$code;
86 }
87 else {
88 1 $self;
89 }
90 }
91  
92 sub to_html {
93 59 ▶ my $self = shift;
Subroutine to_html: called CC=1 SCAR=0.0
Pod documented
94 59 $self->zconfig->producer->html_from_stream($self->to_stream);
95 }
96  
97 sub memoize {
98 0 ▶ my $self = shift;
Subroutine memoize: not called CC=1 SCAR=6.9
Pod documented
99 0 ref($self)->new($self)->from_html($self->to_html);
100 }
101  
102 sub with_transform {
103 72 ▶ my $self = shift->_self_or_new;
Subroutine with_transform: called CC=2 SCAR=6.9
Pod undocumented
104 72 my ($transform) = @_;
105 $self->_with({
106 transforms => [
107 72 ▶ @{$self->{transforms}||[]},
Branch: 1 branch
BranchTrueFalseTotal
$self->{"transforms"} or [] 57 15 72
108 $transform
109 ]
110 });
111 }
112
113 sub with_filter {
114 0 ▶ my $self = shift->_self_or_new;
Subroutine with_filter: not called CC=1 SCAR=6.9
Pod documented
115 0 my ($selector, $filter) = @_;
116 0 $self->with_transform(
117 HTML::Zoom::Transform->new({
118 zconfig => $self->zconfig,
119 selector => $selector,
120 filters => [ $filter ]
121 })
122 );
123 }
124  
125 sub select {
126 98 ▶ my $self = shift->_self_or_new;
Subroutine select: called CC=1 SCAR=0.0
Pod documented
127 98 my ($selector) = @_;
128 98 return HTML::Zoom::TransformBuilder->new({
129 zconfig => $self->zconfig,
130 selector => $selector,
131 proto => $self
132 });
133 }
134  
135 # There's a bug waiting to happen here: if you do something like
136 #
137 # $zoom->select('.foo')
138 # ->remove_attribute(class => 'foo')
139 # ->then
140 # ->well_anything_really
141 #
142 # the second action won't execute because it doesn't match anymore.
143 # Ideally instead we'd merge the match subs but that's more complex to
144 # implement so I'm deferring it for the moment.
145  
146 sub then {
147 0 ▶ my $self = shift;
Subroutine then: not called CC=2 SCAR=17.9
Pod documented
148 die "Can't call ->then without a previous transform"
149 0 ▶ unless $self->{transforms};
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"transforms"} 0 0 0
150 0 $self->select($self->{transforms}->[-1]->selector);
151 }
152  
153 sub AUTOLOAD {
154 25 ▶ my ($self, $selector, @args) = @_;
Subroutine AUTOLOAD: called CC=3 SCAR=11.0
155 25 my $sel = $self->select($selector);
156 25 my $meth = our $AUTOLOAD;
157 25 $meth =~ s/.*:://;
158 25 ▶ if (ref($selector) eq 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $selector eq 'HASH') { } 2 23 25
159 2 my $ret = $self;
160 2 $ret = $ret->_do($_, $meth, @{$selector->{$_}}) for keys %$selector;
161 2 $ret;
162 } else {
163 23 $self->_do($selector, $meth, @args);
164 }
165 }
166  
167 sub _do {
168 27 ▶ my ($self, $selector, $meth, @args) = @_;
Subroutine _do: called CC=2 SCAR=6.9
169 27 my $sel = $self->select($selector);
170 27 ▶ if( my $cr = $sel->_zconfig->filter_builder->can($meth)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $cr = $sel->_zconfig->filter_builder->can($meth)) { } 26 1 27
171 26 return $sel->$meth(@args);
172 } else {
173 1 die "We can't do $meth on ->select('$selector')";
174 }
175 }
176  
177 ▶sub DESTROY {}
Subroutine DESTROY: not called CC=1 SCAR=0.0
178  
179 15 1;
180  
181 =head1 NAME
182  
183 HTML::Zoom - selector based streaming template engine
184  
185 =head1 SYNOPSIS
186  
187 use HTML::Zoom;
188  
189 my $template = <<HTML;
190 <html>
191 <head>
192 <title>Hello people</title>
193 </head>
194 <body>
195 <h1 id="greeting">Placeholder</h1>
196 <div id="list">
197 <span>
198 <p>Name: <span class="name">Bob</span></p>
199 <p>Age: <span class="age">23</span></p>
200 </span>
201 <hr class="between" />
202 </div>
203 </body>
204 </html>
205 HTML
206  
207 my $output = HTML::Zoom
208 ->from_html($template)
209 ->select('title, #greeting')->replace_content('Hello world & dog!')
210 ->select('#list')->repeat_content(
211 [
212 sub {
213 $_->select('.name')->replace_content('Matt')
214 ->select('.age')->replace_content('26')
215 },
216 # alternate form
217 sub {
218 $_->replace_content({'.name' => ['Mark'],'.age' => ['0x29'] })
219 },
220 #alternate alternate form
221 sub {
222 $_->replace_content('.name' => 'Epitaph')
223 ->replace_content('.age' => '<redacted>')
224 },
225 ],
226 { repeat_between => '.between' }
227 )
228 ->to_html;
229  
230 will produce:
231  
232 =begin testinfo
233  
234 my $expect = <<HTML;
235  
236 =end testinfo
237  
238 <html>
239 <head>
240 <title>Hello world &amp; dog!</title>
241 </head>
242 <body>
243 <h1 id="greeting">Hello world &amp; dog!</h1>
244 <div id="list">
245 <span>
246 <p>Name: <span class="name">Matt</span></p>
247 <p>Age: <span class="age">26</span></p>
248 </span>
249 <hr class="between" />
250 <span>
251 <p>Name: <span class="name">Mark</span></p>
252 <p>Age: <span class="age">0x29</span></p>
253 </span>
254 <hr class="between" />
255 <span>
256 <p>Name: <span class="name">Epitaph</span></p>
257 <p>Age: <span class="age">&lt;redacted&gt;</span></p>
258 </span>
259
260 </div>
261 </body>
262 </html>
263  
264 =begin testinfo
265  
266 HTML
267 is($output, $expect, 'Synopsis code works ok');
268  
269 =end testinfo
270  
271 =head1 DANGER WILL ROBINSON
272  
273 This is a 0.9 release. That means that I'm fairly happy the API isn't going
274 to change in surprising and upsetting ways before 1.0 and a real compatibility
275 freeze. But it also means that if it turns out there's a mistake the size of
276 a politician's ego in the API design that I haven't spotted yet there may be
277 a bit of breakage between here and 1.0. Hopefully not though. Appendages
278 crossed and all that.
279  
280 Worse still, the rest of the distribution isn't documented yet. I'm sorry.
281 I suck. But lots of people have been asking me to ship this, docs or no, so
282 having got this class itself at least somewhat documented I figured now was
283 a good time to cut a first real release.
284  
285 =head1 DESCRIPTION
286  
287 HTML::Zoom is a lazy, stream oriented, streaming capable, mostly functional,
288 CSS selector based semantic templating engine for HTML and HTML-like
289 document formats.
290  
291 Which is, on the whole, a bit of a mouthful. So let me step back a moment
292 and explain why you care enough to understand what I mean:
293  
294 =head2 JQUERY ENVY
295  
296 HTML::Zoom is the cure for JQuery envy. When your javascript guy pushes a
297 piece of data into a document by doing:
298  
299 $('.username').replaceAll(username);
300  
301 In HTML::Zoom one can write
302  
303 $zoom->select('.username')->replace_content($username);
304  
305 which is, I hope, almost as clear, hampered only by the fact that Zoom can't
306 assume a global document and therefore has nothing quite so simple as the
307 $() function to get the initial selection.
308  
309 L<HTML::Zoom::SelectorParser> implements a subset of the JQuery selector
310 specification, and will continue to track that rather than the W3C standards
311 for the forseeable future on grounds of pragmatism. Also on grounds of their
312 spec is written in EN_US rather than EN_W3C, and I read the former much better.
313  
314 I am happy to admit that it's very, very much a subset at the moment - see the
315 L<HTML::Zoom::SelectorParser> POD for what's currently there, and expect more
316 and more to be supported over time as we need it and patch it in.
317  
318 =head2 CLEAN TEMPLATES
319  
320 HTML::Zoom is the cure for messy templates. How many times have you looked at
321 templates like this:
322  
323 <form action="/somewhere">
324 [% FOREACH field IN fields %]
325 <label for="[% field.id %]">[% field.label %]</label>
326 <input name="[% field.name %]" type="[% field.type %]" value="[% field.value %]" />
327 [% END %]
328 </form>
329  
330 and despaired of the fact that neither the HTML structure nor the logic are
331 remotely easy to read? Fortunately, with HTML::Zoom we can separate the two
332 cleanly:
333  
334 <form class="myform" action="/somewhere">
335 <label />
336 <input />
337 </form>
338  
339 $zoom->select('.myform')->repeat_content([
340 map { my $field = $_; sub {
341  
342 $_->select('label')
343 ->add_to_attribute( for => $field->{id} )
344 ->then
345 ->replace_content( $field->{label} )
346 ->add_to_attribute(
347 input => {
348 name => $field->{name},
349 type => $field->{type},
350 value => $field->{value}
351 })
352 } } @fields
353 ]);
354  
355 This is, admittedly, very much not shorter. However, it makes it extremely
356 clear what's happening and therefore less hassle to maintain. Especially
357 because it allows the designer to fiddle with the HTML without cutting
358 himself on sharp ELSE clauses, and the developer to add available data to
359 the template without getting angle bracket cuts on sensitive parts.
360  
361 Better still, HTML::Zoom knows that it's inserting content into HTML and
362 can escape it for you - the example template should really have been:
363  
364 <form action="/somewhere">
365 [% FOREACH field IN fields %]
366 <label for="[% field.id | html %]">[% field.label | html %]</label>
367 <input name="[% field.name | html %]" type="[% field.type | html %]" value="[% field.value | html %]" />
368 [% END %]
369 </form>
370  
371 and frankly I'll take slightly more code any day over *that* crawling horror.
372  
373 (addendum: I pick on L<Template Toolkit|Template> here specifically because
374 it's the template system I hate the least - for text templating, I don't
375 honestly think I'll ever like anything except the next version of Template
376 Toolkit better - but HTML isn't text. Zoom knows that. Do you?)
377  
378 =head2 PUTTING THE FUN INTO FUNCTIONAL
379  
380 The principle of HTML::Zoom is to provide a reusable, functional container
381 object that lets you build up a set of transforms to be applied; every method
382 call you make on a zoom object returns a new object, so it's safe to do so
383 on one somebody else gave you without worrying about altering state (with
384 the notable exception of ->next for stream objects, which I'll come to later).
385  
386 So:
387  
388 my $z2 = $z1->select('.name')->replace_content($name);
389  
390 my $z3 = $z2->select('.title')->replace_content('Ms.');
391  
392 each time produces a new Zoom object. If you want to package up a set of
393 transforms to re-use, HTML::Zoom provides an 'apply' method:
394  
395 my $add_name = sub { $_->select('.name')->replace_content($name) };
396
397 my $same_as_z2 = $z1->apply($add_name);
398  
399 =head2 LAZINESS IS A VIRTUE
400  
401 HTML::Zoom does its best to defer doing anything until it's absolutely
402 required. The only point at which it descends into state is when you force
403 it to create a stream, directly by:
404  
405 my $stream = $zoom->to_stream;
406  
407 while (my $evt = $stream->next) {
408 # handle zoom event here
409 }
410  
411 or indirectly via:
412  
413 my $final_html = $zoom->to_html;
414  
415 my $fh = $zoom->to_fh;
416  
417 while (my $chunk = $fh->getline) {
418 ...
419 }
420  
421 Better still, the $fh returned doesn't create its stream until the first
422 call to getline, which means that until you call that and force it to be
423 stateful you can get back to the original stateless Zoom object via:
424  
425 my $zoom = $fh->to_zoom;
426  
427 which is exceedingly handy for filtering L<Plack> PSGI responses, among other
428 things.
429  
430 Because HTML::Zoom doesn't try and evaluate everything up front, you can
431 generally put things together in whatever order is most appropriate. This
432 means that:
433  
434 my $start = HTML::Zoom->from_html($html);
435  
436 my $zoom = $start->select('div')->replace_content('THIS IS A DIV!');
437  
438 and:
439  
440 my $start = HTML::Zoom->select('div')->replace_content('THIS IS A DIV!');
441  
442 my $zoom = $start->from_html($html);
443  
444 will produce equivalent final $zoom objects, thus proving that there can be
445 more than one way to do it without one of them being a
446 L<bait and switch|Switch>.
447  
448 =head2 STOCKTON TO DARLINGTON UNDER STREAM POWER
449  
450 HTML::Zoom's execution always happens in terms of streams under the hood
451 - that is, the basic pattern for doing anything is -
452  
453 my $stream = get_stream_from_somewhere
454  
455 while (my ($evt) = $stream->next) {
456 # do something with the event
457 }
458  
459 More importantly, all selectors and filters are also built as stream
460 operations, so a selector and filter pair is effectively:
461  
462 sub next {
463 my ($self) = @_;
464 my $next_evt = $self->parent_stream->next;
465 if ($self->selector_matches($next_evt)) {
466 return $self->apply_filter_to($next_evt);
467 } else {
468 return $next_evt;
469 }
470 }
471  
472 Internally, things are marginally more complicated than that, but not enough
473 that you as a user should normally need to care.
474  
475 In fact, an HTML::Zoom object is mostly just a container for the relevant
476 information from which to build the final stream that does the real work. A
477 stream built from a Zoom object is a stream of events from parsing the
478 initial HTML, wrapped in a filter stream per selector/filter pair provided
479 as described above.
480  
481 The upshot of this is that the application of filters works just as well on
482 streams as on the original Zoom object - in fact, when you run a
483 L</repeat_content> operation your subroutines are applied to the stream for
484 that element of the repeat, rather than constructing a new zoom per repeat
485 element as well.
486  
487 More concretely:
488  
489 $_->select('div')->replace_content('I AM A DIV!');
490  
491 works on both HTML::Zoom objects themselves and HTML::Zoom stream objects and
492 shares sufficient of the implementation that you can generally forget the
493 difference - barring the fact that a stream already has state attached so
494 things like to_fh are no longer available.
495  
496 =head2 POP! GOES THE WEASEL
497  
498 ... and by Weasel, I mean layout.
499  
500 HTML::Zoom's filehandle object supports an additional event key, 'flush',
501 that is transparent to the rest of the system but indicates to the filehandle
502 object to end a getline operation at that point and return the HTML so far.
503  
504 This means that in an environment where streaming output is available, such
505 as a number of the L<Plack> PSGI handlers, you can add the flush key to an
506 event in order to ensure that the HTML generated so far is flushed through
507 to the browser right now. This can be especially useful if you know you're
508 about to call a web service or a potentially slow database query or similar
509 to ensure that at least the header/layout of your page renders now, improving
510 perceived user responsiveness while your application waits around for the
511 data it needs.
512  
513 This is currently exposed by the 'flush_before' option to the collect filter,
514 which incidentally also underlies the replace and repeat filters, so to
515 indicate we want this behaviour to happen before a query is executed we can
516 write something like:
517  
518 $zoom->select('.item')->repeat(sub {
519 if (my $row = $db_thing->next) {
520 return sub { $_->select('.item-name')->replace_content($row->name) }
521 } else {
522 return
523 }
524 }, { flush_before => 1 });
525  
526 which should have the desired effect given a sufficiently lazy $db_thing (for
527 example a L<DBIx::Class::ResultSet> object).
528  
529 =head2 A FISTFUL OF OBJECTS
530  
531 At the core of an HTML::Zoom system lurks an L<HTML::Zoom::ZConfig> object,
532 whose purpose is to hang on to the various bits and pieces that things need
533 so that there's a common way of accessing shared functionality.
534  
535 Were I a computer scientist I would probably call this an "Inversion of
536 Control" object - which you'd be welcome to google to learn more about, or
537 you can just imagine a computer scientist being suspended upside down over
538 a pit. Either way works for me, I'm a pure maths grad.
539  
540 The ZConfig object hangs on to one each of the following for you:
541  
542 =over 4
543  
544 =item * An HTML parser, normally L<HTML::Zoom::Parser::BuiltIn>
545  
546 =item * An HTML producer (emitter), normally L<HTML::Zoom::Producer::BuiltIn>
547  
548 =item * An object to build event filters, normally L<HTML::Zoom::FilterBuilder>
549  
550 =item * An object to parse CSS selectors, normally L<HTML::Zoom::SelectorParser>
551  
552 =item * An object to build streams, normally L<HTML::Zoom::StreamUtils>
553  
554 =back
555  
556 In theory you could replace any of these with anything you like, but in
557 practice you're probably best restricting yourself to subclasses, or at
558 least things that manage to look like the original if you squint a bit.
559  
560 If you do something more clever than that, or find yourself overriding things
561 in your ZConfig a lot, please please tell us about it via one of the means
562 mentioned under L</SUPPORT>.
563  
564 =head2 SEMANTIC DIDACTIC
565  
566 Some will argue that overloading CSS selectors to do data stuff is a terrible
567 idea, and possibly even a step towards the "Concrete Javascript" pattern
568 (which I abhor) or Smalltalk's Morphic (which I ignore, except for the part
569 where it keeps reminding me of the late, great Tony Hart's plasticine friend).
570  
571 To which I say, "eh", "meh", and possibly also "feh". If it really upsets
572 you, either use extra classes for this (and remove them afterwards) or
573 use special fake elements or, well, honestly, just use something different.
574 L<Template::Semantic> provides a similar idea to zoom except using XPath
575 and XML::LibXML transforms rather than a lightweight streaming approach -
576 maybe you'd like that better. Or maybe you really did want
577 L<Template Toolkit|Template> after all. It is still damn good at what it does,
578 after all.
579  
580 So far, however, I've found that for new sites the designers I'm working with
581 generally want to produce nice semantic HTML with classes that represent the
582 nature of the data rather than the structure of the layout, so sharing them
583 as a common interface works really well for us.
584  
585 In the absence of any evidence that overloading CSS selectors has killed
586 children or unexpectedly set fire to grandmothers - and given microformats
587 have been around for a while there's been plenty of opportunity for
588 octagenarian combustion - I'd suggest you give it a try and see if you like it.
589  
590 =head2 GET THEE TO A SUMMARY!
591  
592 Erm. Well.
593  
594 HTML::Zoom is a lazy, stream oriented, streaming capable, mostly functional,
595 CSS selector based semantic templating engine for HTML and HTML-like
596 document formats.
597  
598 But I said that already. Although hopefully by now you have some idea what I
599 meant when I said it. If you didn't have any idea the first time. I mean, I'm
600 not trying to call you stupid or anything. Just saying that maybe it wasn't
601 totally obvious without the explanation. Or something.
602  
603 Er.
604  
605 Maybe we should just move on to the method docs.
606  
607 =head1 METHODS
608  
609 =head2 new
610  
611 my $zoom = HTML::Zoom->new;
612  
613 my $zoom = HTML::Zoom->new({ zconfig => $zconfig });
614  
615 Create a new empty Zoom object. You can optionally pass an
616 L<HTML::Zoom::ZConfig> instance if you're trying to override one or more of
617 the default components.
618  
619 This method isn't often used directly since several other methods can also
620 act as constructors, notable L</select> and L</from_html>
621  
622 =head2 zconfig
623  
624 my $zconfig = $zoom->zconfig;
625  
626 Retrieve the L<HTML::Zoom::ZConfig> instance used by this Zoom object. You
627 shouldn't usually need to call this yourself.
628  
629 =head2 from_html
630  
631 my $zoom = HTML::Zoom->from_html($html);
632  
633 my $z2 = $z1->from_html($html);
634  
635 Parses the HTML using the current zconfig's parser object and returns a new
636 zoom instance with that as the source HTML to be transformed.
637  
638 =head2 from_file
639  
640 my $zoom = HTML::Zoom->from_file($file);
641  
642 my $z2 = $z1->from_file($file);
643  
644 Convenience method - slurps the contents of $file and calls from_html with it.
645  
646 =head2 from_events
647  
648 my $zoom = HTML::Zoom->from_events($evt);
649  
650 Create a new Zoom object from collected events
651  
652 =head2 to_stream
653  
654 my $stream = $zoom->to_stream;
655  
656 while (my ($evt) = $stream->next) {
657 ...
658  
659 Creates a stream, starting with a stream of the events from the HTML supplied
660 via L</from_html> and then wrapping it in turn with each selector+filter pair
661 that have been applied to the zoom object.
662  
663 =head2 to_fh
664  
665 my $fh = $zoom->to_fh;
666  
667 call_something_expecting_a_filehandle($fh);
668  
669 Returns an L<HTML::Zoom::ReadFH> instance that will create a stream the first
670 time its getline method is called and then return all HTML up to the next
671 event with 'flush' set.
672  
673 You can pass this filehandle to compliant PSGI handlers (and probably most
674 web frameworks).
675  
676 =head2 run
677  
678 $zoom->run;
679  
680 Runs the zoom object's transforms without doing anything with the results.
681  
682 Normally used to get side effects of a zoom run - for example when using
683 L<HTML::Zoom::FilterBuilder/collect> to slurp events for scraping or layout.
684  
685 =head2 apply
686  
687 my $z2 = $z1->apply(sub {
688 $_->select('div')->replace_content('I AM A DIV!') })
689 });
690  
691 Sets $_ to the zoom object and then runs the provided code. Basically syntax
692 sugar, the following is entirely equivalent:
693  
694 my $sub = sub {
695 shift->select('div')->replace_content('I AM A DIV!') })
696 };
697  
698 my $z2 = $sub->($z1);
699  
700 =head2 apply_if
701  
702 my $z2 = $z1->apply_if($cond, sub {
703 $_->select('div')->replace_content('I AM A DIV!') })
704 });
705  
706 ->apply but will only run the tranform if $cond is true
707  
708 =head2 to_html
709  
710 my $html = $zoom->to_html;
711  
712 Runs the zoom processing and returns the resulting HTML.
713  
714 =head2 memoize
715  
716 my $z2 = $z1->memoize;
717  
718 Creates a new zoom whose source HTML is the results of the original zoom's
719 processing. Effectively syntax sugar for:
720  
721 my $z2 = HTML::Zoom->from_html($z1->to_html);
722  
723 but preserves your L<HTML::Zoom::ZConfig> object.
724  
725 =head2 with_filter
726  
727 my $zoom = HTML::Zoom->with_filter(
728 'div', $filter_builder->replace_content('I AM A DIV!')
729 );
730  
731 my $z2 = $z1->with_filter(
732 'div', $filter_builder->replace_content('I AM A DIV!')
733 );
734  
735 Lower level interface than L</select> to adding filters to your zoom object.
736  
737 In normal usage, you probably don't need to call this yourself.
738  
739 =head2 select
740  
741 my $zoom = HTML::Zoom->select('div')->replace_content('I AM A DIV!');
742  
743 my $z2 = $z1->select('div')->replace_content('I AM A DIV!');
744  
745 Returns an intermediary object of the class L<HTML::Zoom::TransformBuilder>
746 on which methods of your L<HTML::Zoom::FilterBuilder> object can be called.
747  
748 In normal usage you should generally always put the pair of method calls
749 together; the intermediary object isn't designed or expected to stick around.
750  
751 =head2 then
752  
753 my $z2 = $z1->select('div')->add_to_attribute(class => 'spoon')
754 ->then
755 ->replace_content('I AM A DIV!');
756  
757 Re-runs the previous select to allow you to chain actions together on the
758 same selector.
759  
760 =head1 AUTOLOAD METHODS
761  
762 L<HTML::Zoom> AUTOLOADS methods against L</select> so that you can reduce a
763 certain amount of boilerplate typing. This allows you to replace:
764  
765 $z->select('div')->replace_content("Hello World");
766
767 With:
768  
769 $z->replace_content(div => "Hello World");
770
771 Besides saving a few keys per invocations, you may feel this looks neater
772 in your code and increases understanding.
773  
774 =head1 AUTHOR
775  
776 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
777  
778 =head1 CONTRIBUTORS
779  
780 Oliver Charles
781  
782 Jakub Nareski
783  
784 Simon Elliott
785  
786 Joe Highton
787  
788 John Napiorkowski
789  
790 Robert Buels
791  
792 David Dorward
793  
794 =head1 COPYRIGHT
795  
796 Copyright (c) 2010-2011 the HTML::Zoom L</AUTHOR> and L</CONTRIBUTORS>
797 as listed above.
798  
799 =head1 LICENSE
800  
801 This library is free software, you can redistribute it and/or modify
802 it under the same terms as Perl itself.
803  
804 =cut
805  
« Zoom/Parser/BuiltIn.pm ↑ Summary Zoom/StreamUtils.pm »