File Coverage

blib/lib/HTML/Zoom.pm

Criterion	Covered	Total	%
statement	74	91	81.3
branch	13	16	81.2
condition	1	2	50.0
subroutine	22	28	78.5
pod	15	17	88.2
total	125	154	81.1

package HTML::Zoom;

use strictures 1;

use HTML::Zoom::ZConfig;
use HTML::Zoom::ReadFH;
use HTML::Zoom::Transform;
use HTML::Zoom::TransformBuilder;
use Scalar::Util ();

our $VERSION = '0.009009';

$VERSION = eval $VERSION;

sub new {
  my ($class, $args) = @_;
  my $new = {};
  $new->{zconfig} = HTML::Zoom::ZConfig->new($args->{zconfig}||{});
  bless($new, $class);
}

sub zconfig { shift->_self_or_new->{zconfig} }

sub _self_or_new {
  ref($_[0]) ? $_[0] : $_[0]->new
}

sub _with {
  bless({ %{$_[0]}, %{$_[1]} }, ref($_[0]));
}

sub from_events {
  my $self = shift->_self_or_new;
  $self->_with({
    initial_events => shift,
  });
}

sub from_html {
  my $self = shift->_self_or_new;
  $self->from_events($self->zconfig->parser->html_to_events($_[0]))
}

sub from_file {
  my $self = shift->_self_or_new;
  my $filename = shift;
  $self->from_html(do { local (@ARGV, $/) = ($filename); <> });
}

sub to_stream {
  my $self = shift;
  die "No events to build from - forgot to call from_html?"
    unless $self->{initial_events};
  my $sutils = $self->zconfig->stream_utils;
  my $stream = $sutils->stream_from_array(@{$self->{initial_events}});
  $stream = $_->apply_to_stream($stream) for @{$self->{transforms}||[]};
  $stream
}

sub to_fh {
  HTML::Zoom::ReadFH->from_zoom(shift);
}

sub to_events {
  my $self = shift;
  [ $self->zconfig->stream_utils->stream_to_array($self->to_stream) ];
}

sub run {
  my $self = shift;
  $self->to_events;
  return
}

sub apply {
  my ($self, $code) = @_;
  local $_ = $self;
  $self->$code;
}

sub apply_if {
  my ($self, $predicate, $code) = @_;
  if($predicate) {
    local $_ = $self;
    $self->$code;
  }
  else {
    $self;
  }
}

sub to_html {
  my $self = shift;
  $self->zconfig->producer->html_from_stream($self->to_stream);
}

sub memoize {
  my $self = shift;
  ref($self)->new($self)->from_html($self->to_html);
}

sub with_transform {
  my $self = shift->_self_or_new;
  my ($transform) = @_;
  $self->_with({
    transforms => [
      @{$self->{transforms}||[]},
      $transform
    ]
  });
}

sub with_filter {
  my $self = shift->_self_or_new;
  my ($selector, $filter) = @_;
  $self->with_transform(
    HTML::Zoom::Transform->new({
      zconfig => $self->zconfig,
      selector => $selector,
      filters => [ $filter ]
    })
  );
}

sub select {
  my $self = shift->_self_or_new;
  my ($selector) = @_;
  return HTML::Zoom::TransformBuilder->new({
    zconfig => $self->zconfig,
    selector => $selector,
    proto => $self
  });
}

# There's a bug waiting to happen here: if you do something like
#
# $zoom->select('.foo')
#      ->remove_attribute(class => 'foo')
#      ->then
#      ->well_anything_really
#
# the second action won't execute because it doesn't match anymore.
# Ideally instead we'd merge the match subs but that's more complex to
# implement so I'm deferring it for the moment.

sub then {
  my $self = shift;
  die "Can't call ->then without a previous transform"
    unless $self->{transforms};
  $self->select($self->{transforms}->[-1]->selector);
}

sub AUTOLOAD {
  my ($self, $selector, @args) = @_;
  my $sel = $self->select($selector);
  my $meth = our $AUTOLOAD;
  $meth =~ s/.*:://;
  if (ref($selector) eq 'HASH') {
    my $ret = $self;
    $ret = $ret->_do($_, $meth, @{$selector->{$_}}) for keys %$selector;
    $ret;
  } else {
    $self->_do($selector, $meth, @args);
  }
}

sub _do {
  my ($self, $selector, $meth, @args) = @_;
  my $sel = $self->select($selector);
  if( my $cr = $sel->_zconfig->filter_builder->can($meth)) {
    return $sel->$meth(@args);
  } else {
    die "We can't do $meth on ->select('$selector')";
  }
}

sub DESTROY {}

1;

=head1 NAME

HTML::Zoom - selector based streaming template engine

=head1 SYNOPSIS

  use HTML::Zoom;

  my $template = <


      Hello people


      Placeholder


          Name: Bob
          Age: 23





  HTML

  my $output = HTML::Zoom
    ->from_html($template)
    ->select('title, #greeting')->replace_content('Hello world & dog!')
    ->select('#list')->repeat_content(
        [
          sub {
            $_->select('.name')->replace_content('Matt')
              ->select('.age')->replace_content('26')
          },
          # alternate form
          sub {
            $_->replace_content({'.name' => ['Mark'],'.age' => ['0x29'] })
          },
          #alternate alternate form
          sub {
            $_->replace_content('.name' => 'Epitaph')
              ->replace_content('.age' => '')
          },
        ],
        { repeat_between => '.between' }
      )
    ->to_html;

will produce:

=begin testinfo

  my $expect = <

=end testinfo



      Hello world & dog!


      Hello world & dog!


          Name: Matt
          Age: 26



          Name: Mark
          Age: 0x29



          Name: Epitaph
          Age: <redacted>






=begin testinfo

  HTML
  is($output, $expect, 'Synopsis code works ok');

=end testinfo

=head1 DANGER WILL ROBINSON

This is a 0.9 release. That means that I'm fairly happy the API isn't going
to change in surprising and upsetting ways before 1.0 and a real compatibility
freeze. But it also means that if it turns out there's a mistake the size of
a politician's ego in the API design that I haven't spotted yet there may be
a bit of breakage between here and 1.0. Hopefully not though. Appendages
crossed and all that.

Worse still, the rest of the distribution isn't documented yet. I'm sorry.
I suck. But lots of people have been asking me to ship this, docs or no, so
having got this class itself at least somewhat documented I figured now was
a good time to cut a first real release.

=head1 DESCRIPTION

HTML::Zoom is a lazy, stream oriented, streaming capable, mostly functional,
CSS selector based semantic templating engine for HTML and HTML-like
document formats.

Which is, on the whole, a bit of a mouthful. So let me step back a moment
and explain why you care enough to understand what I mean:

=head2 JQUERY ENVY

HTML::Zoom is the cure for JQuery envy. When your javascript guy pushes a
piece of data into a document by doing:

  $('.username').replaceAll(username);

In HTML::Zoom one can write

  $zoom->select('.username')->replace_content($username);

which is, I hope, almost as clear, hampered only by the fact that Zoom can't
assume a global document and therefore has nothing quite so simple as the
$() function to get the initial selection.

L implements a subset of the JQuery selector
specification, and will continue to track that rather than the W3C standards
for the forseeable future on grounds of pragmatism. Also on grounds of their
spec is written in EN_US rather than EN_W3C, and I read the former much better.

I am happy to admit that it's very, very much a subset at the moment - see the
L POD for what's currently there, and expect more
and more to be supported over time as we need it and patch it in.

=head2 CLEAN TEMPLATES

HTML::Zoom is the cure for messy templates. How many times have you looked at
templates like this:


  [% FOREACH field IN fields %]
    [% field.label %]

  [% END %]


and despaired of the fact that neither the HTML structure nor the logic are
remotely easy to read? Fortunately, with HTML::Zoom we can separate the two
cleanly:






  $zoom->select('.myform')->repeat_content([
    map { my $field = $_; sub {

     $_->select('label')
       ->add_to_attribute( for => $field->{id} )
       ->then
       ->replace_content( $field->{label} )
       ->add_to_attribute(
        input => {
         name => $field->{name},
         type => $field->{type},
         value => $field->{value}
       })
    } } @fields
  ]);

This is, admittedly, very much not shorter. However, it makes it extremely
clear what's happening and therefore less hassle to maintain. Especially
because it allows the designer to fiddle with the HTML without cutting
himself on sharp ELSE clauses, and the developer to add available data to
the template without getting angle bracket cuts on sensitive parts.

Better still, HTML::Zoom knows that it's inserting content into HTML and
can escape it for you - the example template should really have been:


  [% FOREACH field IN fields %]
    [% field.label | html %]

  [% END %]


and frankly I'll take slightly more code any day over *that* crawling horror.

(addendum: I pick on L