The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
HTML-Element-Tiny-0.006
River stage zero No dependents
++
/ HTML::Element::Tiny

NAME

HTML::Element::Tiny - lightweight DOM-like elements

VERSION

Version 0.006

SYNOPSIS

  use HTML::Element::Tiny;
  my $tree = HTML::Element::Tiny->new(
    [ div => { id => "stuff" },
      "some text",
      [ div => "another div inside that one" ],
      "some more text"
    ]
  );

  my $elems = $tree->find({ tag => 'div' });

DESCRIPTION

HTML::Element::Tiny is a simple module for dealing with trees of HTML elements, including traversing them and manipulating the tree structure and individual element attributes, and then for generating HTML.

Though it lives under HTML::, there's no reason that you couldn't use this for processing arbitrary XML, maybe with XML::Tiny in front of it.

CAVEATS

This module does not make very many efforts to check its input as far as HTML validation goes. For example, nothing will stop you from having a tree with a repeated id attribute; this will cause you grief if you try to find by that id, since you will only ever get the first such element, and you won't get an error.

ACCESSORS

parent

The parent of this element, or undef if it is a root.

children

A list of the children of this element.

tag

  print $elem->tag; # "div"

The HTML tag for this element.

id

class

  print $elem->id; # "mylist"

  print $elem->class # "menu alert"

Shortcuts for commonly-used attributes. These are not mutators.

classes

  my @classes = $elem->classes;

Where ->class returns all classes joined with a space, this method returns a list of classnames.

attr

  print $elem->attr('href'); # "http://...something.../"

  $elem->attr({ src => "http://somewhere.com" });

Get or set attributes of an element.

With a single scalar, return the requested attribute.

With a hashref, set attributes based on keys and values of that hashref.

METHODS

new

  my $elem = HTML::Element::Tiny->new([ ... ]);

Build a new element based on the given arrayref, which is the same format expected by HTML::Element->new_from_lol, namely:

  [ <tag>, <optional \%attributes>, <strings or more arrayrefs> ]

Any children (elements past the tag and optional attributes) will recursively have new called on them as well.

clone

  my $clone = $elem->clone(\%attributes);

Return a clone of this element and its descendents, deleting the clone's parent (making it a root of its own tree) and adding any extra attributes specified.

Clone (0.28 or later) will be used, if installed. This is about twice as fast as the internal manual clone that HTML::Element::Tiny does.

iter

  my $iter = $elem->iter;

Returns an iterator for this node and all its descendents. See "ITERATORS".

all

  my $elems = $elem->all;

Returns a collection of this node and all its descendents. See "COLLECTIONS".

find

find_one

find_iter

  my $elems = $tree->find(\%arg);

  my $elem = $tree->find_one(\%arg); # or die

  my $iter = $tree->find_iter(\%arg);

These are the main traversal methods of HTML::Element::Tiny. Each takes a hashref argument which is interpreted as attributes to be matched, and searches the invocant element and all its descendents. The special -tag attribute matches the element tag. Use an empty string to indicate that an attribute should not be present.

For example:

  { -tag => 'div', class => 'alert', id => "" }

will match divs that have a class of 'alert' (and possibly others), but not divs with an id attribute.

find returns a collection of matched elements. In list context, this is simply a list of the elements. See "COLLECTIONS".

find_one either returns a single element or dies, complaining that it couldn't find any elements or it found too many.

find_iter returns an iterator of matched elements. See "ITERATORS".

prepend

append

  $elem->append(@elements, @text, @lists_of_lists);

Add all arguments to the element's list of children, either at the beginning or at the end.

Strings and arrayrefs will be passed through new first. Objects will be cloned if they already have a parent or simply attached if they do not.

remove_child

  $elem->remove_child(@elements, @indices);

Remove all listed children from the element. Arguments may either be element objects or indices (starting at 0).

Returns a collection of removed children.

as_HTML

  print $tree->as_HTML;

Return the element and its descendents as HTML. If HTML::Entities is installed, it will be used to escape any text nodes; otherwise, minimal entity escaping is done (&<>"').

ITERATORS

Several methods in this class return iterators. These iterators return elements as you call ->next on them. They have no other methods and return undef when exhausted.

COLLECTIONS

Several methods in this class return element collections. These objects represent aggregates, often a sort of 'current selection'. Most of their methods are chainable -- each method notes whether it returns a collection (either the same object or a clone) or some other value. Any method that returns a collection only does so in scalar context. In list context, those methods return a normal list of elements.

each

  my %seen;
  $elems->each(sub { $seen{$_->tag}++ });

Call the passed-in coderef once for each element. The current element is available as $_.

Returns: collection, unchanged except for whatever your sub does (may change elements in-place)

filter

grep

not

  my $elems_without_id = $elems->filter({ id => "" });

  my $elems_with_id = $elems->not({ id => "" });

Using the same syntax as "find", select only matching elements.

grep is a synonym for filter.

not selects only elements that do not match.

Returns: new collection

attr

  $elems->attr({ class => "bogus" });
  my @ids = $elems->attr('id');

Get or set element attributes.

With a hashref, this is a shortcut for each and $_->attr(\%arg).

With a scalar, this is a shortcut for map, with the added advantage that it removes all empty values.

Returns: same collection OR list of values

one

  my $e = $elems->one;

Return a single element, verifying that the collection does contain exactly one element.

Return: element

all

  my @elems = $elems->all;

Return every element in the collection, as a normal Perl list.

Return: list of elements (not collection)

map

  my @frobbed = $elems->map(sub { Frobber->frob($_) });

Shortcut for map { $code->() } $elems->all.

Return: list of values

size

  my $size = $elems->size;

Return: number of elements in collection

EXTENDING

It is possible to change the classes into which new elements are blessed. When new is called, it looks for a %TAG_CLASS in the invocant's package. If present, it will use the tag name as a key and expect a class as the value. Thus:

  package My::Element;
  use base 'HTML::Element::Tiny';
  our %TAG_CLASS = (img => "My::Element::Image");
  ... # elsewhere
  my $img = My::Element->new([ img => { src => "http://..." } ]);
  # $img isa My::Element::Image

Some keys and values in this hash are magical. Classes that start with '-' have it replaced with $class::, e.g.

  our %TAG_CLASS = (img => '-Image');

If there is a -base key, it is used instead of the class name when doing this sort of expansion.

To change the default element class, add a -default key.

A class that used all these options might have a %TAG_CLASS that looked like this:

  our %TAG_CLASS = (
    -default => 'My::Element::Base',
    -base    => 'My::Element',
    img      => '-Image',
    map      => '-Map',
  );

The default is to use the invocant's package for both -default and -base.

AUTHOR

Hans Dieter Pearcey, <hdp at cpan.org>

BUGS

Please report any bugs or feature requests to bug-html-element-tiny at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML-Element-Tiny. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc HTML::Element::Tiny

You can also look for information at:

ACKNOWLEDGEMENTS

A lot of the HTML generation is either directly from or inspired by Andy Armstrong's excellent HTML::Tiny module.

The concept of element collections is shamelessly lifted from jQuery. http://jquery.com/

COPYRIGHT & LICENSE

Copyright 2007 Hans Dieter Pearcey, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.