HTML::Stream(3pm)

💖 HTML::Stream 💖

so bestie, this is HTML::Stream(3pm) from the User Contributed Perl Documentation section, and it's literally about to change your whole HTML-output game. sit down, grab a boba, we're going in 🧋✨

---

🌸 NAME 🌸

HTML::Stream — an HTML output stream class, plus a lil grab-bag of markup utilities. she does both, she's versatile, we stan 🫶

---

🎀 SYNOPSIS 🎀

here's a tiny taste of the non-OO ways you can use this module, bestie:

use HTML::Stream qw(:funcs);

print html_tag('A', HREF=>$link);
print html_escape("<<Hello & welcome!>>");

and now the OO ways too, because we're not one-dimensional here:

use HTML::Stream;
$HTML = new HTML::Stream \*STDOUT;

# The vanilla interface...
$HTML->tag('A', HREF=>"$href");
$HTML->tag('IMG', SRC=>"logo.gif", ALT=>"LOGO");
$HTML->text($copyright);
$HTML->tag('_A');

# The chocolate interface...
$HTML -> A(HREF=>"$href");
$HTML -> IMG(SRC=>"logo.gif", ALT=>"LOGO");
$HTML -> t($caption);
$HTML -> _A;

# The chocolate interface, with whipped cream...
$HTML -> A(HREF=>"$href")
      -> IMG(SRC=>"logo.gif", ALT=>"LOGO")
      -> t($caption)
      -> _A;

# The strawberry interface...
output $HTML [A, HREF=>"$href"],
             [IMG, SRC=>"logo.gif", ALT=>"LOGO"],
             $caption,
             [_A];

okay but the dessert naming scheme?? the author was in their dessert era and honestly, iconic behavior 🍨

---

✨ DESCRIPTION ✨

so the HTML::Stream module gives you an object-oriented (and subclassable, bestie, we love to see it) way of outputting HTML. basically: you open up an "HTML stream" on an existing filehandle, and then you do all of your output to the HTML stream instead. and the cute part? you can totally intermix HTML-stream-output and ordinary-print-output if you feel like it. no rules, just vibes 💅

there's even a lil built-in subclass, HTML::Stream::Latin1, which handles Latin-1 input right out of the box. but all in good time, babe... 🙈

---

🍦 INTRODUCTION (the Neapolitan dessert special) 🍦

🧁 Function interface 🧁

let's start with the simple stuff, no cap. this module hands you a whole collection of non-OO utility functions for escaping HTML text and producing HTML tags. like this:

use HTML::Stream qw(:funcs);        # imports functions from @EXPORT_OK

print html_tag(A, HREF=>$url);
print '© 1996 by', html_escape($myname), '!';
print html_tag('/A');

btw bestie, that last line could be rewritten as:

print html_tag(_A);

and if you need a parameter in your tag that doesn't have an associated value, you supply the undefined value — not the empty string!! — like so:

print html_tag(TD, NOWRAP=>undef, ALIGN=>'LEFT');

     <TD NOWRAP ALIGN=LEFT>

versus:

print html_tag(IMG, SRC=>'logo.gif', ALT=>'');

     <IMG SRC="logo.gif" ALT="">

see the difference? undef = bare attribute, '' = empty-string attribute. they are not the same thing and the universe will know 😭

there are also some routines for reversing the whole process, like:

$text = "This <i>isn't</i> &quot;fun&quot;...";
print html_unmarkup($text);

     This isn't &quot;fun&quot;...

print html_unescape($text);

     This isn't "fun"...

yeah yeah yeah, I hear you cry, we've seen this stuff before. but wait! there's more... 🔥

---

🍫 OO interface, vanilla 🍫

using the function interface can get kinda tedious ngl... so we also give you an "HTML output stream" class. messages to an instance of that class basically tell that stream to output some HTML. here's the above example, rewritten with HTML streams:

use HTML::Stream;
$HTML = new HTML::Stream \*STDOUT;

$HTML->tag(A, HREF=>$url);
$HTML->ent('copy');
$HTML->text(" 1996 by $myname!");
$HTML->tag(_A);

and as you've probably guessed, bestie:

• text() — outputs some text, which will be HTML-escaped.
• tag() — outputs an ordinary tag, like <A>, possibly with parameters. the parameters will all be HTML-escaped automatically.
• ent() — outputs an HTML entity, like the © or <. you mostly don't need to use it; you can often just put the Latin-1 representation of the character in the text().

you might prefer to use t() and e() instead of text() and ent() — they're absolutely identical, and easier to type:

$HTML -> tag(A, HREF=>$url);
$HTML -> e('copy');
$HTML -> t(" 1996 by $myname!");
$HTML -> tag(_A);

now, it wouldn't be nice to give you those text() and ent() shortcuts without giving you one for tag(), would it? of course not, we're not monsters here... 😌

---

🍫🍫 OO interface, chocolate 🍫🍫

the known HTML tags even get their own tag-methods, compiled on demand. so that above code could be written even more compactly as:

$HTML -> A(HREF=>$url);
$HTML -> e('copy');
$HTML -> t(" 1996 by $myname!");
$HTML -> _A;

and as you've probably guessed:

A(HREF=>$url)   ==   tag(A, HREF=>$url)   ==   <A HREF="/the/url">
_A              ==   tag(_A)              ==   </A>

all of the autoloaded "tag-methods" use the tagname in all-uppercase. and a _ prefix on any tag-method means you want an end-tag. the _ was chosen for several reasons:

1. it's short and easy to type,
2. it doesn't produce much visual clutter to look at,
3. _TAG looks a little like /TAG because of the straight line.

• I know, I know... it looks like a private method. you get used to it. really. 💀

I should stress that this module will only auto-create tag methods for known HTML tags. so you're protected from typos like this (which will cause a fatal exception at run-time):

$HTML -> IMGG(SRC=>$src);

(you're not yet protected from illegal tag parameters, but it's a start, ain't it? 🙈)

if you need to make a tag known — sorry babe, but this is currently a global operation, and not stream-specific — do this:

accept_tag HTML::Stream 'MARQUEE';       # for you MSIE fans...

note: there is no corresponding reject_tag. the author thought and thought about it, and could not convince themselves that such a method would do anything more useful than cause other people's modules to suddenly stop working because some bozo function decided to reject the FONT tag. so. yeah. that's the tea 🍵

---

🍨 OO interface, with whipped cream 🍨

in the grand tradition of C++, output method chaining is supported in both the Vanilla Interface and the Chocolate Interface. so you can (and probably should, bestie) write the above code as:

$HTML -> A(HREF=>$url)
      -> e('copy') -> t(" 1996 by $myname!")
      -> _A;

but wait! Neapolitan ice cream has one more flavor... 🍓

---

🍓 OO interface, strawberry 🍓

the author was jealous of the compact syntax of HTML::AsSubs, but didn't want to worry about clogging the namespace with a lot of functions like p(), a(), etc. (especially when markup-functions like tr() conflict with existing Perl functions). so they came up with this:

output $HTML [A, HREF=>$url], "Here's my $caption", [_A];

conceptually, arrayrefs are sent to html_tag(), and strings to html_escape(). cute, right? 🎀

✨ ADVANCED TOPICS ✨

Okay bestie, this is where the training wheels come off. We're going deep. 💖

🎀 Auto-formatting and inserting newlines 🎀

Auto-formatting is the name I give to the Chocolate Interface feature where newlines (and maybe, in the future, other things) get inserted before or after the tags you output, so your HTML is more readable. So, by default, this:

$HTML -> HTML
      -> HEAD
      -> TITLE -> t("Hello!") -> _TITLE
      -> _HEAD
      -> BODY(BGCOLOR=>'#808080');

Actually produces this:

<HTML><HTML>
<HEAD>
<TITLE>Hello!</TITLE>
</HEAD>
<BODY BGCOLOR="#808080">

To turn off autoformatting altogether on a given HTML::Stream object, use the auto_format() method:

$HTML->auto_format(0);        # stop autoformatting!

To change whether a newline is automatically output before/after the begin/end form of a tag at a global level, use set_tag():

HTML::Stream->set_tag('B', Newlines=>15);   # 15 means "\n<B>\n \n</B>\n"
HTML::Stream->set_tag('I', Newlines=>7);    # 7 means  "\n<I>\n \n</I>  "

To change whether a newline is automatically output before/after the begin/end form of a tag for a given stream level, give the stream its own private "tag info" table, and then use set_tag():

$HTML->private_tags;
$HTML->set_tag('B', Newlines=>0);     # won't affect anyone else!

To output newlines explicitly, just use the special nl method in the Chocolate Interface:

$HTML->nl;     # one newline
$HTML->nl(6);  # six newlines

I am sometimes asked, "why don't you put more newlines in automatically?" Well, mostly because...

• Sometimes you'll be outputting stuff inside a "PRE" environment.
• Sometimes you really do want to jam things (like images, or table cell delimiters and the things they contain) right up against each other.

So I've stuck to outputting newlines in places where it's most likely to be harmless.

🦋 Entities 🦋

As shown above, You can use the ent() (or e()) method to output an entity:

$HTML->t('Copyright ')->e('copy')->t(' 1996 by Me!');

But this can be a pain, particularly for generating output with non-ASCII characters:

$HTML -> t('Copyright ')
      -> e('copy')
      -> t(' 1996 by Fran') -> e('ccedil') -> t('ois, Inc.!');

Granted, Europeans can always type the 8-bit characters directly in their Perl code, and just have this:

$HTML -> t("Copyright \251 1996 by Fran\347ois, Inc.!');

But folks without 8-bit text editors can find this kind of output cumbersome to generate. Sooooooooo...

🌸 Auto-escaping: changing the way text is escaped 🌸

Auto-escaping is the name I give to the act of taking an "unsafe" string (one with ">", "&", etc.), and magically outputting "safe" HTML.

The default "auto-escape" behavior of an HTML stream can be a drag if you've got a lot character entities that you want to output, or if you're using the Latin-1 character set, or some other input encoding. Fortunately, you can use the auto_escape() method to change the way a particular HTML::Stream works at any time.

First, here's a couple of special invocations:

$HTML->auto_escape('ALL');      # Default; escapes [<>"&] and 8-bit chars.
$HTML->auto_escape('LATIN_1');  # Like ALL, but uses Latin-1 entities
                                #   instead of decimal equivalents.
$HTML->auto_escape('NON_ENT');  # Like ALL, but leaves "&" alone.

You can also install your own auto-escape function (note that you might very well want to install it for just a little bit only, and then de-install it):

sub my_auto_escape {
    my $text = shift;
    HTML::Entities::encode($text);     # start with default
    $text =~ s/\(c\)/©/ig;        # (C) becomes copyright
    $text =~ s/\\,(c)/\&$1cedil;/ig;   # \,c becomes a cedilla
    $text;
}

# Start using my auto-escape:
my $old_esc = $HTML->auto_escape(\&my_auto_escape);

# Output some stuff:
$HTML-> IMG(SRC=>'logo.gif', ALT=>'Fran\,cois, Inc');
output $HTML 'Copyright (C) 1996 by Fran\,cois, Inc.!';

# Stop using my auto-escape:
$HTML->auto_escape($old_esc);

If you find yourself in a situation where you're doing this a lot, a better way is to create a subclass of HTML::Stream which installs your custom function when constructed. For an example, see the HTML::Stream::Latin1 subclass in this module.

💜 Outputting HTML to things besides filehandles 💜

As of Revision 1.21, you no longer need to supply new() with a filehandle: any object that responds to a print() method will do. Of course, this includes blessed FileHandles, and IO::Handles.

If you supply a GLOB reference (like "\*STDOUT") or a string (like "Module::FH"), HTML::Stream will automatically create an invisible object for talking to that filehandle (I don't dare bless it into a FileHandle, since the underlying descriptor would get closed when the HTML::Stream is destroyed, and you might not want that).

You say you want to print to a string? For kicks and giggles, try this:

package StringHandle;
sub new {
    my $self = '';
    bless \$self, shift;
}
sub print {
    my $self = shift;
    $$self .= join('', @_);
}

package main;
use HTML::Stream;

my $SH = new StringHandle;
my $HTML = new HTML::Stream $SH;
$HTML -> H1 -> t("Hello & <<welcome>>!") -> _H1;
print "PRINTED STRING: ", $$SH, "\n";

👑 Subclassing 👑

This is where you can make your application-specific HTML-generating code much easier to look at. Consider this:

package MY::HTML;
@ISA = qw(HTML::Stream);

sub Aside {
    $_[0] -> FONT(SIZE=>-1) -> I;
}
sub _Aside {
    $_[0] -> _I -> _FONT;
}

Now, you can do this:

my $HTML = new MY::HTML \*STDOUT;

$HTML -> Aside
      -> t("Don't drink the milk, it's spoiled... pass it on...")
      -> _Aside;

If you're defining these markup-like, chocolate-interface-style functions, I recommend using mixed case with a leading capital. You probably shouldn't use all-uppercase, since that's what this module uses for real HTML tags.

💅 PUBLIC INTERFACE 💅

okay bestie, this is the part where we actually learn the moves. the API. the whole vibe. grab a snack. 🍓

---

✨ Functions ✨

these are plain ol' functions, not methods — call them like html_escape($text) and go.

• html_escape TEXT — hand it a TEXT string and it turns it into valid HTML by escaping the "unsafe" characters. right now "unsafe" means 8-bit characters plus these lil guys:

<  >  =  &

Note: this one's here for convenience and backwards-compatibility only. if you want the actual good stuff, you probably wanna use the more-powerful HTML::Entities::encode function instead. 💖

• html_tag TAG [, PARAM=>VALUE, ...] — returns the text for a given TAG, and yeah you can throw parameters at it too. quick heads up though: as an efficiency hack, only the values get HTML-escaped right now — it just assumes the tag and the parameters are already safe. (it trusts you. don't make it regret that. 🙈)

and for convenience + readability, you can say "_A" instead of "/A" for the first tag, if you're into barewords like that.

• html_unescape TEXT — strips the angle-tag markup out, and converts the standard ampersand-escapes ("lt", "gt", "amp", "quot", and "#ddd") back into ASCII characters.

Note: again, convenience and backwards-compatibility only. you may wanna reach for the more-powerful HTML::Entities::decode function instead — because unlike this one, it can collapse entities like "copy" and "ccedil" into their Latin-1 byte values. this function? cannot. not its fault. it's just built different. 💀

• html_unmarkup TEXT — removes angle-tag markup from TEXT, but does not convert ampersand-escapes. it's cheesy, ngl, but theoretically useful if you wanna, say, take externally-provided HTML and shove it into a page you're generating, and you're lowkey worried that the HTML might contain some undesirable markup. 🧚

---

🌸 Vanilla 🌸

the basic flavour. the starter pack. everything you need to be a normal, well-adjusted HTML-generating girlie.

• new [PRINTABLE] — class method. creates a brand new HTML output stream. 🎀

the PRINTABLE can be a FileHandle, a glob reference, or literally any object that responds to a print() message. and if you don't pass a PRINTABLE at all? it does a select() and uses whatever that gives back. easy.

• auto_escape [NAME|SUBREF] — instance method. sets the auto-escape function for this HTML stream.

if the argument is a subroutine reference SUBREF, then that subroutine is what gets used. declare those subroutines like this:

sub my_escape {
    my $text = shift;     # it's passed in the first argument
    ...
    $text;
}

and if you give it a textual NAME instead, then one of the appropriate built-in functions gets used. the possible values are:

• ALL — the default for HTML::Stream objects. escapes angle brackets, ampersands, double-quotes, and 8-bit characters. the 8-bit characters get escaped using decimal entity codes (like "#123").
• LATIN_1 — like "ALL", but it uses Latin-1 entity names (like "ccedil") instead of decimal entity codes to escape characters. this makes the HTML more readable, but it's currently not advised, because "older" browsers (like Netscape 2.0, bless their heart) don't recognize many of the ISO-8859-1 entity names (like "deg").

Warning: if you specify this option, you'll find that it attempts to "require" HTML::Entities at run time. that's because the author didn't wanna force you to have that module just to use the rest of HTML::Stream. to pick up problems at compile time, you are advised to say:

use HTML::Stream;
use HTML::Entities;

in your source code.

• NON_ENT — like "ALL", except ampersands (&) are not escaped. this lets you use &-entities in your text strings while everything else stays safely escaped:

output $HTML "If A is an acute angle, then A > 90°";

it returns the previously-installed function, in the manner of "select()". and no arguments at all just returns the currently-installed function. 👑

• auto_format ONOFF — instance method. sets the auto-formatting characteristics for this HTML stream. currently all you can do is supply a single defined boolean argument, which turns auto-formatting ON (1) or OFF (0). the self object gets returned.

please use no other values; they are reserved for future use. don't be messy. 🙏

• comment COMMENT — instance method. outputs an HTML comment. and as of 1.29, a newline is automatically appended. no extra work required, bestie. ✨
• ent ENTITY — instance method. outputs an HTML entity. for example, here's how you'd output a non-breaking space:

  $html->ent('nbsp');

you may abbreviate this method name as "e":

  $html->e('nbsp');

Warning: this function assumes that the entity argument is legal. it does not check. it trusts. 🫶

• io — returns the underlying output handle for this HTML stream. all you can depend upon is that it's some kind of object which responds to a print() message:

    $HTML->io->print("This is not auto-escaped or nuthin!");

• nl [COUNT] — instance method. outputs COUNT newlines. if it's undefined, COUNT defaults to 1.
• tag TAGNAME [, PARAM=>VALUE, ...] — instance method. outputs a tag. returns the self object so you can chain methods like the icon you are. and yes, you can say "_A" instead of "/A", if you're into barewords. 💅
• text TEXT... — instance method. outputs some text. you may abbreviate this method name as "t":

  $html->t('Hi there, ', $yournamehere, '!');

returns the self object, to allow method chaining.

• text_nbsp TEXT... — instance method. outputs some text, but with all spaces output as non-breaking-space characters:

  $html->t("To list your home directory, type: ")
       ->text_nbsp("ls -l ~yourname.")

returns the self object, to allow method chaining. look at that chaining. gorgeous. 🔥

---

🍓 Strawberry 🍓

a lil fruity, a lil extra, and honestly so worth it.

• output ITEM,...,ITEM — instance method. goes through the items one by one. if an item is an arrayref, it treats it like the array argument to html_tag() and outputs the result. if an item is a text string, it escapes the text and outputs the result. like this:

   output $HTML [A, HREF=>$url], "Here's my $caption!", [_A];

one line, whole vibe, done. 😭✨

---

🍫 Chocolate 🍫

the rich one. this is where tags become methods and everything gets kinda magical.

• accept_tag TAG — class method. declares that the tag is to be accepted as valid HTML (if it isn't already). for example, this...

   # Make sure methods MARQUEE and _MARQUEE are compiled on demand:
   HTML::Stream->accept_tag('MARQUEE');

...gives the Chocolate Interface permission to create (via AUTOLOAD) definitions for the MARQUEE and _MARQUEE methods, so you can then say:

   $HTML -> MARQUEE -> t("Hi!") -> _MARQUEE;

and if you wanna set the default attribute of the tag as well, you can do that via the set_tag() method instead — it'll effectively do an accept_tag() as well.

   # Make sure methods MARQUEE and _MARQUEE are compiled on demand,
   #   *and*, set the characteristics of that tag.
   HTML::Stream->set_tag('MARQUEE', Newlines=>9);

• private_tags — instance method. normally, HTML streams use a reference to a global table of tag information to figure out how to do stuff like auto-formatting, and any modifications made to that table by "set_tag" will affect everyone. sharing is caring except when it's chaos.

but if you want an HTML stream to have its own private copy of that table to munge with, just send it this message after creating it. like this:

    my $HTML = new HTML::Stream \*STDOUT;
    $HTML->private_tags;

then you can say stuff like:

    $HTML->set_tag('PRE',   Newlines=>0);
    $HTML->set_tag('BLINK', Newlines=>9);

and it won't affect anyone else's auto-formatting (although they will possibly be able to use the BLINK tag method without a fatal exception ":-(" ).

returns the self object.

• set_tag TAG, [TAGINFO...] — class/instance method. accepts the given TAG in the Chocolate Interface, and (if TAGINFO is given) alters its characteristics when being output.
  • if invoked as a class method, this alters the "master tag table", and allows a new tag to be supported via an autoloaded method:

     HTML::Stream->set_tag('MARQUEE', Newlines=>9);

once you do this, all HTML streams you open from then on will allow that tag to be output in the chocolate interface.

• if invoked as an instance method, this alters the "tag table" referenced by that HTML stream — usually for the purpose of affecting things like the auto-formatting on that HTML stream.

Warning: by default, an HTML stream just references the "master tag table" (this makes "new()" more efficient), so by default, the instance method will behave exactly like the class method. 💀

     my $HTML = new HTML::Stream \*STDOUT;
     $HTML->set_tag('BLINK', Newlines=>0);  # changes it for others!

if you want to diddle with one stream's auto-formatting only, you'll need to give that stream its own private tag table. like this:

     my $HTML = new HTML::Stream \*STDOUT;
     $HTML->private_tags;
     $HTML->set_tag('BLINK', Newlines=>0);  # doesn't affect other streams

Note: this will still force an default entry for BLINK in the master tag table — otherwise, we'd never know that it was legal to AUTOLOAD a BLINK method. however, it will only alter the characteristics of the BLINK tag (like auto-formatting) in the object's tag table.

the TAGINFO, if given, is a set of key=>value pairs with the following possible keys:

Newlines

assumed to be a number which encodes how newlines are to be output before/after a tag. the value is the logical OR (or sum) of a set of flags:

     0x01    newline before <TAG>         .<TAG>.     .</TAG>.
     0x02    newline after <TAG>          |     |     |      |
     0x04    newline before </TAG>        1     2     4      8
     0x08    newline after </TAG>

hence, to output BLINK environments which are preceded/followed by newlines:

     set_tag HTML::Stream 'BLINK', Newlines=>9;

returns the self object on success. 🫶

• tags — class/instance method. returns an unsorted list of all tags in the class/instance tag table (see "set_tag" for class/instance method differences). 🌈

---

✨ SUBCLASSES ✨

🌸 HTML::Stream::Latin1 🌸

okay so this one is a tiny little public package for outputting Latin-1 markup, and its whole personality is that its default auto-escape function is LATIN_1 💅 which tries to spit out the mnemonic entity markup (like, ç and friends) for ISO-8859-1 characters. cute, right?

So using HTML::Stream::Latin1 like this:

use HTML::Stream;

$HTML = new HTML::Stream::Latin1 \*STDOUT;
output $HTML "\253A right angle is 90\260, \277No?\273\n";

Prints this:

«A right angle is 90°, ¿No?»

Instead of what HTML::Stream would print, which is this:

«A right angle is 90°, ¿No?»

Warning: a lot of Latin-1 HTML markup is not recognized by older browsers (e.g., Netscape 2.0 😭). Consider using HTML::Stream; it will output the decimal entities which currently seem to be more "portable".

Note: using this class "requires" that you have HTML::Entities. no HTML::Entities, no mnemonic cuteness, bestie. 🫶

---

🐌 PERFORMANCE 🐌

Slower than I'd like. ngl. 😭 Both the output() method and the various "tag" methods seem to run about 5 times slower than the old just-hardcode-the-darn stuff approach. That is, in general, this:

### Approach #1...
tag  $HTML 'A', HREF=>"$href";
tag  $HTML 'IMG', SRC=>"logo.gif", ALT=>"LOGO";
text $HTML $caption;
tag  $HTML '_A';
text $HTML $a_lot_of_text;

And this:

### Approach #2...
output $HTML [A, HREF=>"$href"],
             [IMG, SRC=>"logo.gif", ALT=>"LOGO"],
             $caption,
             [_A];
output $HTML $a_lot_of_text;

And this:

### Approach #3...
$HTML -> A(HREF=>"$href")
      -> IMG(SRC=>"logo.gif", ALT=>"LOGO")
      -> t($caption)
      -> _A
      -> t($a_lot_of_text);

Each run about 5x slower than this:

### Approach #4...
print '<A HREF="', html_escape($href), '>',
      '<IMG SRC="logo.gif" ALT="LOGO">',
      html_escape($caption),
      '</A>';
print html_escape($a_lot_of_text);

Of course, I'd much rather use any of first three (especially #3) if I had to get something done right in a hurry. Or did you not notice the typo in approach #4? ";-)" 😏

(BTW, thanks to Benchmark:: for allowing me to... er... benchmark stuff.) 💖

---

🎀 VERSION 🎀

$Id: Stream.pm,v 1.60 2008/08/06 dstaal Exp $

---

📜 CHANGE LOG 📜

Version 1.60 (2008/08/06)

Fixed up the tests some more, updated changelog. (Which I'd forgotten about... 🙈)

Version 1.59 (2008/06/01)

Better tests, better Meta.yml. ✨

Version 1.58 (2008/05/28)

Another attempt at cleanup, as well expanding the Meta.yml file.

Version 1.57 (2008/05/28)

Cleaned up the Mac-specific files that were getting created in the archive. 🍎

Version 1.56 (2008/05/27)

Added the start of a testing suite. In the process, I found an error: HTML defines the tag 'NOFRAMES', not 'NOFRAME'. Both are currently in the tag list, but consider 'NOFRAME' depriciated.

The test suite requires Test::More and Test::Output.

Version 1.55 (2003/10/28)

New maintainer: Daniel T. Staal. No major changes in the code, except to complete the tag list to HTML 4.01 specifications. (With the exception of the 'S' tag, which I want to test, and is depreciated anyway. Note that the DOCTYPE is not actually a HTML tag, and is not currently included.)

Version 1.54 (2001/08/20)

The terms-of-use have been placed in the distribution file "COPYING". Also, small documentation tweaks were made.

Version 1.51 (2001/08/16)

No real changes to code; just improved documentation, and removed HTML::Entities and HTML::Parser from ./etc at CPAN's request.

Version 1.47 (2000/06/10)

No real changes to code; just improved documentation.

Version 1.45 (1999/02/09)

Cleanup for Perl 5.005: removed duplicate typeglob assignments.

Version 1.44 (1998/01/14)

Win95 install (5.004) now works. Added SYNOPSIS to POD.

Version 1.41 (1998/01/02)

Removed $& for efficiency. Thanks, Andreas!

Added support for OPTION, and default now puts newlines after SELECT and /SELECT. Also altered "TELEM" syntax to put newline after end-tags of list element tags (like /OPTION, /LI, etc.). In theory, this change could produce undesirable results for folks who embed lists inside of PRE environments... however, that kind of stuff was done in the days before TABLEs; also, you can always turn it off if you really need to. Thanks to John D Groenveld for these patches.

Added text_nbsp(). Thanks to John D Groenveld for the patch. This method may also be invoked as nbsp_text() as in the original patch, but that's sort of a private tip-of-the-hat to the patch author, and the synonym may go away in the future. 👀

Version 1.37 (1997/02/09)

No real change; just trying to make CPAN.pm happier. 😌

Version 1.32 (1997/01/12)

NEW TOOL for generating Perl code which uses HTML::Stream! Check your toolkit for html2perlstream. 🔥

Added built-in support for escaping 8-bit characters.

Added "LATIN_1" auto-escape, which uses HTML::Entities to generate mnemonic entities. This is now the default method for HTML::Stream::Latin1.

Added "auto_format()," so you can now turn auto-formatting off/on.

Added "private_tags()", so it is now possible for HTML streams to each have their own "private" copy of the %Tags table, for use by "set_tag()".

Added "set_tag()". The tags tables may now be modified dynamically so as to change how formatting is done on-the-fly. This will hopefully not compromise the efficiency of the chocolate interface (until now, the formatting was compiled into the method itself), and will add greater flexibility for more-complex programs. 🍫

Added POD documentation for all subroutines in the public interface.

Version 1.29 (1996/12/10)

Added terminating newline to comment(). Thanks to John D Groenveld for the suggestion and the patch.

Version 1.27 (1996/12/10)

Added built-in HTML::Stream::Latin1, which does a very simple encoding of all characters above ASCII 127.

Fixed bug in accept_tag(), where 'my' variable was shadowing argument. Thanks to John D Groenveld for the bug report and the patch.

Version 1.26 (1996/09/27)

Start of history. 🌱

---

⚖️ COPYRIGHT ⚖️

This program is free software. You may copy or redistribute it under the same terms as Perl itself. 🫶

---

💖 ACKNOWLEDGEMENTS 💖

Warmest thanks to...

Eryq                   For writing the original version of this module.

John Buckman           For suggesting that I write an "html2perlstream",
                       and inspiring me to look at supporting Latin-1.
Tony Cebzanov          For suggesting that I write an "html2perlstream"
John D Groenveld       Bug reports, patches, and suggestions
B. K. Oxley (binkley)  For suggesting the support of "writing to strings"
                       which became the "printable" interface.

like, absolute legends, every single one of them 👑✨

---

👑 AUTHOR 👑

Daniel T. Staal (DStaal@usa.net).

Enjoy. Yell if it breaks. 😤💅

---

and that's the whole page bestie!! 🌈 this lil number came from perl v5.34.0, dated 2022-06-14, and it's HTML::Stream(3pm) — go forth and stream your HTML, you absolute icon 🎀🦋💖