HTML-Stream-1.60/0000755000076600001200000000000011046441050013743 5ustar danieltstaaladminHTML-Stream-1.60/bin/0000755000076600001200000000000011046441050014513 5ustar danieltstaaladminHTML-Stream-1.60/bin/html2perlstream0000755000076600001200000002576007337065070017614 0ustar danieltstaaladmin#!/usr/bin/perl -w =head1 NAME html2perlstream - convert an HTML document to Perl code for that document =head1 SYNOPSIS html2perlstream html2perlstream [options] - html2perlstream [options] file.html .. file.html =head1 DESCRIPTION Takes an HTML file, and produces from it a Perl script that will generate that HTML using the L module. For usage, just say: html2perlstream The normal form is: html2perlstream [-options] [files] Any named HTML input file F will cause output script F to be generated. To read from the standard input, specify '-', like this: html2perlstream - < test.html If reading from the standard input, the output Perl code goes to the standard output. So if you want to run it right away to see the output, just do this: html2perlstream - < test.html | perl =head1 OPTIONS =over 4 =item B<-d> Automatically load and run the output Perl file, then do a diff on that and the input file (you must input from a file and output to a file in order to use this). html2perlstream -w -d testin/test.html You'll get fewer differences if you build the code with C<-w>. =item B<-w> Try to generate code which will output all whitespace between tags verbatim. The default code only outputs whitespace if it is believed to be needed; e.g., if we are inside a C
 environment.

=back


=head1 REQUIRES

To run this, you need:

   HTML::Entities
   HTML::Parser


=head1 VERSION

$Id: html2perlstream,v 1.10 2001/08/17 00:50:00 eryq Exp $


=head1 AUTHOR

Eryq, 11 Jan 1997, F or thereabouts.

Thanks (independently) to Tony Cebzanov and John Buckman for suggesting 
that I write a tool like this.

=cut

# Try this: 
#
# perl -I. bin/html2perlstream -w testin/test.html;
# perl -I. testin/test.html.pl > testin/test2.html 
# diff testin/test.html testin/test2.html

use HTML::Parser;
use HTML::Entities;
use Getopt::Std;
use FileHandle;

use strict;
use vars qw($VERSION 
	    $opt_d 
	    $opt_w
	    );

#------------------------------------------------------------
#
# Globals...
#
#------------------------------------------------------------

# Version...
( $VERSION ) = '$Revision: 1.10 $ ' =~ /\$Revision:\s+([^\s]+)/;

# Escape-map:
my %PerlUnescape = (
		    "\b"=>'b',
		    "\f"=>'f',
		    "\r"=>'r',
		    "\t"=>'t',
		    "\n"=>'n',
		    );
my $PerlEscapePat = join('',keys(%PerlUnescape));

#------------------------------------------------------------
# str2perl STRING,[QUOTECHAR]
#------------------------------------------------------------
# Convert a string to a double-quoted Perl string.
# Unsafe characters and non-printables are escaped.
#
# If QUOTECHAR is nonempty (default is '"'), it is escaped and also 
# wrapped around the string.

sub str2perl {
    my ($str, $qq) = @_;
    defined($qq) or $qq = '"';

    $str =~ s/[\\\$\@]/\\$&/g;                           # unsafe
    $str =~ s/$qq/\\$qq/g          if $qq;               # quote char
    $str =~ s/[$PerlEscapePat]/\\$PerlUnescape{$&}/og;   # newlines, tabs...
    $str =~ s/[\x00-\x1F\x7F-\xFF]/sprintf("\\x%02X", ord($&))/eg;
    "$qq$str$qq";
}



#============================================================
package Main::Parser;
#============================================================

use HTML::Stream qw(:funcs);
use vars qw(@ISA);

@ISA = (qw(HTML::Parser));


# Are we inside a preformatter environment?
my $PREcount = 0;

#------------------------------------------------------------
# declaration
#------------------------------------------------------------
# This method is called when a markup declaration has been
# recognized. For typical HTML documents, the only declaration you are 
# likely to find is . The initial ``'' 
# is not part of the string passed as argument. Comments
# are removed and entities have not been expanded yet. 

sub declaration {
    my ($self, $decl) = @_;    

    print '$HTML->io->print(', ::str2perl(""), ");\n";
}

#------------------------------------------------------------
# start
#------------------------------------------------------------
# This method is called when a complete start tag has been
# recognized. The first argument is the tag name (in lower case)
# and the second argument is a reference to a hash that contain
# all attributes found within the start tag. The attribute keys
# are converted to lower case. Entities found in the attribute
# values are already expanded.

sub start {
    my ($self, $tag, $attr) = @_;
 
    # Bookkeeping:
    ++$PREcount if ($tag eq 'pre');

    # Output:
    if (keys %$attr) {

	# Output and remember first line, up to open paren:
	my $firstline = "\$HTML -> \U$tag\E(";
	print $firstline;

	# Determine nice indent:
	my $indent =  ' ' x length($firstline);
	$indent =~ s/ {8}/\t/g;

	# Output tag params:
	my @keys = sort keys %$attr;
	my $i;
	for ($i = 0; $i < int(@keys); $i++) {
	    print "\U$keys[$i]\E => ";
	    print ::str2perl($attr->{$keys[$i]});
	    print ",\n$indent" unless ($i == (int(@keys)-1));
	}
	print ");\n";
    }
    else {
	print "\$HTML -> \U$tag\E;\n";
    }
}

#------------------------------------------------------------
# end
#------------------------------------------------------------
# This method is called when an end tag has been recognized. 
# The argument is the lower case tag name. 

sub end {
    my ($self, $tag) = @_;
    print "\$HTML -> _\U$tag\E;\n";

    # Bookkeeping:
    --$PREcount if ($tag eq 'pre');
}


#------------------------------------------------------------
# should_output_whitespace
#------------------------------------------------------------
sub should_output_whitespace {
    $::opt_w || ($PREcount > 0);
}

#------------------------------------------------------------
# whitespace
#------------------------------------------------------------
sub whitespace {
    my $ws = shift;
    
    return if (!$ws);
    if ($ws =~ /\A\n*\Z/) {
	print "\$HTML -> nl";
	print( (length($ws) > 1) ? '('.length($ws).')' : '');
	print ";\n";
    }
    else {
	print "\$HTML -> t(", ::str2perl($ws), ");\n";
    }    
}

#------------------------------------------------------------
# text
#------------------------------------------------------------
# This method is called as plain text in the document
# is recognized. The text is passed on unmodified and might contain
# multiple lines. Note that for efficiency reasons entities in the
# text are not expanded. You should call
# HTML::Entities::decode($text) before you process the text any
# further.

sub text {
    my ($self, $text) = @_;

    # Do nothing if empty string:
    return if (!defined($text) or ($text eq ''));

    # Unescape HTML:
    $text = HTML::Entities::decode($text);

    # Break into WHITE* NONWHITE* WHITE*
    my ($pre, $in, $dummy, $post) = ($text =~ /\A(\s*)((.|\n)*?)(\s*)\Z/);

    # Output leading whitespace:
    if ($pre && should_output_whitespace()) {
	whitespace($pre);
    }

    # Output main text:
    if (defined($in) && ($in ne '')) {
	if (length($in) < 70) {    # output as t()
	    print "\$HTML -> t(", ::str2perl($in), ");\n";
	}
	else {     # output as hereis()
	    my $hereis = ::str2perl($in, '');
	    $hereis =~ s/\\n/\n/g;

	    print "output \$HTML < comment(", ::str2perl($comment), ");\n";
}


#============================================================
package main;
#============================================================

#------------------------------------------------------------
# print_header
#------------------------------------------------------------
sub print_header {
    print <auto_format(0);
EOF
    }
    else {
	print <auto_format(0);
EOF
    }

    print <flush;
    STDERR->flush;

    # Do it!
    my $cmd = join(' ', ($^X, (map {"-I$_"} @INC), $perlfile));
    # print STDERR "diff command = $cmd\n";
    print STDERR "    Running code: output in $html2\n";
    system "$cmd > $html2";
    print STDERR "    Doing diff:   output in $diff\n";
    system "diff $htmlfile $html2 > $diff";
}

#------------------------------------------------------------
# main
#------------------------------------------------------------
sub main {
    my $parser = new Main::Parser;

    # Usage if no args:
    @ARGV or usage();

    # Get opts:
    getopts "wd";
    
    # Process files:
    @ARGV or unshift @ARGV, '-';
    my $infile;
    while ($infile = shift @ARGV) {
	my $outfile = (($infile eq '-') ? '-' : "$infile.pl");

	# Trap for bad -d usage:
	if ($opt_d and (($infile eq '-') || ($outfile eq '-'))) {
	    die "Cannot use -d if input is from STDIN\n";
	}

	# Report:
	print STDERR "Converting ", ($infile  eq '-' ? '' : $infile),
	             " to "       , ($outfile eq '-' ? '' : $outfile),
	             "\n";

	# Open input and output:
	open INPUT,  "<$infile" or die "$infile: $!";
	open OUTPUT, ">$outfile" or die "$outfile: $!";
	select OUTPUT;

	# Header:
	print_header();
	$parser->parse_file(\*INPUT);
	
	# Footer:
	print_footer();

	# Close:
	close OUTPUT;
	close INPUT;
	
	# Do a diff...
	do_diff($infile, $outfile) if ($opt_d);
	
    }
    print STDERR "Done.\n";
    1;
}
exit (&main ? 0 : -1);

#------------------------------------------------------------
1;
HTML-Stream-1.60/Changes0000644000076600007660000001030511046440635016642 0ustar  danieltstaaldanieltstaalCHANGE 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.HTML-Stream-1.60/COPYING0000644000076600001200000000370110000052601014764 0ustar  danieltstaaladminThe "HTML-Stream" Perl5 toolkit.

Copyright (c) 1996 by Eryq.  All rights reserved.
Copyright (c) 1999 by ZeeGee Software Inc.  All rights reserved.
Copyright (c) 2004 by Daniel Staal.  All rights reserved.

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

You should have received a copy of the Perl license along with
Perl; see the file README in Perl distribution.

You should have received a copy of the GNU General Public License
along with Perl; see the file Copying.  If not, write to
the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

You should have received a copy of the Artistic License
along with Perl; see the file Artistic.

			    NO WARRANTY

BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "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 PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM 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 PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (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 PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

		     END OF TERMS AND CONDITIONS
HTML-Stream-1.60/docs/0000755000076600001200000000000011046441050014673 5ustar  danieltstaaladminHTML-Stream-1.60/docs/giggles.html0000644000076600001200000000066107340272077017222 0ustar  danieltstaaladmin

  


ZeeGee Software


Generated Mon Aug 20 16:34:07 2001 by cvu_pod2html
HTML-Stream-1.60/docs/HTML/0000755000076600001200000000000011046441050015437 5ustar danieltstaaladminHTML-Stream-1.60/docs/HTML/icons/0000755000076600001200000000000011046441050016552 5ustar danieltstaaladminHTML-Stream-1.60/docs/HTML/icons/h1bullet.gif0000644000076600001200000000064507340272052020774 0ustar danieltstaaladminGIF87a`Lx(hxXPH@@$XPP888Z.<ɔ)7n:1fNEK)3FD_ߊ*بQFK6JnM.+?t3hN!%ZhRC3/2 I*֫I<*P EPn9ڂxL-z2euQEKC j5JʚLd^#"2edAڶرrG3A`)Tujbۿ QOO{Kf}pȐʜ܁:y9F'c݁&H4? pQ0\@6(@2@PO`T@)L`=`htP PKr 0A 4y@?hpA`Lj@i X2PNd zD)J-zs@0Ld`*J(` "@):"`B#/6 P0A4XA  AfA 3`? ɑP( R "@S@N\p&< ` t 0l@#DR],YC_+db2˔R2|L )BM8L4DŹs j3t2L&PWR#0 5Ģ2mUXU|#G[O'@2"$@`0" %jV%Xpc\q cYshK0(TpR QP#eE Q /17^#cg9矀ȗ w&v͈a\pB͇ slS>sBOt~9][Рn`?x"  PR :.D]I  .F$#B,<a a7-}D&P:B8(  `7 `8p]yKQ/ HNT01"d%Dd J5rt36+\ $Qaa:@}#&`Em`WB@*S[8P pQRLR%L4xb x)pϘ )>ǐ8 A&gb#D@}S%= *uN0-#ܠ`YJ`̜-IE0û|":fX hѓ @AQe\p&BxE8 yG-U<-'≕(DTb,.+QLo n$ a8?Ce%1[%FXB jJb !EUF 8lмws cm L@Ҙbp$`-$AoAH`FpjUݭ1;}}0 rU*Q0-e[/l@p0dNb |qNʡ 3$F2NxV-m:ĠA x 3 tۣ)(' b k)\{Tc jDӱbދ [C1bxk&fxR<4ٸ0) Y)kbP<.Ȑepko} ᧍[ hCaъ0"ȭB4%+YFFX1([Yʬ0B< V8`ǼT|Y')l`TB @ 04:G$逖4@%+m`M074`D hv$XBJsh,EA<M4@] ocD5CQvkR 走 H@IBh@ؼ.*ڼҪcANĈ 4Y @v4[@J5 @Q"׈轀~B8;BJ_2IOS,-@jA?Uqvlֱ_$ j4"zQJ‖pC*5[+͕*~ՈA A8\9H?W#zoMG1Ƒ?š)P&0Pf,-/4p #!%Pf AhIN$a xM$X!7 a)Hp:21 M6HW U ސ $9 eP `πP# [@3\q3 % F2>a @36a@ h ` 0 S J3QDq: p P5S6Zݠ  ڐ)QYOUHa F /8 ;EY=] 01hSPPSL qA7@ 8! ʠ6=\q6^q $?4p4WzU aS@8\ ;qp Q SҘ S5\]@#bP]5`;BE6g a` C( OZyWI tbPx>E6gVS6a\2 TU0U@u=vc0]50a  pQ 9Z7 X\e׀16!T "n> O u2vQUWZ5XU0 j H6=)>U>Ոs˨Qpn:v4 p_ӓ򱖸<(Ӱ ư4#VU: e@ 9D+fo`2c ^[^P]0  7u[sf ` Ba ˰m@  z]E69P9Y<[1R9MذSSP0 j b(TA]g]Ƒ/R26^Cߠ!ו C/Z6V1`kIʡ93ccy  P 1@ݰ $ J`Z` ЊZ* 5`ڪ Z1"#  vPtv@c7I2bR#2hq* | $pPBw&B"BZ>Wj7 `/&Jvkrw2$nl*d/dt0 yjFi. {p!6$0tė4rw(w?hh6 @m? ~2v'x%[U)N$괹r!f/P,FC@iTBM+$nJd+$z2Ztv&ƺizes(H.’0OW%0,vFq hҷr?7#I"x &&pI Vd#B(&7)`*p60P sW~@M[Z%˺(0 ĴsPд~W''x'xAF"rFWW2 f`j4z'òsm& 'XBs$ '5g heRL$qq{gW' #"h {(q˜Boi /2!v.Ch@u rϒA"-'  -/p17A6"/1+#ɢ$"㶙(.n( ?$#!bxrJ 2ʛ{jQPAh !|D.!f<8!@k.%\-h % ?c~{&.޺GG.AV%{,Ʋg FBq2I\gG܂ ` p0s-,z%1} wG"zTo&|q-vD jY$pЫD"F `lr) H̢Wu$pl;rBRxg2 zW|\s@%D;ǻEE "œ0zQ"J0ՂD"\4 ܇ ,B<${KB pR0lW&w hr, C$$ ;HTML-Stream-1.60/docs/HTML/Stream.pm.html0000644000076600001200000013643007340272063020212 0ustar danieltstaaladmin HTML::Stream 1.54 ZeeGee Software

HTML::Stream 1.54


Top NAME

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


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


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


Top INTRODUCTION (the Neapolitan dessert special)


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


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


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

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


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


Top 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().


Top ADVANCED TOPICS


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

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


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


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


Top 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";


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


Top PUBLIC INTERFACE


Top Functions

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

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

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

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


Top Vanilla

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

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

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

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

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

Top 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!");

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

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

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

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


Top Strawberry

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


Top Chocolate

Top 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);

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

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

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

Top 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).


Top SUBCLASSES


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


Top 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.)


Top VERSION

$Id: Stream.pm,v 1.54 2001/08/20 20:33:26 eryq Exp $


Top CHANGE LOG

Top Version 1.54 (2001/08/20)
The terms-of-use have been placed in the distribution file "COPYING". Also, small documentation tweaks were made.

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

Top Version 1.47 (2000/06/10)
No real changes to code; just improved documentation.

Top Version 1.45 (1999/02/09)
Cleanup for Perl 5.005: removed duplicate typeglob assignments.

Top Version 1.44 (1998/01/14)
Win95 install (5.004) now works. Added SYNOPSIS to POD.

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

Top Version 1.37 (1997/02/09)
No real change; just trying to make CPAN.pm happier.

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

Top Version 1.29 (1996/12/10)
Added terminating newline to comment(). Thanks to John D Groenveld for the suggestion and the patch.

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

Top Version 1.26 (1996/09/27)
Start of history.


Top ACKNOWLEDGEMENTS

Warmest thanks to...

    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.


Top AUTHOR

Eryq (eryq@zeegee.com). President, ZeeGee Software Inc. (http://www.zeegee.com).

Go to http://www.zeegee.com for the latest downloads and on-line documentation for this module.

Enjoy. Yell if it breaks.


Generated Mon Aug 20 16:33:54 2001 by cvu_pod2html
HTML-Stream-1.60/docs/html2perlstream.html0000644000076600001200000000764107340272074020730 0ustar danieltstaaladmin html2perlstream 1.10 ZeeGee Software

html2perlstream 1.10


Top NAME

html2perlstream - convert an HTML document to Perl code for that document


Top SYNOPSIS

    html2perlstream
    html2perlstream [options] -
    html2perlstream [options] file.html .. file.html


Top DESCRIPTION

Takes an HTML file, and produces from it a Perl script that will generate that HTML using the HTML::Stream module.

For usage, just say:

    html2perlstream

The normal form is:

    html2perlstream [-options] [files]

Any named HTML input file file.html will cause output script file.html.pl to be generated. To read from the standard input, specify '-', like this:

    html2perlstream - < test.html

If reading from the standard input, the output Perl code goes to the standard output. So if you want to run it right away to see the output, just do this:

    html2perlstream - < test.html | perl


Top OPTIONS

-d
Automatically load and run the output Perl file, then do a diff on that and the input file (you must input from a file and output to a file in order to use this).
    html2perlstream -w -d testin/test.html

You'll get fewer differences if you build the code with -w.

-w
Try to generate code which will output all whitespace between tags verbatim. The default code only outputs whitespace if it is believed to be needed; e.g., if we are inside a PRE environment.


Top REQUIRES

To run this, you need:

   HTML::Entities
   HTML::Parser


Top VERSION

$Id: html2perlstream,v 1.10 2001/08/17 00:50:00 eryq Exp $


Top AUTHOR

Eryq, 11 Jan 1997, eryq@zeegee.com or thereabouts.

Thanks (independently) to Tony Cebzanov and John Buckman for suggesting that I write a tool like this.


Generated Mon Aug 20 16:34:04 2001 by cvu_pod2html
HTML-Stream-1.60/docs/icons/0000755000076600001200000000000011046441050016006 5ustar danieltstaaladminHTML-Stream-1.60/docs/icons/h1bullet.gif0000644000076600001200000000064507340272077020237 0ustar danieltstaaladminGIF87a`Lx(hxXPH@@$XPP888Z.<ɔ)7n:1fNEK)3FD_ߊ*بQFK6JnM.+?t3hN!%ZhRC3/2 I*֫I<*P EPn9ڂxL-z2euQEKC j5JʚLd^#"2edAڶرrG3A`)Tujbۿ QOO{Kf}pȐʜ܁:y9F'c݁&H4? pQ0\@6(@2@PO`T@)L`=`htP PKr 0A 4y@?hpA`Lj@i X2PNd zD)J-zs@0Ld`*J(` "@):"`B#/6 P0A4XA  AfA 3`? ɑP( R "@S@N\p&< ` t 0l@#DR],YC_+db2˔R2|L )BM8L4DŹs j3t2L&PWR#0 5Ģ2mUXU|#G[O'@2"$@`0" %jV%Xpc\q cYshK0(TpR QP#eE Q /17^#cg9矀ȗ w&v͈a\pB͇ slS>sBOt~9][Рn`?x"  PR :.D]I  .F$#B,<a a7-}D&P:B8(  `7 `8p]yKQ/ HNT01"d%Dd J5rt36+\ $Qaa:@}#&`Em`WB@*S[8P pQRLR%L4xb x)pϘ )>ǐ8 A&gb#D@}S%= *uN0-#ܠ`YJ`̜-IE0û|":fX hѓ @AQe\p&BxE8 yG-U<-'≕(DTb,.+QLo n$ a8?Ce%1[%FXB jJb !EUF 8lмws cm L@Ҙbp$`-$AoAH`FpjUݭ1;}}0 rU*Q0-e[/l@p0dNb |qNʡ 3$F2NxV-m:ĠA x 3 tۣ)(' b k)\{Tc jDӱbދ [C1bxk&fxR<4ٸ0) Y)kbP<.Ȑepko} ᧍[ hCaъ0"ȭB4%+YFFX1([Yʬ0B< V8`ǼT|Y')l`TB @ 04:G$逖4@%+m`M074`D hv$XBJsh,EA<M4@] ocD5CQvkR 走 H@IBh@ؼ.*ڼҪcANĈ 4Y @v4[@J5 @Q"׈轀~B8;BJ_2IOS,-@jA?Uqvlֱ_$ j4"zQJ‖pC*5[+͕*~ՈA A8\9H?W#zoMG1Ƒ?š)P&0Pf,-/4p #!%Pf AhIN$a xM$X!7 a)Hp:21 M6HW U ސ $9 eP `πP# [@3\q3 % F2>a @36a@ h ` 0 S J3QDq: p P5S6Zݠ  ڐ)QYOUHa F /8 ;EY=] 01hSPPSL qA7@ 8! ʠ6=\q6^q $?4p4WzU aS@8\ ;qp Q SҘ S5\]@#bP]5`;BE6g a` C( OZyWI tbPx>E6gVS6a\2 TU0U@u=vc0]50a  pQ 9Z7 X\e׀16!T "n> O u2vQUWZ5XU0 j H6=)>U>Ոs˨Qpn:v4 p_ӓ򱖸<(Ӱ ư4#VU: e@ 9D+fo`2c ^[^P]0  7u[sf ` Ba ˰m@  z]E69P9Y<[1R9MذSSP0 j b(TA]g]Ƒ/R26^Cߠ!ו C/Z6V1`kIʡ93ccy  P 1@ݰ $ J`Z` ЊZ* 5`ڪ Z1"#  vPtv@c7I2bR#2hq* | $pPBw&B"BZ>Wj7 `/&Jvkrw2$nl*d/dt0 yjFi. {p!6$0tė4rw(w?hh6 @m? ~2v'x%[U)N$괹r!f/P,FC@iTBM+$nJd+$z2Ztv&ƺizes(H.’0OW%0,vFq hҷr?7#I"x &&pI Vd#B(&7)`*p60P sW~@M[Z%˺(0 ĴsPд~W''x'xAF"rFWW2 f`j4z'òsm& 'XBs$ '5g heRL$qq{gW' #"h {(q˜Boi /2!v.Ch@u rϒA"-'  -/p17A6"/1+#ɢ$"㶙(.n( ?$#!bxrJ 2ʛ{jQPAh !|D.!f<8!@k.%\-h % ?c~{&.޺GG.AV%{,Ʋg FBq2I\gG܂ ` p0s-,z%1} wG"zTo&|q-vD jY$pЫD"F `lr) H̢Wu$pl;rBRxg2 zW|\s@%D;ǻEE "œ0zQ"J0ՂD"\4 ܇ ,B<${KB pR0lW&w hr, C$$ ;HTML-Stream-1.60/docs/index-menu.html0000644000076600001200000000202407340272103017633 0ustar danieltstaaladmin perlmod
Overview
HTML::Stream

Programs
html2perlstream

Examples
giggles
latin

HTML-Stream-1.60/docs/index.html0000644000076600001200000000046207340272103016675 0ustar danieltstaaladmin perlmod <BODY> Go <A HREF="menu.html">here</A> </BODY> HTML-Stream-1.60/docs/index.menu0000644000076600001200000000033407340272101016671 0ustar danieltstaaladminMENU perlmod SECTION Overview ITEM HTML::Stream HREF HTML/Stream.pm.html SECTION Programs ITEM html2perlstream HREF html2perlstream.html SECTION Examples ITEM giggles HREF giggles.html ITEM latin HREF latin.html HTML-Stream-1.60/docs/latin.html0000644000076600001200000000126207340272101016672 0ustar danieltstaaladmin latin ZeeGee Software

latin


Top NAME

latin - just some example code using HTML::Stream::Latin1


Generated Mon Aug 20 16:34:09 2001 by cvu_pod2html
HTML-Stream-1.60/etc/0000755000076600001200000000000011046441050014516 5ustar danieltstaaladminHTML-Stream-1.60/etc/README0000644000076600001200000000034606615250440015410 0ustar danieltstaaladminThis directory (./etc) contains modules which the HTML::Stream toolkit might depend on. They are NOT automatically installed for you. You are encouraged to get newer copies of these modules from the CPAN (http://www.perl.com). HTML-Stream-1.60/examples/0000755000076600001200000000000011046441050015561 5ustar danieltstaaladminHTML-Stream-1.60/examples/giggles0000755000076600001200000000266007337073344017153 0ustar danieltstaaladmin#!/usr/bin/perl =head1 NAME giggles - just some example code using HTML::Stream =cut BEGIN { unshift @INC, ".."; } package StringHandle; sub new { my $self = ''; bless \$self, shift; } sub print { my $self = shift; $$self .= join('', @_); } package main; use HTML::Stream; use FileHandle; my $SH = new StringHandle; my $HTML = new HTML::Stream $SH; $HTML -> H1 -> t("") -> _H1; print "PRINTED STRING: ", $$SH, "\n"; my $HTML = new HTML::Stream; $HTML -> H1 -> t("none") -> _H1; my $HTML = new HTML::Stream \*STDOUT; $HTML -> H1 -> t("<\\*STDOUT>") -> _H1; my $HTML = new HTML::Stream 'STDOUT'; $HTML -> H1 -> t("STDOUT") -> _H1; my $HTML = new HTML::Stream 'main::STDOUT'; $HTML -> H1 -> t("main::STDOUT") -> _H1; my $fh = new FileHandle ">&STDOUT"; my $HTML = new HTML::Stream $fh; $HTML -> H1 -> t("FD 0") -> _H1; package MY::HTML; @ISA = qw(HTML::Stream); sub Aside { $_[0] -> FONT(SIZE=>-1) -> I; } sub _Aside { $_[0] -> _I -> _FONT; } package main; use HTML::Stream qw(:funcs); my $HTML = new MY::HTML \*STDOUT; $HTML -> Aside -> t("Don't drink the milk, it's spoiled... pass it on...") -> _Aside; $HTML -> nl -> comment("Hey\nthere") -> comment("Ho"); my $htmlstr = "Hi & 360°\n"; print "Raw: ", $htmlstr; print "Unescaped: ", html_unescape($htmlstr); print "Unmarkedup: ", html_unmarkup($htmlstr); 1; HTML-Stream-1.60/examples/latin0000755000076600001200000000135407337073326016640 0ustar danieltstaaladmin=head1 NAME latin - just some example code using HTML::Stream::Latin1 =cut use HTML::Stream; accept_tag HTML::Stream 'BLORF'; $PLAIN = new HTML::Stream \*STDOUT; $LATIN = new HTML::Stream::Latin1 \*STDOUT; sub test { my $HTML = shift; $HTML -> nl -> H2 -> t("From ", ref($HTML), "...") -> _H2 -> nl; $HTML -> t(qq{\253Fran\347ois, }, qq{a \"right angle\" is 90\260, \277No?\273}) -> nl; $HTML -> P -> t("This example uses \\251: Copyright \251 1997 by me!") -> BR -> t("This example uses ent(): Copyright ") -> e('copy') -> t(" 1997 by me!"); $HTML -> P -> BLORF -> t("Hi!") -> _BLORF -> nl; $HTML -> BLORF -> t("Hi!") -> _BLORF; $HTML -> nl(2); } test($PLAIN); test($LATIN); HTML-Stream-1.60/examples/opts0000644000076600001200000000104206615250436016502 0ustar danieltstaaladmin#!/usr/bin/perl -w use HTML::Stream; # Setup: $HTML = new HTML::Stream \*STDOUT; $href = "/usr/local/foo"; $verse = < P -> A(HREF=>"$href") -> IMG(SRC=>"foo.gif", ALT=>"FOO!") -> t("Copyright \251 1997 by me!") -> _A; $HTML -> P -> text($verse) -> BR -> BR; } $HTML -> H1 -> t("NORMAL") -> _H1; &test; $HTML -> H1 -> t("NO AUTOFORMAT") -> _H1; $HTML->auto_format(0); &test; HTML-Stream-1.60/examples/README0000644000076600001200000000006406615250436016455 0ustar danieltstaaladminHere is some example code which uses HTML::Stream. HTML-Stream-1.60/lib/0000755000076600001200000000000011046441050014511 5ustar danieltstaaladminHTML-Stream-1.60/lib/HTML/0000755000076600001200000000000011046441050015255 5ustar danieltstaaladminHTML-Stream-1.60/lib/HTML/Stream.pm0000644000076600001200000012524411046440177017067 0ustar danieltstaaladminpackage HTML::Stream; =head1 NAME HTML::Stream - HTML output stream class, and some markup utilities =head1 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("<>"); 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]; =head1 DESCRIPTION The B 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, B, which can handle Latin-1 input right out of the box. But all in good time... =head1 INTRODUCTION (the Neapolitan dessert special) =head2 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 '© 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 I value (I the empty string!): print html_tag(TD, NOWRAP=>undef, ALIGN=>'LEFT'); print html_tag(IMG, SRC=>'logo.gif', ALT=>''); There are also some routines for reversing the process, like: $text = "This isn't "fun"..."; print html_unmarkup($text); This isn't "fun"... print html_unescape($text); This isn't "fun"... I, I hear you cry. I But wait! There's more... =head2 OO interface, vanilla Using the function interface can be tedious... so we also provide an B<"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 , 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 C and C instead of C and C: 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 C and C shortcuts without giving you one for C, would it? Of course not... =head2 OO interface, chocolate The known HTML tags are even given their own B 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 == tag(_A) == All of the autoloaded "tag-methods" use the tagname in I. A C<"_"> prefix on any tag-method means that an end-tag is desired. The C<"_"> 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) C<_TAG> looks a little like C because of the straight line. =over 4 =item * I =back I should stress that this module will only auto-create tag methods for B 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 I operation, and not stream-specific), do this: accept_tag HTML::Stream 'MARQUEE'; # for you MSIE fans... B 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 C tag. =head2 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; I =head2 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 C, and strings to C. =head1 ADVANCED TOPICS =head2 Auto-formatting and inserting newlines I 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: Hello! B on a given HTML::Stream object, use the C method: $HTML->auto_format(0); # stop autoformatting! B before/after the begin/end form of a tag at a B level, use C: HTML::Stream->set_tag('B', Newlines=>15); # 15 means "\n\n \n\n" HTML::Stream->set_tag('I', Newlines=>7); # 7 means "\n\n \n " B before/after the begin/end form of a tag B level, give the stream its own private "tag info" table, and then use C: $HTML->private_tags; $HTML->set_tag('B', Newlines=>0); # won't affect anyone else! B, just use the special C 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... =over 4 =item * Sometimes you'll be outputting stuff inside a C
 environment.

=item *

Sometimes you really do want to jam things (like images, or table
cell delimiters and the things they contain) right up against each other.

=back

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


=head2 Entities

As shown above, You can use the C (or C) 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...


=head2 Auto-escaping: changing the way text is escaped

I 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 C 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 B of HTML::Stream which installs
your custom function when constructed.  For an example, see the 
B subclass in this module.


=head2 Outputting HTML to things besides filehandles

As of Revision 1.21, you no longer need to supply C with a 
filehandle: I.
Of course, this includes B FileHandles, and IO::Handles.

If you supply a GLOB reference (like C<\*STDOUT>) or a string (like
C<"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 & <>!") -> _H1;
    print "PRINTED STRING: ", $$SH, "\n";


=head2 Subclassing

This is where you can make your application-specific HTML-generating code
I 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.


=head1 PUBLIC INTERFACE

=cut

use Carp;
use Exporter;
use strict;
use vars qw(@ISA %EXPORT_TAGS $AUTOLOAD $DASH_TO_SLASH $VERSION %Tags);

# Exporting...
@ISA = qw(Exporter);
%EXPORT_TAGS = (
      'funcs' => [qw(html_escape html_unescape html_unmarkup html_tag)]
);
Exporter::export_ok_tags('funcs');

# The package version, both in 1.23 style *and* usable by MakeMaker:
$VERSION = substr q$Revision: 1.60$, 10;



#------------------------------
#
# GLOBALS
#
#------------------------------

# Allow dashes to become slashes?
$DASH_TO_SLASH = 1;

# HTML escape sequences.  This bit was stolen from html_escape() in CGI::Base.
my %Escape = (
    '&'    => 'amp', 
    '>'    => 'gt', 
    '<'    => 'lt', 
    '"'    => 'quot',
);
my %Unescape;
{my ($k, $v); $Unescape{$v} = $k while (($k, $v) = each %Escape);}

# Flags for streams:
my $F_NEWLINE = 0x01;      # is autonewlining allowed?



#------------------------------
#
# PRIVATE UTILITIES
#
#------------------------------

#------------------------------
# escape_all TEXT
#
# Given a TEXT string, turn the text into valid HTML by interpolating the 
# appropriate escape sequences for all troublesome characters
# (angles, double-quotes, ampersands, and 8-bit characters).
#
# Uses the decimal-value syntax for 8-bit characters).

sub escape_all {
    my $text = shift;
    $text =~ s/([<>"&])/\&$Escape{$1};/mg; 
    $text =~ s/([\x80-\xFF])/'&#'.unpack('C',$1).';'/eg;
    $text;
}

#------------------------------
# escape_latin_1 TEXT
#
# Given a TEXT string, turn the text into valid HTML by interpolating the 
# appropriate escape sequences for all troublesome characters
# (angles, double-quotes, ampersands, and 8-bit characters).
#
# Uses the Latin-1 entities for 8-bit characters.

sub escape_latin_1 {
    my $text = shift;
    HTML::Entities::encode($text);  # can't use $_[0]! encode is destructive!
    $text;
}

#------------------------------
# escape_non_ent TEXT
#
# Given a TEXT string, turn the text into valid HTML by interpolating the 
# appropriate escape sequences for angles, double-quotes, and 8-bit
# characters only (i.e., ampersands are left alone).

sub escape_non_ent {
    my $text = shift;
    $text =~ s/([<>"])/\&$Escape{$1};/mg; 
    $text =~ s/([\x80-\xFF])/'&#'.unpack('C',$1).';'/eg;
    $text;
}

#------------------------------
# escape_none TEXT
#
# No-op, provided for very simple compatibility.  Just returns TEXT.

sub escape_none {
    $_[0];
}

#------------------------------
# build_tag ESCAPEFUNC, \@TAGINFO
#
# I  Build an HTML tag using the given ESCAPEFUNC.
# As an efficiency hack, only the values are HTML-escaped currently:
# it is assumed that the tag and parameters will already be safe.

sub build_tag {
    my $esc = shift;       # escape function
    my $taginfo = shift;   # tag info

    # Start off, converting "_x" to "/x":
    my $tag = shift @$taginfo;
    $tag =~ s|^_|/|;
    my $s = '<' . $tag;

    # Add parameters, if any:
    while (@$taginfo) {
	my $k = shift @$taginfo;
	my $v = shift @$taginfo;
	$s .= " $k";
	defined($v) and ((($s .= '="') .= &$esc($v)) .= '"');
    }
    $s .= '>';
}


#------------------------------



=head2 Functions

=over 4

=cut

#------------------------------


#------------------------------

=item 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:

    <  >  =  &

B provided for convenience and backwards-compatibility only.
You may want to use the more-powerful B
function instead.

=cut

sub html_escape {
    my $text = shift;
    $text =~ s/([<>"&])/\&$Escape{$1};/mg; 
    $text =~ s/([\x80-\xFF])/'&#'.unpack('C',$1).';'/eg;
    $text;
}
 
#------------------------------

=item 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 C<_A> instead of C<"/A">
for the first tag, if you're into barewords.

=cut

sub html_tag {
    build_tag(\&html_escape, \@_);    # warning! using ref to @_!
}

#------------------------------

=item html_unescape TEXT

Remove angle-tag markup, and convert the standard ampersand-escapes
(C, C, C, C, and C<#ddd>) into ASCII characters.

B provided for convenience and backwards-compatibility only.
You may want to use the more-powerful B
function instead: unlike this function, it can collapse entities
like C and C into their Latin-1 byte values.

=cut

sub html_unescape {
    my ($text) = @_;

    # Remove  sequences.  KLUDGE!  I'll code a better way later.
    $text =~ s/\<[^>]+\>//g;
    $text =~ s/\&([a-z]+);/($Unescape{$1}||'')/gie;
    $text =~ s/\&\#(\d+);/pack("C",$1)/gie;
    return $text;
}

#------------------------------

=item 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.

=cut

sub html_unmarkup {
    my ($text) = @_;

    # Remove  sequences.  KLUDGE!  I'll code a better way later.
    $text =~ s/\<[^>]+\>//g;
    return $text;
}



#------------------------------

=back

=head2 Vanilla

=over 4

=cut

#------------------------------

# Special mapping from names to utility functions (more stable than symtable):
my %AutoEscapeSubs = 
    ('ALL'     => \&HTML::Stream::escape_all,
     'LATIN_1' => \&HTML::Stream::escape_latin_1,
     'NON_ENT' => \&HTML::Stream::escape_non_ent,
     );


#------------------------------

=item new [PRINTABLE] 

I
Create a new HTML output stream.

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

=cut

sub new {
    my $class = shift;
    my $out = shift || select;      # defaults to current output stream

    # If it looks like an unblessed filehandle, bless it:
    if (!ref($out) || ref($out) eq 'GLOB') {
	$out = new HTML::Stream::FileHandle $out;
    }

    # Create the object:
    my $self = { 
	OUT   => $out,
	Esc   => \&escape_all,
	Tags  => \%Tags,          # reference to the master table
	Flags => $F_NEWLINE,      # autonewline
    };
    bless $self, $class;
}

#------------------------------
# DESTROY
#
# Destructor.  Does I close the filehandle!

sub DESTROY { 1 }

#------------------------------
# autoescape - DEPRECATED as of 1.31 due to bad name choice
#
sub autoescape {
    my $self = shift;
    warn "HTML::Stream's autoescape() method is deprecated.\n",
         "Please use the identical (and more nicely named) auto_escape().\n";
    $self->auto_escape(@_);
}

#------------------------------

=item auto_escape [NAME|SUBREF]

I
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:

=over 4

=item 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 C<#123>).

=item LATIN_1

Like C<"ALL">, but uses Latin-1 entity names (like C) 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 C).

B If you specify this option, you'll find that it attempts
to "require" B at run time.  That's because I didn't want 
to I 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.

=item NON_ENT

Like C<"ALL">, except that ampersands (&) are I 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°";

=back

Returns the previously-installed function, in the manner of C.
No arguments just returns the currently-installed function.

=cut

sub auto_escape {
    my $self = shift;

    # Grab existing value:
    my $oldesc = $self->{Esc}; 

    # If arguments were given, they specify the new value:
    if (@_) { 
	my $newesc = shift;
	if (ref($newesc) ne 'CODE') {  # must be a string: map it to a subref
	    require HTML::Entities if ($newesc eq 'LATIN_1');
	    $newesc = $AutoEscapeSubs{uc($newesc)} or
		croak "never heard of auto-escape option '$newesc'";
	}
	$self->{Esc} = $newesc;
    }

    # Return old value:
    $oldesc;
}

#------------------------------

=item auto_format ONOFF

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

=cut

sub auto_format {
    my ($self, $onoff) = @_;
    ($self->{Flags} &= (~1 << 0)) |= ($onoff << 0);
    $self;
}

#------------------------------

=item comment COMMENT

I
Output an HTML comment.
As of 1.29, a newline is automatically appended.

=cut

sub comment {
    my $self = shift;
    $self->{OUT}->print('\n");
    $self;
}

#------------------------------

=item ent ENTITY

I
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 C:

      $html->e('nbsp');

B this function assumes that the entity argument is legal.

=cut

sub ent {
    my ($self, $entity) = @_;
    $self->{OUT}->print("\&$entity;");
    $self;
}
*e = \&ent;


#------------------------------

=item 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!");

=cut

sub io {
    shift->{OUT};
}


#------------------------------

=item nl [COUNT]

I
Output COUNT newlines.  If undefined, COUNT defaults to 1.

=cut

sub nl {
    my ($self, $count) = @_;
    $self->{OUT}->print("\n" x (defined($count) ? $count : 1));
    $self;
}

#------------------------------

=item tag TAGNAME [, PARAM=>VALUE, ...]

I
Output a tag.  Returns the self object, to allow method chaining.
You can say C<_A> instead of C<"/A">, if you're into barewords.

=cut

sub tag {
    my $self = shift;
    $self->{OUT}->print(build_tag($self->{Esc}, \@_));
    $self;
}

#------------------------------

=item text TEXT...

I
Output some text.  You may abbreviate this method name as C:

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

Returns the self object, to allow method chaining.

=cut

sub text {
    my $self = shift;
    $self->{OUT}->print(&{$self->{Esc}}(join('',@_)));
    $self;
}
*t = \&text;

#------------------------------

=item text_nbsp TEXT...

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

=cut

sub text_nbsp {
    my $self = shift;
    my $txt = &{$self->{Esc}}(join('',@_));
    $txt =~ s/ / /g;
    $self->{OUT}->print($txt);
    $self;
}
*nbsp_text = \&text_nbsp;      # deprecated, but supplied for John :-)


#------------------------------

=back

=head2 Strawberry

=over 4

=cut

#------------------------------

#------------------------------

=item output ITEM,...,ITEM

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

=cut

sub output {
    my $self = shift;
    my $out = $self->{OUT};
    my $esc = $self->{Esc};
    foreach (@_) {
	if (ref($_) eq 'ARRAY') {    # E.g., $_ is [A, HREF=>$url]
	    $out->print(&build_tag($esc, $_));
	}
	elsif (!ref($_)) {           # E.g., $_ is "Some text"
	    $out->print(&$esc($_));
	}
	else {
	    confess "bad argument to output: $_";
	}
    }
    $self;        # heh... why not...
}


#------------------------------

=back

=head2 Chocolate

=over 4

=cut

#------------------------------

#------------------------------
# %Tags
#------------------------------
# The default known HTML tags.  The value if each is CURRENTLY a set of flags:
#
#     0x01    newline before 
#     0x02    newline after 
#     0x04    newline before 
#     0x08    newline after 
#
# This can be summarized as:

my $TP     = 1 | 0 | 0 | 0;
my $TBR    = 0 | 2 | 0 | 0;
my $TFONT  = 0 | 0 | 0 | 0;  # fontlike
my $TOUTER = 1 | 0 | 0 | 8;
my $TBOTH  = 0 | 2 | 0 | 8;
my $TLIST  = 0 | 2 | 0 | 8;
my $TELEM  = 0 | 0 | 0 | 8; 
my $TTITLE = 0 | 0 | 0 | 8;
my $TSOLO  = 0 | 2 | 0 | 0;

%Tags = 
    (
     A       => 0,
     ABBR    => 0,
     ACRONYM => 0,
     ADDRESS => $TBOTH,
     APPLET  => $TBOTH,
     AREA    => $TELEM,
     B       => 0,
     BASE    => 0,
    BASEFONT => $TBOTH,
     BDO     => $TBOTH,
     BIG     => 0,
     BGSOUND => $TELEM,
     BLINK   => 0,
  BLOCKQUOTE => $TBOTH,
     BODY    => $TBOTH,
     BUTTON  => $TP,
     BR      => $TBR,
     CAPTION => $TTITLE,
     CENTER  => $TBOTH,
     CITE    => 0,
     CODE    => 0,
     COMMENT => $TBOTH,
    COLGROUP => $TP,
     COL     => $TP,
     DEL     => 0,
     DFN     => 0,
     DD      => $TLIST,
     DIR     => $TLIST,
     DIV     => $TP,
     DL      => $TELEM,
     DT      => $TELEM,
     EM      => 0,
     EMBED   => $TBOTH,
     FONT    => 0,
     FORM    => $TBOTH,
    FIELDSET => $TBOTH,
     FRAME   => $TBOTH,
    FRAMESET => $TBOTH,
     H1      => $TTITLE,
     H2      => $TTITLE,
     H3      => $TTITLE,
     H4      => $TTITLE,
     H5      => $TTITLE,
     H6      => $TTITLE,
     HEAD    => $TBOTH,
     HR      => $TBOTH,
     HTML    => $TBOTH,
     I       => 0,
     IFRAME  => $TBOTH,
     IMG     => 0,
     INPUT   => 0,
     INS     => 0,
     ISINDEX => 0,
     KEYGEN  => $TBOTH,
     KBD     => 0,
     LABEL   => $TP,
     LEGEND  => $TP,
     LI      => $TELEM,
     LINK    => 0,
     LISTING => $TBOTH,
     MAP     => $TBOTH,
     MARQUEE => $TTITLE,
     MENU    => $TLIST,
     META    => $TSOLO,
     NEXTID  => $TBOTH,
     NOBR    => $TFONT,
     NOEMBED => $TBOTH,
     NOFRAME => $TBOTH,
    NOFRAMES => $TBOTH,
    NOSCRIPT => $TBOTH,
     OBJECT  => 0,
     OL      => $TLIST, 
     OPTION  => $TELEM,
    OPTGROUP => $TELEM,
     P       => $TP,
     PARAM   => $TP,
   PLAINTEXT => $TBOTH,
     PRE     => $TOUTER,
     Q       => 0,
     SAMP    => 0,
     SCRIPT  => $TBOTH,
     SELECT  => $TBOTH,
     SERVER  => $TBOTH,
     SMALL   => 0,
     SPAN    => 0,
     STRONG  => 0,
     STRIKE  => 0,
     STYLE   => 0,
     SUB     => 0,
     SUP     => 0,
     TABLE   => $TBOTH,
     TBODY   => $TP,
     TD      => 0,
    TEXTAREA => 0,
     TFOOT   => $TP,
     TH      => 0,
     THEAD   => $TP,
     TITLE   => $TTITLE,
     TR      => $TOUTER,
     TT      => 0,
     U       => 0,
     UL      => $TLIST, 
     VAR     => 0,
     WBR     => 0,
     XMP     => 0,
     );


#------------------------------

=item accept_tag TAG

I
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);

=cut

sub accept_tag {
    my ($self, $tag) = @_;
    my $class = (ref($self) ? ref($self) : $self);   # force it, for now
    $class->set_tag($tag);
}


#------------------------------

=item private_tags 

I
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 C 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 I (although they will 
possibly be able to use the BLINK tag method without a fatal
exception C<:-(> ).

Returns the self object.

=cut

sub private_tags {
    my $self = shift;
    my %newtags = %Tags;
    $self->{Tags} = \%newtags;
    $self;
}

#------------------------------

=item set_tag TAG, [TAGINFO...]

I
Accept the given TAG in the Chocolate Interface, and (if TAGINFO
is given) alter its characteristics when being output.

=over 4

=item *

B 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, I HTML streams you open from then on 
will allow that tag to be output in the chocolate interface.

=item *

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

B by default, an HTML stream just references the "master tag table" 
(this makes C more efficient), so I

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

If you want to diddle with I stream's auto-formatting I 
you'll need to give that stream its own I tag table.  Like this:

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

B this will still force an default entry for BLINK in the I 
tag table: otherwise, we'd never know that it was legal to AUTOLOAD a 
BLINK method.   However, it will only alter the I of the 
BLINK tag (like auto-formatting) in the I tag table.

=back

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

=over 4

=item 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          ..     ..    
     0x02    newline after           |     |     |      |
     0x04    newline before         1     2     4      8
     0x08    newline after     

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

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

=back

Returns the self object on success.

=cut

sub set_tag {
    my ($self, $tag, %params) = @_;
    $tag = uc($tag);                           # it's GOT to be uppercase!!!

    # Force it to BE in the MASTER tag table, regardless:
    defined($Tags{$tag}) or $Tags{$tag} = 0;       # default value

    # Determine what table we ALTER, and force membership in that table:
    my $tags = (ref($self) ? $self->{Tags} : \%Tags);
    defined($tags->{$tag}) or $tags->{$tag} = 0;   # default value

    # Now, set selected characteristics in that table:
    if (defined($params{Newlines})) {
	$tags->{$tag} = ($params{Newlines} || 0);
    }
    $self;
}

#------------------------------

=item tags 

I
Returns an unsorted list of all tags in the class/instance tag table 
(see C for class/instance method differences).

=cut

sub tags {
    my $self = shift;
    return (keys %{ref($self) ? $self->{Tags} : \%Tags});
}


#------------------------------
# AUTOLOAD
#
# The custom autoloader, for the chocolate interface.
#
# B I have no idea if the mechanism I use to put the
# functions in this module (HTML::Stream) is perlitically correct.

sub AUTOLOAD {
    my $funcname = $AUTOLOAD;
    $funcname =~ s/.*:://;            # get rid of package name 
    my $tag;
    ($tag = $funcname) =~ s/^_//;     # get rid of leading "_"

    # If it's a tag method that's been approved in the master table...
    if (defined($Tags{$tag})) {

	# A begin-tag, like "IMG"...
	if ($funcname !~ /^_/) {     
	    eval <{OUT}->print("\n") if (\$self->{Tags}{'$tag'} & 1 and
					       \$self->{Flags} & $F_NEWLINE);
                \$self->{OUT}->print(html_tag('$tag',\@_));
		\$self->{OUT}->print("\n") if (\$self->{Tags}{'$tag'} & 2 and
					       \$self->{Flags} & $F_NEWLINE);
                \$self;
            }
EOF
	}
        # An end-tag, like "_IMG"...
	else { 
	    eval <{OUT}->print("\n") if (\$self->{Tags}{'$tag'} & 4 and
					       \$self->{Flags} & $F_NEWLINE);
                \$self->{OUT}->print("");
		\$self->{OUT}->print("\n") if (\$self->{Tags}{'$tag'} & 8 and
					       \$self->{Flags} & $F_NEWLINE);
                \$self;
            }
EOF
	}
	if ($@) { $@ =~ s/ at .*\n//; croak $@ }   # die!
        my $fn = "HTML::Stream::$funcname";        # KLUDGE: is this right???
        goto &$fn;
    }

    # If it's NOT a tag method...
    else { 
	# probably should call the *real* autoloader in the future...
	croak "Sorry: $AUTOLOAD is neither defined or loadable";
    }
    goto &$AUTOLOAD;
}


=back

=head1 SUBCLASSES

=cut


# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

# A small, private package for turning FileHandles into safe printables:

package HTML::Stream::FileHandle;

use strict;
no strict 'refs';

sub new {
    my ($class, $raw) = @_;
    bless \$raw, $class;
}
sub print {
    my $self = shift;
    print { $$self } @_;
}


# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

=head2 HTML::Stream::Latin1

A small, public package for outputting Latin-1 markup.  Its
default auto-escape function is C, which tries to output
the mnemonic entity markup (e.g., C<ç>) 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:

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

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

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

B 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".

B using this class "requires" that you have HTML::Entities.

=cut

package HTML::Stream::Latin1;

use strict;
use vars qw(@ISA);
@ISA = qw(HTML::Stream);

# Constructor:
sub new {
    my $class = shift;
    my $self = HTML::Stream->new(@_);
    $self->auto_escape('LATIN_1');
    bless $self, $class;
}


__END__

# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

=head1 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 '',
  	  html_escape($caption),
          '';
    print html_escape($a_lot_of_text);

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

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



=head1 VERSION

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

=head1 CHANGE LOG

=over 4

=item Version 1.60   (2008/08/06)

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

=item Version 1.59   (2008/06/01)

Better tests, better Meta.yml.

=item Version 1.58   (2008/05/28)

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

=item Version 1.57   (2008/05/28)

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

=item 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.

=item 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.)


=item Version 1.54   (2001/08/20)

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

=item 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.


=item Version 1.47   (2000/06/10)

No real changes to code; just improved documentation.


=item Version 1.45   (1999/02/09)

Cleanup for Perl 5.005: removed duplicate typeglob assignments.


=item Version 1.44   (1998/01/14)

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


=item Version 1.41   (1998/01/02)

Removed $& for efficiency.
I

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

Added text_nbsp().
I
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.


=item Version 1.37   (1997/02/09)

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


=item Version 1.32   (1997/01/12)

B 
Check your toolkit for B.

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

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

Added C 
so you can now turn auto-formatting off/on.

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

Added C.  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 I add
greater flexibility for more-complex programs.

Added POD documentation for all subroutines in the public interface.


=item Version 1.29   (1996/12/10)

Added terminating newline to comment().
I


=item 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.
I


=item Version 1.26   (1996/09/27)

Start of history.

=back

=head1 COPYRIGHT

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

=head1 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.

=head1 AUTHOR

Daniel T. Staal (F).

Enjoy.  Yell if it breaks.

=cut

#------------------------------
1;

HTML-Stream-1.60/Makefile.PL0000755000076600001200000000111611017304571015723 0ustar  danieltstaaladmin#!/usr/bin/perl
use ExtUtils::MakeMaker;

# Write the Makefile:
WriteMakefile(
	      NAME         => 'HTML::Stream',
	      VERSION_FROM => "lib/HTML/Stream.pm",
	      DISTNAME     => "HTML-Stream",
	      'dist'       => {
			  PREOP    => 'rm .DS_Store &',
			  COMPRESS => 'gzip',
			  SUFFIX   => 'gz',
			  TARFLAGS => '--exclude ._* -cvf'
			  },
	      ($] >= 5.005 ?     ## Add these new keywords supported since 5.005
      		(ABSTRACT_FROM  => 'lib/HTML/Stream.pm', # retrieve abstract from module
       		AUTHOR         => 'Daniel T. Staal ') : ()),
	      );
HTML-Stream-1.60/MANIFEST0000644000076600001200000000130311017306377015103 0ustar  danieltstaaladminChanges
COPYING
MANIFEST
Makefile.PL
README
README.system
bin/html2perlstream
docs/HTML/Stream.pm.html
docs/HTML/icons/h1bullet.gif
docs/HTML/icons/h2bullet.gif
docs/HTML/icons/itembullet.gif
docs/HTML/icons/zeegee.gif
docs/giggles.html
docs/html2perlstream.html
docs/icons/h1bullet.gif
docs/icons/h2bullet.gif
docs/icons/itembullet.gif
docs/icons/zeegee.gif
docs/index-menu.html
docs/index.html
docs/index.menu
docs/latin.html
etc/README
examples/README
examples/giggles
examples/latin
examples/opts
lib/HTML/Stream.pm
testin/README
testin/test.html
testin/test2.html
t/01-HTML-Stream.t
t/02-OO_Tests.t
t/03-Functional_Tests.t
META.yml                                 Module meta-data (added by MakeMaker)
HTML-Stream-1.60/META.yml0000644000076600001200000000065011046441050015215 0ustar  danieltstaaladmin--- #YAML:1.0
name:                HTML-Stream
version:             1.60
abstract:            HTML output stream class, and some markup utilities
license:             ~
author:              
    - Daniel T. Staal 
generated_by:        ExtUtils::MakeMaker version 6.44
distribution_type:   module
requires:     
meta-spec:
    url:     http://module-build.sourceforge.net/META-spec-v1.3.html
    version: 1.3
HTML-Stream-1.60/README0000644000076600001200000007605611046440575014654 0ustar  danieltstaaladminNAME
    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("<>");

    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 '© 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');
        
         
        
    print html_tag(IMG, SRC=>'logo.gif', ALT=>'');
        
         

    There are also some routines for reversing the process, like:

        $text = "This isn't "fun"...";    
        print html_unmarkup($text);
           
         This isn't "fun"...
          
    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 , 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...

  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              ==   tag(_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.

    *   *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:

        
        
        Hello!
        
        

    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\n \n\n"
        HTML::Stream->set_tag('I', Newlines=>7);    # 7 means  "\n\n \n  "

    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 & <>!") -> _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°";

        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.

        *   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          ..     ..    
                 0x02    newline after           |     |     |      |
                 0x04    newline before         1     2     4      8
                 0x08    newline after 

            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., "ç") 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:

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

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 '',
              html_escape($caption),
              '';
        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.

HTML-Stream-1.60/README.system0000644000076600001200000000000011017306367016145 0ustar  danieltstaaladminHTML-Stream-1.60/t/0000755000076600001200000000000011046441050014206 5ustar  danieltstaaladminHTML-Stream-1.60/t/01-HTML-Stream.t0000644000076600001200000000073111046154531016614 0ustar  danieltstaaladmin# Before `make install' is performed this script should be runnable with
# `make test'. After `make install' it should work as `perl HTML-Stream.t'

#########################

# change 'tests => 1' to 'tests => last_test_to_print';

use Test::More tests => 1;
BEGIN { use_ok('HTML::Stream') };

#########################

# Insert your test code below, the Test::More module is use()ed here so read
# its man page ( perldoc Test::More ) for help writing this test script.

HTML-Stream-1.60/t/02-OO_Tests.t0000644000076600001200000000543211046437505016327 0ustar  danieltstaaladmin
#use Test::More tests=>19;
use Test::More qw(no_plan);
use HTML::Stream;



# Test if we have all the normal stuff we are supposed to.
my $HTML = new HTML::Stream \*STDOUT;

# The directly defined methods.
can_ok($HTML, qw(auto_escape auto_format comment ent io nl tag t text text_nbsp
				output accept_tag private_tags set_tag tags
				));

# Check that we say we accept the 'historic' tag list by default.
# (The historic tag list is the list of all tags in HTML 4 plus other common tags.)
my @tags = $HTML->tags();
@tags = sort @tags;
my @historic_tags = qw(A ABBR ACRONYM ADDRESS APPLET AREA B BASE BASEFONT BDO
						BGSOUND BIG BLINK BLOCKQUOTE BODY BR BUTTON CAPTION 
						CENTER CITE CODE COL COLGROUP COMMENT DD DEL DFN DIR 
						DIV DL DT EM EMBED FIELDSET FONT FORM FRAME FRAMESET 
						H1 H2 H3 H4 H5 H6 HEAD HR HTML I IFRAME IMG INPUT INS 
						ISINDEX KBD KEYGEN LABEL LEGEND LI LINK LISTING MAP 
						MARQUEE MENU META NEXTID NOBR NOEMBED NOFRAME NOFRAMES NOSCRIPT 
						OBJECT OL OPTGROUP OPTION P PARAM PLAINTEXT PRE Q SAMP 
						SCRIPT SELECT SERVER SMALL SPAN STRIKE STRONG STYLE 
						SUB SUP TABLE TBODY TD TEXTAREA TFOOT TH THEAD TITLE 
						TR TT U UL VAR WBR XMP
					);

is_deeply (\@tags, \@historic_tags, "Tags List");

# Check that we can add tags as needed...
$HTML->accept_tag('DSTAAL');
push @historic_tags, 'DSTAAL';
@historic_tags = sort @historic_tags;
@tags = $HTML->tags();
@tags = sort @tags;
is_deeply (\@tags, \@historic_tags, "Tags List");


# Skip tests if we can't run them.
SKIP: {
 	eval { require Test::Output };
	skip "Test::Output is needed for OO tests to run.", 16 if $@;
	Test::Output->import();

	# Check that some of these tags actually work as expected...
	stdout_is( sub { $HTML->ABBR }, "" );
	stdout_is( sub { $HTML->ABBR->_ABBR }, "" );
	stdout_is( sub { $HTML->A(HREF=>'mailto:DSTAAL@USA.NET') }, '' );
	stdout_is( sub { $HTML->ADDRESS->_ADDRESS }, "
\n
\n" ); stdout_is( sub { $HTML->AREA->_AREA }, "\n" ); stdout_is( sub { $HTML->BR->_BR }, "
\n
" ); stdout_is( sub { $HTML->BUTTON->_BUTTON }, "\n" ); stdout_is( sub { $HTML->H1->_H1 }, "

\n" ); stdout_is( sub { $HTML->TR(NOWRAP=>undef)->_TR }, "\n\n" ); # Check Escaping # (I really should be through about this, but these are the # HTML _required_ escapes checked at least.) stdout_is( sub { $HTML->text("&") }, "&" ); stdout_is( sub { $HTML->t("<") }, "<" ); #Check a couple of the other methods... # 'Newline' is up first. stdout_is( sub { $HTML->nl }, "\n" ); stdout_is( sub { $HTML->nl(3) }, "\n\n\n" ); stdout_is( sub { $HTML->nl(0) }, "" ); stdout_is( sub { $HTML->nl(-1) }, "" ); stdout_is( sub { $HTML->nl("a") }, "" ); # This fails intentionally. }HTML-Stream-1.60/t/03-Functional_Tests.t0000644000076600001200000000065511046154513020112 0ustar danieltstaaladminuse Test::More tests => 4; use HTML::Stream qw(:funcs); # Test the 'un' methods. my $text = "This isn't "fun"..."; is(html_unmarkup($text), "This isn't "fun"...", "HTML Unmarkup"); is(html_unescape($text), 'This isn\'t "fun"...', "HTML Unescape"); # Test escaping. is(html_escape("<>&"), "<>&", "Escaping text"); # Test HTML. is(html_tag(TR, NOWRAP=>undef), "", "HTML 1");HTML-Stream-1.60/testin/0000755000076600001200000000000011046441050015251 5ustar danieltstaaladminHTML-Stream-1.60/testin/README0000644000076600001200000000006406615250437016146 0ustar danieltstaaladminThere are some input test files for HTML::Stream. HTML-Stream-1.60/testin/test.html0000644000076600001200000000054306615250436017134 0ustar danieltstaaladmin
Hi!
Foo! <Bar!>

This is a paragraph of text! How does this work... or "this"? & this?

  • Eenica>
  • Meenica
  • Mineamoica
HTML-Stream-1.60/testin/test2.html0000644000076600001200000000054406615250437017220 0ustar danieltstaaladmin Hi!
GOO! <GOO>

This is a paragraph of text! How does this work... or "this"? & this?

  • Eenica>
  • Meenica
  • Mineamoica