Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTML::Stream(3)	      User Contributed Perl Documentation      HTML::Stream(3)

NAME
       HTML::Stream - HTML output stream class,	and some markup	utilities

SYNOPSIS
       Here's small sample of some of the non-OO ways you can use this module:

	     use HTML::Stream qw(:funcs);

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

       And some	of the OO ways as well:

	     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];

DESCRIPTION
       The HTML::Stream	module provides	you with an object-oriented (and
       subclassable) way of outputting HTML.  Basically, you open up an	"HTML
       stream" on an existing filehandle, and then do all of your output to
       the HTML	stream.	 You can intermix HTML-stream-output and ordinary-
       print-output, if	you like.

       There's even a small built-in subclass, HTML::Stream::Latin1, which can
       handle Latin-1 input right out of the box.   But	all in good time...

INTRODUCTION (the Neapolitan dessert special)
   Function interface
       Let's start out with the	simple stuff.  This module provides a
       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 '&copy; 1996 by', html_escape($myname), '!';
	   print html_tag('/A');

       By the way: that	last line could	be rewritten as:

	   print html_tag(_A);

       And if you need to get a	parameter in your tag that doesn't have	an
       associated value, supply	the undefined value (not the empty string!):

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

		<TD NOWRAP ALIGN=LEFT>

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

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

       There are also some routines for	reversing the 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	be tedious... so we also provide an
       "HTML output stream" class.  Messages to	an instance of that class
       generally tell that stream to output some HTML.	Here's the above
       example,	rewritten using	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);

       As you've probably guessed:

	   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 &copy; or &lt; .
		    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...

   OO interface, chocolate
       The known HTML tags are even given their	own tag-methods, compiled on
       demand.	The above code could be	written	even more compactly as:

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

       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.
       A "_" prefix on any tag-method means that an end-tag is desired.	 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.

       o   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, 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".  I	thought	and thought
       about it, and could not convince	myself 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.

   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) 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
       I was jealous of	the compact syntax of HTML::AsSubs, but	I 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 I 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()".

ADVANCED TOPICS
   Auto-formatting and inserting newlines
       Auto-formatting is the name I give to the Chocolate Interface feature
       whereby newlines	(and maybe, in the future, other things) are inserted
       before or after the tags	you output in order to make your HTML 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...

       o   Sometimes you'll be outputting stuff	inside a "PRE" environment.

       o   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\)/&copy;/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
   Functions
       html_escape TEXT
	   Given a TEXT	string,	turn the text into valid HTML by escaping
	   "unsafe" characters.	 Currently, the	"unsafe" characters are	8-bit
	   characters plus:

	       <  >  =	&

	   Note: provided for convenience and backwards-compatibility only.
	   You may want	to use the more-powerful HTML::Entities::encode
	   function instead.

       html_tag	TAG [, PARAM=>VALUE, ...]
	   Return the text for a given TAG, possibly with parameters.  As an
	   efficiency hack, only the values are	HTML-escaped currently:	it is
	   assumed that	the tag	and parameters will already be safe.

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

       html_unescape TEXT
	   Remove angle-tag markup, and	convert	the standard ampersand-escapes
	   ("lt", "gt",	"amp", "quot", and "#ddd") into	ASCII characters.

	   Note: provided for convenience and backwards-compatibility only.
	   You may want	to use the more-powerful HTML::Entities::decode
	   function instead: unlike this function, it can collapse entities
	   like	"copy" and "ccedil" into their Latin-1 byte values.

       html_unmarkup TEXT
	   Remove angle-tag markup from	TEXT, but do not convert ampersand-
	   escapes.  Cheesy, but theoretically useful if you want to, say,
	   incorporate externally-provided HTML	into a page you're generating,
	   and are worried that	the HTML might contain undesirable markup.

   Vanilla
       new [PRINTABLE]
	   Class method.  Create a new HTML output stream.

	   The PRINTABLE may be	a FileHandle, a	glob reference,	or any object
	   that	responds to a "print()"	message.  If no	PRINTABLE is given,
	   does	a select() and uses that.

       auto_escape [NAME|SUBREF]
	   Instance method.  Set the auto-escape function for this HTML
	   stream.

	   If the argument is a	subroutine reference SUBREF, then that
	   subroutine will be used.  Declare such subroutines like this:

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

	   If a	textual	NAME is	given, then one	of the appropriate built-in
	   functions is	used.  Possible	values are:

	   ALL Default for HTML::Stream	objects.  This escapes angle brackets,
	       ampersands, double-quotes, and 8-bit characters.	 8-bit
	       characters are escaped using decimal entity codes (like
	       "#123").

	   LATIN_1
	       Like "ALL", but uses Latin-1 entity names (like "ccedil")
	       instead of decimal entity codes to escape characters.  This
	       makes the HTML more readable but	it is currently	not advised,
	       as "older" browsers (like Netscape 2.0) do not 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 I didn't	want to	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 that ampersands (&) are not escaped.	This
	       allows you to use &-entities in your text strings, while	having
	       everything else safely escaped:

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

	   Returns the previously-installed function, in the manner of
	   "select()".	No arguments just returns the currently-installed
	   function.

       auto_format ONOFF
	   Instance method.  Set 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 is returned.

	   Please use no other values; they are	reserved for future use.

       comment COMMENT
	   Instance method.  Output an HTML comment.  As of 1.29, a newline is
	   automatically appended.

       ent ENTITY
	   Instance method.  Output 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.

       io  Return the underlying output	handle for this	HTML stream.  All you
	   can depend upon is that it is some kind of object which responds to
	   a print() message:

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

       nl [COUNT]
	   Instance method.  Output COUNT newlines.  If	undefined, COUNT
	   defaults to 1.

       tag TAGNAME [, PARAM=>VALUE, ...]
	   Instance method.  Output a tag.  Returns the	self object, to	allow
	   method chaining.  You can say "_A" instead of "/A", if you're into
	   barewords.

       text TEXT...
	   Instance method.  Output 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.  Output 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.

   Strawberry
       output ITEM,...,ITEM
	   Instance method.  Go	through	the items.  If an item is an arrayref,
	   treat it like the array argument to html_tag() and output the
	   result.  If an item is a text string, escape	the text and output
	   the result.	Like this:

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

   Chocolate
       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;

	   If you want to set the default attribute of the tag as well,	you
	   can do so via the set_tag() method instead; it will 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 determine	how to do such things
	   as auto-formatting, and modifications made to that table by
	   "set_tag" will affect everyone.

	   However, if you want	an HTML	stream to have a 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.  Accept the given TAG	in the Chocolate
	   Interface, and (if TAGINFO is given)	alter its characteristics when
	   being output.

	   o   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.

	   o   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
       A small,	public package for outputting Latin-1 markup.  Its default
       auto-escape function is "LATIN_1", which	tries to output	the mnemonic
       entity markup (e.g., "&ccedil;")	for ISO-8859-1 characters.

       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:

	   &laquo;A right angle	is 90&deg;, &iquest;No?&raquo;

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

	   &#171;A right angle is 90&#176;, &#191;No?&#187;

       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.

PERFORMANCE
       Slower than I'd like.  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 undesireable 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 orginal 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.

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

       Enjoy.  Yell if it breaks.

perl v5.32.1			  2008-08-07		       HTML::Stream(3)

NAME | SYNOPSIS | DESCRIPTION | INTRODUCTION (the Neapolitan dessert special) | ADVANCED TOPICS | PUBLIC INTERFACE | SUBCLASSES | PERFORMANCE | VERSION | CHANGE LOG | COPYRIGHT | ACKNOWLEDGEMENTS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTML::Stream&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help