lib/HTML/Zoom.pm

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