NAME

NAME
XHTML::Util - (alpha software) powerful utilities for common but
difficult to nail HTML munging.

VERSION
0.04

SYNOPSIS
use strict;
use warnings;
use XHTML::Util;
my $xu = XHTML::Util->new;
print $xu->enpara("This is naked\n\ntext for making into paragraphs.");

# This is naked
#
# text for making into paragraphs.

print $xu->enpara("<blockquote>Quotes should probably have paras.</blockquote>", "blockquote");
# <blockquote>
# Quotes should probably have paras.
# </blockquote>

print $xu->strip_tags('<a href="#">Something</a>.','a');
# Something.

DESCRIPTION
This is a set of itches I'm sick of scratching 5 different ways from the
Sabbath. Right now it's in alpha-mode so please sample but don't count
on the interface or behavior. Some of the code is fire tested in other
places but as this is a new home and API, it's subject to change. Like
they say, release early, release often. Like I say: Release whatever
you've got so you'll be embarrassed into making it better.

You can use CSS expressions to most of the methods. E.g., to only enpara
the contents of div tags with a class of "enpara" -- "<div
class="enpara"/>" -- you could do this-

print $xu->enpara($content, "div.enpara");

To do the contents of all blockquotes and divs-

print $xu->enpara($content, "div, blockquote");

METHODS
new
Creates a new "XHTML::Util" object.

strip_tags
Why you might need this-

my $post_title = "I <3 <a href="http://icanhascheezburger.com/">kittehs</a>";
my $blog_link = some_link_maker($post_title);
print $blog_link;

<a href="/oh-noes">I <3 <a href="http://icanhascheezburger.com/">kittehs</a></a>

That ain't legal so there's no definition for what browsers should do
with it. Some sort of tolerate it, some don't. It's never going to be a
good user experience.

What you can do, and I've done successfully for years, is something like
this-

my $post_title = "I <3 <a href="http://icanhascheezburger.com/">kittehs</a>";
my $safe_title = $xu->strip_tags($post_title, ["a"]);
# Menu link should only go to the single post page.
my $menu_view_title = some_link_maker($safe_title);
# No need to link back to the page you're viewing already.
my $single_view_title = $post_title;

remove
Takes a content block and a CSS selector string. Completely removes the
matched nodes, including their content. This differs from "strip_tags"
which retains the child nodes intact and only removes the tag(s) proper.

my $cleaned = $xu->remove($html, "center, img[src^='http']");

traverse
[Not implemented.] Walks the given nodes and executes the given
callback.

translate_tags
[Not implemented.] Translates one tag to another.

remove_style
[Not implemented.] Removes styles from matched nodes. To remove all
style from a fragment-

$xu->remove_style($content, "*");

inline_stylesheets
[Not implemented.] Moves all linked stylesheet information into inline
style attributes. This is useful, for example, when distributing a
document fragment like an RSS/Atom feed and having it match its online
appearance.

html_to_xhtml
[Not implemented.] Upgrades old or broken HTML to valid XHTML.

validate
[Not implemented.] Validates a given document or fragment against its
claimed DTD or one provided by name.

enpara
To add paragraph markup to naked text. There are many, many
implementations of this basic idea out there as well as many like
Markdown which do much more. While some are decent, none is really meant
to sling arbitrary HTML and get DWIM behavior from places where it's
left out; every implementation I've seen either has rigid syntax or has
beaucoup failure prone edge cases. Consider these-

Is this a paragraph
or two?

I can do HTML when I'm paying attention.
Or I need to for some reason.
Oh, I stopped paying attention... What happens here? Or here?

I'd like to see this in a paragraph so it's legal markup.
<pre>
now
this
should

not be touched!
</pre>I meant to do that.

With "XHTML::Util->enpara" you will get-

Is this a paragraph 
or two?

I can do HTML when I'm paying attention.
Or I need to for some reason.
Oh, I stopped paying attention... What happens here? Or here?

I'd like to see this in a paragraph so it's legal markup.
<pre>
now
this
should

not be touched!
</pre>
I meant to do that.

xml_parser
Don't use unless you read the code and see why/how.

selector_to_xpath
This wraps "selector_to_xpath" in selector_to_xpath
HTML::Selector::Xpath. Not really meant to be used but exposed in case
you want it.

print $xu->selector_to_xpath("form[name='register'] input[type='password']");
# //form[@name='register']//input[@type='password']

TO DO
Finish spec and tests. Get it running solid enough to remove alpha
label. Generalize the argument handling. Provide optional setting or
methods for returning nodes intead of serialized content. Improve
document/head related handling/options.

BUGS AND LIMITATIONS
All input should be utf8 or at least safe to run Encode::decode_utf8 on.
Regular Latin character sets, I suspect, will be fine but extended sets
will probably give garbage or unpredictable results; guessing.

This module is currently targeted to working with body fragments. You
will get fragments back, not documents. I want to expand it to handle
both and deal with doc, DTD, head and such but that's not its primary
use case so it won't come first.

I have used many of these methods and snippets in many projects and I'm
tired of recycling them. Some are extremely useful and, at least in the
case of "enpara", better than any other implementation I've been able to
find in any language.

That said, a lot of the code herein is not well tested or at least not
well tested in this incarnation. Bug reports and good feedback are
adored.

SEE ALSO
XML::LibXML, HTML::Tagset, HTML::Entities, HTML::Selector::XPath,
HTML::TokeParser::Simple, CSS::Tiny.

CSS W3Schools, <http://www.w3schools.com/Css/default.asp>, Learning CSS
at W3C, <http://www.w3.org/Style/CSS/learning>.

AUTHOR
Ashley Pond V, "<ashley at cpan.org>".

COPYRIGHT & LICENSE
Copyright (�) 2006-2009.

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

DISCLAIMER OF WARRANTY
Because this software is licensed free of charge, there is no warranty
for the software, to the extent permitted by applicable law. Except when
otherwise stated in writing the copyright holders or other parties
provide the software "as is" without warranty of any kind, either
expressed or implied, including, but not limited to, the implied
warranties of merchantability and fitness for a particular purpose. The
entire risk as to the quality and performance of the software is with
you. Should the software prove defective, you assume the cost of all
necessary servicing, repair, or correction.

In no event unless required by applicable law or agreed to in writing
will any copyright holder, or any other party who may modify and/or
redistribute the software as permitted by the above licence, be liable
to you for damages, including any general, special, incidental, or
consequential damages arising out of the use or inability to use the
software (including but not limited to loss of data or data being
rendered inaccurate or losses sustained by you or third parties or a
failure of the software to operate with any other software), even if
such holder or other party has been advised of the possibility of such
damages.