NAME
HTML::Element::Tiny - lightweight DOM-like elements
VERSION
Version 0.003
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".
push
$elem->push(@elements, @text, @lists_of_lists);Add all arguments to the element's list of children.
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 (&<>"').