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.");

     # <p>This is naked</p>
     #
     # <p>text for making into paragraphs.</p>

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

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

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?

     <p>I can do HTML when I'm paying attention.</p>
     <p style="color:#a00">Or I need to for some reason.</p>
     Oh, I stopped paying attention... What happens here? Or <i>here</i>?

     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-

     <p>Is this a paragraph<br/>
     or two?</p>

     <p>I can do HTML when I'm paying attention.</p>
     <p style="color:#a00">Or I need to for some reason.</p>
     <p>Oh, I stopped paying attention... What happens here? Or <i>here</i>?</p>

     <p>I'd like to see this in a paragraph so it's legal markup.</p>
     <pre>
     now
     this
     should
 
 
     not be touched!
     </pre>
     <p>I meant to do that.</p>

  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.

