HTML::...leParse(3pm)

HTML::SimpleParse 💖 a bare-bones HTML parser

ok so bestie, you found the manual page for HTML::SimpleParse, which lives in the User Contributed Perl Documentation section of your friendly neighborhood 3pm man pages. It's giving "baby's first HTML parser" but in the most useful way possible, i promise. 🎀

---

✨ NAME ✨

HTML::SimpleParse — a bare-bones HTML parser. that's the whole thing. bare bones. no cap. 💀

---

🌸 SYNOPSIS 🌸

use HTML::SimpleParse;

# Parse the text into a simple tree
my $p = new HTML::SimpleParse( $html_text );
$p->output;                 # Output the HTML verbatim

$p->text( $new_text );      # Give it some new HTML to chew on
$p->parse                   # Parse the new HTML
$p->output;

my %attrs = HTML::SimpleParse->parse_args('A="xx" B=3');
# %attrs is now ('A' => 'xx', 'B' => '3')

---

💅 DESCRIPTION 💅

This module is a simple HTML parser, fr fr. Conceptually it's similar to HTML::Parser, but the way it differs from HTML::TreeBuilder is actually super important in a couple of ways.

First off — HTML::TreeBuilder is the overachiever that knows which tags can contain other tags, which start tags have matching end tags, which tags are only allowed to live inside the <HEAD> portion of the document, all of that. HTML::SimpleParse knows none of that. It just finds tags and text in whatever HTML you hand it, and it does not care about the specific content of those tags (though it does distinguish between different types of tags — comments, starting tags like <b>, ending tags like </b>, and so on).

Second — HTML::SimpleParse does not build you a hierarchical tree of HTML content. It builds a simple linear list. It pays zero attention to balancing start tags with their corresponding end tags, or to which pairs of tags are nested inside other pairs of tags. not its business, not its problem. 🙈

And because of those exact characteristics, you can make a very effective HTML filter by sub-classing HTML::SimpleParse. For example, to remove all comments from HTML:

package NoComment;
use HTML::SimpleParse;
@ISA = qw(HTML::SimpleParse);
sub output_comment {}

package main;
NoComment->new($some_html)->output;

Historically, the author started the HTML::SimpleParse project in part because of a misunderstanding about HTML::Parser's functionality. Many aspects of these two modules actually overlap. He continues to maintain the HTML::SimpleParse module because people seem to be depending on it, and because beginners sometimes find HTML::SimpleParse to be simpler than HTML::Parser's more powerful interface. People also seem to get a fair amount of usage out of the parse_args() method directly. iconic behavior tbh. 👑

🦋 Methods 🦋

• new

$p = new HTML::SimpleParse( $some_html );

Creates a new HTML::SimpleParse object. Optionally takes one argument, a string containing some HTML with which to initialize the object. If you give it a non-empty string, the HTML will be parsed into a tree and ready for outputting.

Can also take a list of attributes, such as

$p = new HTML::SimpleParse( $some_html, 'fix_case' => -1);

See the parse_args() method below for an explanation of this attribute.

• text

$text = $p->text;
$p->text( $new_text );

Get or set the contents of the HTML to be parsed.

• tree

foreach ($p->tree) { ... }

Returns a list of all the nodes in the tree, in case you want to step through them manually or something. Each node in the tree is an anonymous hash with (at least) three data members: $node->{type} (is this a comment, a start tag, an end tag, etc.), $node->{content} (all the text between the angle brackets, verbatim), and $node->{offset} (number of bytes from the beginning of the string).

The possible values of $node->{type} are "text", "starttag", "endtag", "ssi", and "markup".

• parse

$p->parse;

Once an object has been initialized with some text, call $p->parse and a tree will be created. After the tree is created, you can call $p->output. If you feed some text to the new() method, parse will be called automatically during your object's construction.

• parse_args

%hash = $p->parse_args( $arg_string );

This routine is handy for parsing the contents of an HTML tag into key=value pairs. For instance:

$text = 'type=checkbox checked name=flavor value="chocolate or strawberry"';
%hash = $p->parse_args( $text );
# %hash is ( TYPE=>'checkbox', CHECKED=>undef, NAME=>'flavor',
#            VALUE=>'chocolate or strawberry' )

⚠️ heads up bestie: the position of the last m//g search on the string (the value returned by Perl's pos() function) will be altered by the parse_args function, so make sure you take that into account if (in the above example) you do $text =~ m/something/g.

The parse_args() method can be run as either an object method or as a class method, i.e. as either $p->parse_args(...) or HTML::SimpleParse->parse_args(...).

HTML attribute lists are supposed to be case-insensitive with respect to attribute names. To achieve this behavior, parse_args() respects the 'fix_case' flag, which can be set either as a package global $FIX_CASE, or as a class member datum 'fix_case'. If set to 0, no case conversion is done. If set to 1, all keys are converted to upper case. If set to -1, all keys are converted to lower case. The default is 1, i.e. all keys are uppercased.

If an attribute takes no value (like "checked" in the above example) then it will still have an entry in the returned hash, but its value will be "undef". For example:

%hash = $p->parse_args('type=checkbox checked name=banana value=""');
# $hash{CHECKED} is undef, but $hash{VALUE} is ""

This method actually returns a list (not a hash), so duplicate attributes and order will be preserved if you want them to be:

@hash = $p->parse_args("name=family value=gwen value=mom value=pop");
# @hash is qw(NAME family VALUE gwen VALUE mom VALUE pop)

• output

$p->output;

This will output the contents of the HTML, passing the real work off to the output_text, output_comment, etc. functions. If you do not override any of these methods, this module will output the exact text that it parsed into a tree in the first place.

• get_output

print $p->get_output

Similar to $p->output(), but returns its result instead of printing it.

• execute

foreach ($p->tree) {
   print $p->execute($_);
}

Executes a single node in the HTML parse tree. Useful if you want to loop through the nodes and output them individually.

The following methods do the actual outputting of the various parts of the HTML. Override some of them if you want to change the way the HTML is output. For instance, to strip comments from the HTML, override the output_comment method like so:

# In subclass:
sub output_comment { }  # Does nothing

• output_text
• output_comment
• output_endtag
• output_starttag
• output_markup
• output_ssi

---

⚠️ CAVEATS ⚠️

Please do not assume that the interface here is stable. This is a first pass, and the author is still trying to incorporate suggestions from the community. If you employ this module somewhere, make doubly sure before upgrading that none of your code breaks when you use the newer version. seriously, check twice. 🫶

---

💀 BUGS 💀

• Embedded >s are broken

Won't handle tags with embedded >s in them, like <input name=expr value="x > y">. This will be fixed in a future version, probably by using the parse_args method. Suggestions are welcome.

---

🌈 TO DO 🌈

• extensibility

Based on a suggestion from Randy Harmon (thanks), the author would like to make it easier for subclasses of SimpleParse to pick out other kinds of HTML blocks, i.e. extend the set {text, comment, endtag, starttag, markup, ssi} to include more members. Currently the only easy way to do that is by overriding the parse method:

sub parse {  # In subclass
   my $self = $_[0];
   $self->SUPER::parse(@_);
   foreach ($self->tree) {
      if ($_->{content} =~ m#^a\s+#i) {
         $_->{type} = 'anchor_start';
      }
   }
}

sub output_anchor_start {
   # Whatever you want...
}

Alternatively, this feature might be implemented by hanging attachments onto the parsing loop, like this:

my $parser = new SimpleParse( $html_text );
$regex = '<(a\s+.*?)>';
$parser->watch_for( 'anchor_start', $regex );

sub SimpleParse::output_anchor_start {
   # Whatever you want...
}

The author thinks he likes that idea better. If you wanted to, you could make a subclass with output_anchor_start as one of its methods, and put the ->watch_for stuff in the constructor.

• reading from filehandles

It would be nice if you could initialize an object by giving it a filehandle or filename instead of the text itself.

• tests

The author needs to write a few tests that run under make test.

---

👑 AUTHOR 👑

Ken Williams <ken@forum.swarthmore.edu>

---

🎀 COPYRIGHT 🎀

Copyright 1998 Swarthmore College. All rights reserved.

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

---

okay slay, that's the whole page bestie, nothing skipped, nothing dropped, you're so welcome 💖✨

this little legend was brought to you by perl v5.36.0, dated 2022-10-13, and it's the HTML::...leParse(3pm) page — yes the title really does get truncated like that in the header, it's giving cunty little abbreviation and we love her for it. bye bye, go parse something 🦋🌸