| 1 |
<HTML> |
| 2 |
<HEAD> |
| 3 |
<TITLE>HTML::Stream 1.54</TITLE> |
| 4 |
</HEAD> |
| 5 |
<BODY |
| 6 |
bgcolor="#FFFFFF" link="#CC3366" vlink="#993366" alink="#FF6666"> |
| 7 |
<FONT FACE="sans-serif" SIZE=-1><A HREF="http://www.zeegee.com" TARGET="_top"><IMG SRC="icons/zeegee.gif" ALT="ZeeGee Software" ALIGN="RIGHT" BORDER="0"></A><A NAME="__TOP__"><H1>HTML::Stream 1.54</H1> |
| 8 |
</A><UL> |
| 9 |
<LI> <A NAME="menu:NAME"><A HREF="#NAME">NAME</A></A> |
| 10 |
<LI> <A NAME="menu:SYNOPSIS"><A HREF="#SYNOPSIS">SYNOPSIS</A></A> |
| 11 |
<LI> <A NAME="menu:DESCRIPTION"><A HREF="#DESCRIPTION">DESCRIPTION</A></A> |
| 12 |
<LI> <A NAME="menu:INTRODUCTION_the_Neapolitan_dessert_special"><A HREF="#INTRODUCTION_the_Neapolitan_dessert_special">INTRODUCTION (the Neapolitan dessert special)</A></A> |
| 13 |
<UL> |
| 14 |
<LI> <A NAME="menu:Function_interface"><A HREF="#Function_interface">Function interface</A></A> |
| 15 |
<LI> <A NAME="menu:OO_interface_vanilla"><A HREF="#OO_interface_vanilla">OO interface, vanilla</A></A> |
| 16 |
<LI> <A NAME="menu:OO_interface_chocolate"><A HREF="#OO_interface_chocolate">OO interface, chocolate</A></A> |
| 17 |
<LI> <A NAME="menu:OO_interface_with_whipped_cream"><A HREF="#OO_interface_with_whipped_cream">OO interface, with whipped cream</A></A> |
| 18 |
<LI> <A NAME="menu:OO_interface_strawberry"><A HREF="#OO_interface_strawberry">OO interface, strawberry</A></A> |
| 19 |
</UL> |
| 20 |
<LI> <A NAME="menu:ADVANCED_TOPICS"><A HREF="#ADVANCED_TOPICS">ADVANCED TOPICS</A></A> |
| 21 |
<UL> |
| 22 |
<LI> <A NAME="menu:Auto-formatting_and_inserting_newlines"><A HREF="#Auto-formatting_and_inserting_newlines">Auto-formatting and inserting newlines</A></A> |
| 23 |
<LI> <A NAME="menu:Entities"><A HREF="#Entities">Entities</A></A> |
| 24 |
<LI> <A NAME="menu:Auto-escaping_changing_the_way_text_is_escaped"><A HREF="#Auto-escaping_changing_the_way_text_is_escaped">Auto-escaping: changing the way text is escaped</A></A> |
| 25 |
<LI> <A NAME="menu:Outputting_HTML_to_things_besides_filehandles"><A HREF="#Outputting_HTML_to_things_besides_filehandles">Outputting HTML to things besides filehandles</A></A> |
| 26 |
<LI> <A NAME="menu:Subclassing"><A HREF="#Subclassing">Subclassing</A></A> |
| 27 |
</UL> |
| 28 |
<LI> <A NAME="menu:PUBLIC_INTERFACE"><A HREF="#PUBLIC_INTERFACE">PUBLIC INTERFACE</A></A> |
| 29 |
<UL> |
| 30 |
<LI> <A NAME="menu:Functions"><A HREF="#Functions">Functions</A></A> |
| 31 |
<UL> |
| 32 |
<LI> <A NAME="menu:item:html_escape_TEXT"><A HREF="#item:html_escape_TEXT">html_escape TEXT</A></A> |
| 33 |
<LI> <A NAME="menu:item:html_tag_TAG_PARAM_VALUE"><A HREF="#item:html_tag_TAG_PARAM_VALUE">html_tag TAG [, PARAM=>VALUE, ...]</A></A> |
| 34 |
<LI> <A NAME="menu:item:html_unescape_TEXT"><A HREF="#item:html_unescape_TEXT">html_unescape TEXT</A></A> |
| 35 |
<LI> <A NAME="menu:item:html_unmarkup_TEXT"><A HREF="#item:html_unmarkup_TEXT">html_unmarkup TEXT</A></A> |
| 36 |
</UL> |
| 37 |
<LI> <A NAME="menu:Vanilla"><A HREF="#Vanilla">Vanilla</A></A> |
| 38 |
<UL> |
| 39 |
<LI> <A NAME="menu:item:new_PRINTABLE"><A HREF="#item:new_PRINTABLE">new [PRINTABLE] </A></A> |
| 40 |
<LI> <A NAME="menu:item:auto_escape_NAME_SUBREF"><A HREF="#item:auto_escape_NAME_SUBREF">auto_escape [NAME|SUBREF]</A></A> |
| 41 |
<LI> <A NAME="menu:item:auto_format_ONOFF"><A HREF="#item:auto_format_ONOFF">auto_format ONOFF</A></A> |
| 42 |
<LI> <A NAME="menu:item:comment_COMMENT"><A HREF="#item:comment_COMMENT">comment COMMENT</A></A> |
| 43 |
<LI> <A NAME="menu:item:ent_ENTITY"><A HREF="#item:ent_ENTITY">ent ENTITY</A></A> |
| 44 |
<LI> <A NAME="menu:item:io"><A HREF="#item:io">io</A></A> |
| 45 |
<LI> <A NAME="menu:item:nl_COUNT"><A HREF="#item:nl_COUNT">nl [COUNT]</A></A> |
| 46 |
<LI> <A NAME="menu:item:tag_TAGNAME_PARAM_VALUE"><A HREF="#item:tag_TAGNAME_PARAM_VALUE">tag TAGNAME [, PARAM=>VALUE, ...]</A></A> |
| 47 |
<LI> <A NAME="menu:item:text_TEXT"><A HREF="#item:text_TEXT">text TEXT...</A></A> |
| 48 |
<LI> <A NAME="menu:item:text_nbsp_TEXT"><A HREF="#item:text_nbsp_TEXT">text_nbsp TEXT...</A></A> |
| 49 |
</UL> |
| 50 |
<LI> <A NAME="menu:Strawberry"><A HREF="#Strawberry">Strawberry</A></A> |
| 51 |
<UL> |
| 52 |
<LI> <A NAME="menu:item:output_ITEM_ITEM"><A HREF="#item:output_ITEM_ITEM">output ITEM,...,ITEM</A></A> |
| 53 |
</UL> |
| 54 |
<LI> <A NAME="menu:Chocolate"><A HREF="#Chocolate">Chocolate</A></A> |
| 55 |
<UL> |
| 56 |
<LI> <A NAME="menu:item:accept_tag_TAG"><A HREF="#item:accept_tag_TAG">accept_tag TAG</A></A> |
| 57 |
<LI> <A NAME="menu:item:private_tags"><A HREF="#item:private_tags">private_tags </A></A> |
| 58 |
<LI> <A NAME="menu:item:set_tag_TAG_TAGINFO"><A HREF="#item:set_tag_TAG_TAGINFO">set_tag TAG, [TAGINFO...]</A></A> |
| 59 |
<LI> <A NAME="menu:item:tags"><A HREF="#item:tags">tags </A></A> |
| 60 |
</UL> |
| 61 |
</UL> |
| 62 |
<LI> <A NAME="menu:SUBCLASSES"><A HREF="#SUBCLASSES">SUBCLASSES</A></A> |
| 63 |
<UL> |
| 64 |
<LI> <A NAME="menu:HTML_Stream_Latin1"><A HREF="#HTML_Stream_Latin1">HTML::Stream::Latin1</A></A> |
| 65 |
</UL> |
| 66 |
<LI> <A NAME="menu:PERFORMANCE"><A HREF="#PERFORMANCE">PERFORMANCE</A></A> |
| 67 |
<LI> <A NAME="menu:VERSION"><A HREF="#VERSION">VERSION</A></A> |
| 68 |
<LI> <A NAME="menu:CHANGE_LOG"><A HREF="#CHANGE_LOG">CHANGE LOG</A></A> |
| 69 |
<UL> |
| 70 |
<LI> <A NAME="menu:item:Version_1_54_2001_08_20"><A HREF="#item:Version_1_54_2001_08_20">Version 1.54 (2001/08/20)</A></A> |
| 71 |
<LI> <A NAME="menu:item:Version_1_51_2001_08_16"><A HREF="#item:Version_1_51_2001_08_16">Version 1.51 (2001/08/16)</A></A> |
| 72 |
<LI> <A NAME="menu:item:Version_1_47_2000_06_10"><A HREF="#item:Version_1_47_2000_06_10">Version 1.47 (2000/06/10)</A></A> |
| 73 |
<LI> <A NAME="menu:item:Version_1_45_1999_02_09"><A HREF="#item:Version_1_45_1999_02_09">Version 1.45 (1999/02/09)</A></A> |
| 74 |
<LI> <A NAME="menu:item:Version_1_44_1998_01_14"><A HREF="#item:Version_1_44_1998_01_14">Version 1.44 (1998/01/14)</A></A> |
| 75 |
<LI> <A NAME="menu:item:Version_1_41_1998_01_02"><A HREF="#item:Version_1_41_1998_01_02">Version 1.41 (1998/01/02)</A></A> |
| 76 |
<LI> <A NAME="menu:item:Version_1_37_1997_02_09"><A HREF="#item:Version_1_37_1997_02_09">Version 1.37 (1997/02/09)</A></A> |
| 77 |
<LI> <A NAME="menu:item:Version_1_32_1997_01_12"><A HREF="#item:Version_1_32_1997_01_12">Version 1.32 (1997/01/12)</A></A> |
| 78 |
<LI> <A NAME="menu:item:Version_1_29_1996_12_10"><A HREF="#item:Version_1_29_1996_12_10">Version 1.29 (1996/12/10)</A></A> |
| 79 |
<LI> <A NAME="menu:item:Version_1_27_1996_12_10"><A HREF="#item:Version_1_27_1996_12_10">Version 1.27 (1996/12/10)</A></A> |
| 80 |
<LI> <A NAME="menu:item:Version_1_26_1996_09_27"><A HREF="#item:Version_1_26_1996_09_27">Version 1.26 (1996/09/27)</A></A> |
| 81 |
</UL> |
| 82 |
<LI> <A NAME="menu:ACKNOWLEDGEMENTS"><A HREF="#ACKNOWLEDGEMENTS">ACKNOWLEDGEMENTS</A></A> |
| 83 |
<LI> <A NAME="menu:AUTHOR"><A HREF="#AUTHOR">AUTHOR</A></A> |
| 84 |
</UL> |
| 85 |
|
| 86 |
|
| 87 |
<P><HR> |
| 88 |
<A NAME="NAME"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> NAME</H2></A> |
| 89 |
|
| 90 |
|
| 91 |
<P>HTML::Stream - HTML output stream class, and some markup utilities |
| 92 |
|
| 93 |
|
| 94 |
|
| 95 |
<P><HR> |
| 96 |
<A NAME="SYNOPSIS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SYNOPSIS</H2></A> |
| 97 |
|
| 98 |
|
| 99 |
<P>Here's small sample of some of the non-OO ways you can use this module: |
| 100 |
|
| 101 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 102 |
use HTML::Stream qw(:funcs); |
| 103 |
|
| 104 |
print html_tag('A', HREF=>$link); |
| 105 |
print html_escape("<<Hello & welcome!>>"); |
| 106 |
</PRE></FONT> |
| 107 |
|
| 108 |
<P>And some of the OO ways as well: |
| 109 |
|
| 110 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 111 |
use HTML::Stream; |
| 112 |
$HTML = new HTML::Stream \*STDOUT; |
| 113 |
|
| 114 |
# The vanilla interface... |
| 115 |
$HTML->tag('A', HREF=>"$href"); |
| 116 |
$HTML->tag('IMG', SRC=>"logo.gif", ALT=>"LOGO"); |
| 117 |
$HTML->text($copyright); |
| 118 |
$HTML->tag('_A'); |
| 119 |
|
| 120 |
# The chocolate interface... |
| 121 |
$HTML -> A(HREF=>"$href"); |
| 122 |
$HTML -> IMG(SRC=>"logo.gif", ALT=>"LOGO"); |
| 123 |
$HTML -> t($caption); |
| 124 |
$HTML -> _A; |
| 125 |
|
| 126 |
# The chocolate interface, with whipped cream... |
| 127 |
$HTML -> A(HREF=>"$href") |
| 128 |
-> IMG(SRC=>"logo.gif", ALT=>"LOGO") |
| 129 |
-> t($caption) |
| 130 |
-> _A; |
| 131 |
</PRE></FONT> |
| 132 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 133 |
# The strawberry interface... |
| 134 |
output $HTML [A, HREF=>"$href"], |
| 135 |
[IMG, SRC=>"logo.gif", ALT=>"LOGO"], |
| 136 |
$caption, |
| 137 |
[_A]; |
| 138 |
</PRE></FONT> |
| 139 |
|
| 140 |
|
| 141 |
<P><HR> |
| 142 |
<A NAME="DESCRIPTION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> DESCRIPTION</H2></A> |
| 143 |
|
| 144 |
|
| 145 |
<P>The <B>HTML::Stream</B> module provides you with an object-oriented |
| 146 |
(and subclassable) way of outputting HTML. Basically, you open up |
| 147 |
an "HTML stream" on an existing filehandle, and then do all of your |
| 148 |
output to the HTML stream. You can intermix HTML-stream-output and |
| 149 |
ordinary-print-output, if you like. |
| 150 |
|
| 151 |
|
| 152 |
<P>There's even a small built-in subclass, <B>HTML::Stream::Latin1</B>, which can |
| 153 |
handle Latin-1 input right out of the box. But all in good time... |
| 154 |
|
| 155 |
|
| 156 |
|
| 157 |
<P><HR> |
| 158 |
<A NAME="INTRODUCTION_the_Neapolitan_dessert_special"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> INTRODUCTION (the Neapolitan dessert special)</H2></A> |
| 159 |
|
| 160 |
|
| 161 |
|
| 162 |
<P><HR> |
| 163 |
<A NAME="Function_interface"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Function interface</H3></A> |
| 164 |
|
| 165 |
|
| 166 |
<P>Let's start out with the simple stuff. |
| 167 |
This module provides a collection of non-OO utility functions |
| 168 |
for escaping HTML text and producing HTML tags, like this: |
| 169 |
|
| 170 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 171 |
use HTML::Stream qw(:funcs); # imports functions from @EXPORT_OK |
| 172 |
|
| 173 |
print html_tag(A, HREF=>$url); |
| 174 |
print '&copy; 1996 by', html_escape($myname), '!'; |
| 175 |
print html_tag('/A'); |
| 176 |
</PRE></FONT> |
| 177 |
|
| 178 |
<P>By the way: that last line could be rewritten as: |
| 179 |
|
| 180 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 181 |
print html_tag(_A); |
| 182 |
</PRE></FONT> |
| 183 |
|
| 184 |
<P>And if you need to get a parameter in your tag that doesn't have an |
| 185 |
associated value, supply the <I>undefined</I> value (<I>not</I> the empty string!): |
| 186 |
|
| 187 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 188 |
print html_tag(TD, NOWRAP=>undef, ALIGN=>'LEFT'); |
| 189 |
|
| 190 |
<TD NOWRAP ALIGN=LEFT> |
| 191 |
|
| 192 |
print html_tag(IMG, SRC=>'logo.gif', ALT=>''); |
| 193 |
|
| 194 |
<IMG SRC="logo.gif" ALT=""> |
| 195 |
</PRE></FONT> |
| 196 |
|
| 197 |
<P>There are also some routines for reversing the process, like: |
| 198 |
|
| 199 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 200 |
$text = "This <i>isn't</i> &quot;fun&quot;..."; |
| 201 |
print html_unmarkup($text); |
| 202 |
|
| 203 |
This isn't &quot;fun&quot;... |
| 204 |
|
| 205 |
print html_unescape($text); |
| 206 |
|
| 207 |
This isn't "fun"... |
| 208 |
</PRE></FONT> |
| 209 |
|
| 210 |
<P><I>Yeah, yeah, yeah</I>, I hear you cry. <I>We've seen this stuff before.</I> |
| 211 |
But wait! There's more... |
| 212 |
|
| 213 |
|
| 214 |
|
| 215 |
<P><HR> |
| 216 |
<A NAME="OO_interface_vanilla"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> OO interface, vanilla</H3></A> |
| 217 |
|
| 218 |
|
| 219 |
<P>Using the function interface can be tedious... so we also |
| 220 |
provide an <B>"HTML output stream"</B> class. Messages to an instance of |
| 221 |
that class generally tell that stream to output some HTML. Here's the |
| 222 |
above example, rewritten using HTML streams: |
| 223 |
|
| 224 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 225 |
use HTML::Stream; |
| 226 |
$HTML = new HTML::Stream \*STDOUT; |
| 227 |
|
| 228 |
$HTML->tag(A, HREF=>$url); |
| 229 |
$HTML->ent('copy'); |
| 230 |
$HTML->text(" 1996 by $myname!"); |
| 231 |
$HTML->tag(_A); |
| 232 |
</PRE></FONT> |
| 233 |
|
| 234 |
<P>As you've probably guessed: |
| 235 |
|
| 236 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 237 |
text() Outputs some text, which will be HTML-escaped. |
| 238 |
|
| 239 |
tag() Outputs an ordinary tag, like <A>, possibly with parameters. |
| 240 |
The parameters will all be HTML-escaped automatically. |
| 241 |
|
| 242 |
ent() Outputs an HTML entity, like the &copy; or &lt; . |
| 243 |
You mostly don't need to use it; you can often just put the |
| 244 |
Latin-1 representation of the character in the text(). |
| 245 |
</PRE></FONT> |
| 246 |
|
| 247 |
<P>You might prefer to use <CODE>t()</CODE> and <CODE>e()</CODE> instead of <CODE>text()</CODE> |
| 248 |
and <CODE>ent()</CODE>: they're absolutely identical, and easier to type: |
| 249 |
|
| 250 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 251 |
$HTML -> tag(A, HREF=>$url); |
| 252 |
$HTML -> e('copy'); |
| 253 |
$HTML -> t(" 1996 by $myname!"); |
| 254 |
$HTML -> tag(_A); |
| 255 |
</PRE></FONT> |
| 256 |
|
| 257 |
<P>Now, it wouldn't be nice to give you those <CODE>text()</CODE> and <CODE>ent()</CODE> shortcuts |
| 258 |
without giving you one for <CODE>tag()</CODE>, would it? Of course not... |
| 259 |
|
| 260 |
|
| 261 |
|
| 262 |
<P><HR> |
| 263 |
<A NAME="OO_interface_chocolate"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> OO interface, chocolate</H3></A> |
| 264 |
|
| 265 |
|
| 266 |
<P>The known HTML tags are even given their own <B>tag-methods,</B> compiled on |
| 267 |
demand. The above code could be written even more compactly as: |
| 268 |
|
| 269 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 270 |
$HTML -> A(HREF=>$url); |
| 271 |
$HTML -> e('copy'); |
| 272 |
$HTML -> t(" 1996 by $myname!"); |
| 273 |
$HTML -> _A; |
| 274 |
</PRE></FONT> |
| 275 |
|
| 276 |
<P>As you've probably guessed: |
| 277 |
|
| 278 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 279 |
A(HREF=>$url) == tag(A, HREF=>$url) == <A HREF="/the/url"> |
| 280 |
_A == tag(_A) == </A> |
| 281 |
</PRE></FONT> |
| 282 |
|
| 283 |
<P>All of the autoloaded "tag-methods" use the tagname in <I>all-uppercase</I>. |
| 284 |
A <CODE>"_"</CODE> prefix on any tag-method means that an end-tag is desired. |
| 285 |
The <CODE>"_"</CODE> was chosen for several reasons: |
| 286 |
(1) it's short and easy to type, |
| 287 |
(2) it doesn't produce much visual clutter to look at, |
| 288 |
(3) <CODE>_TAG</CODE> looks a little like <CODE>/TAG</CODE> because of the straight line. |
| 289 |
|
| 290 |
|
| 291 |
|
| 292 |
<UL> |
| 293 |
<P><LI> |
| 294 |
<P><I>I know, I know... it looks like a private method. |
| 295 |
You get used to it. Really.</I> |
| 296 |
|
| 297 |
</UL> |
| 298 |
|
| 299 |
|
| 300 |
<P>I should stress that this module will only auto-create tag methods |
| 301 |
for <B>known</B> HTML tags. So you're protected from typos like this |
| 302 |
(which will cause a fatal exception at run-time): |
| 303 |
|
| 304 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 305 |
$HTML -> IMGG(SRC=>$src); |
| 306 |
</PRE></FONT> |
| 307 |
|
| 308 |
<P>(You're not yet protected from illegal tag parameters, but it's a start, |
| 309 |
ain't it?) |
| 310 |
|
| 311 |
|
| 312 |
<P>If you need to make a tag known (sorry, but this is currently a |
| 313 |
<I>global</I> operation, and not stream-specific), do this: |
| 314 |
|
| 315 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 316 |
accept_tag HTML::Stream 'MARQUEE'; # for you MSIE fans... |
| 317 |
</PRE></FONT> |
| 318 |
|
| 319 |
<P><B>Note: there is no corresponding "reject_tag".</B> I thought and thought |
| 320 |
about it, and could not convince myself that such a method would |
| 321 |
do anything more useful than cause other people's modules to suddenly |
| 322 |
stop working because some bozo function decided to reject the <CODE>FONT</CODE> tag. |
| 323 |
|
| 324 |
|
| 325 |
|
| 326 |
<P><HR> |
| 327 |
<A NAME="OO_interface_with_whipped_cream"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> OO interface, with whipped cream</H3></A> |
| 328 |
|
| 329 |
|
| 330 |
<P>In the grand tradition of C++, output method chaining is supported |
| 331 |
in both the Vanilla Interface and the Chocolate Interface. |
| 332 |
So you can (and probably should) write the above code as: |
| 333 |
|
| 334 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 335 |
$HTML -> A(HREF=>$url) |
| 336 |
-> e('copy') -> t(" 1996 by $myname!") |
| 337 |
-> _A; |
| 338 |
</PRE></FONT> |
| 339 |
|
| 340 |
<P><I>But wait! Neapolitan ice cream has one more flavor...</I> |
| 341 |
|
| 342 |
|
| 343 |
|
| 344 |
<P><HR> |
| 345 |
<A NAME="OO_interface_strawberry"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> OO interface, strawberry</H3></A> |
| 346 |
|
| 347 |
|
| 348 |
<P>I was jealous of the compact syntax of HTML::AsSubs, but I didn't |
| 349 |
want to worry about clogging the namespace with a lot of functions |
| 350 |
like p(), a(), etc. (especially when markup-functions like tr() conflict |
| 351 |
with existing Perl functions). So I came up with this: |
| 352 |
|
| 353 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 354 |
output $HTML [A, HREF=>$url], "Here's my $caption", [_A]; |
| 355 |
</PRE></FONT> |
| 356 |
|
| 357 |
<P>Conceptually, arrayrefs are sent to <CODE>html_tag()</CODE>, and strings to |
| 358 |
<CODE>html_escape()</CODE>. |
| 359 |
|
| 360 |
|
| 361 |
|
| 362 |
<P><HR> |
| 363 |
<A NAME="ADVANCED_TOPICS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> ADVANCED TOPICS</H2></A> |
| 364 |
|
| 365 |
|
| 366 |
|
| 367 |
<P><HR> |
| 368 |
<A NAME="Auto-formatting_and_inserting_newlines"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Auto-formatting and inserting newlines</H3></A> |
| 369 |
|
| 370 |
|
| 371 |
<P><I>Auto-formatting</I> is the name I give to the Chocolate Interface feature |
| 372 |
whereby newlines (and maybe, in the future, other things) |
| 373 |
are inserted before or after the tags you output in order to make |
| 374 |
your HTML more readable. So, by default, this: |
| 375 |
|
| 376 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 377 |
$HTML -> HTML |
| 378 |
-> HEAD |
| 379 |
-> TITLE -> t("Hello!") -> _TITLE |
| 380 |
-> _HEAD |
| 381 |
-> BODY(BGCOLOR=>'#808080'); |
| 382 |
</PRE></FONT> |
| 383 |
|
| 384 |
<P>Actually produces this: |
| 385 |
|
| 386 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 387 |
<HTML><HTML> |
| 388 |
<HEAD> |
| 389 |
<TITLE>Hello!</TITLE> |
| 390 |
</HEAD> |
| 391 |
<BODY BGCOLOR="#808080"> |
| 392 |
</PRE></FONT> |
| 393 |
|
| 394 |
<P><B>To turn off autoformatting altogether</B> on a given HTML::Stream object, |
| 395 |
use the <CODE>auto_format()</CODE> method: |
| 396 |
|
| 397 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 398 |
$HTML->auto_format(0); # stop autoformatting! |
| 399 |
</PRE></FONT> |
| 400 |
|
| 401 |
<P><B>To change whether a newline is automatically output</B> before/after the |
| 402 |
begin/end form of a tag at a <B>global</B> level, use <CODE>set_tag()</CODE>: |
| 403 |
|
| 404 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 405 |
HTML::Stream->set_tag('B', Newlines=>15); # 15 means "\n<B>\n \n</B>\n" |
| 406 |
HTML::Stream->set_tag('I', Newlines=>7); # 7 means "\n<I>\n \n</I> " |
| 407 |
</PRE></FONT> |
| 408 |
|
| 409 |
<P><B>To change whether a newline is automatically output</B> before/after the |
| 410 |
begin/end form of a tag <B>for a given stream</B> level, give the stream |
| 411 |
its own private "tag info" table, and then use <CODE>set_tag()</CODE>: |
| 412 |
|
| 413 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 414 |
$HTML->private_tags; |
| 415 |
$HTML->set_tag('B', Newlines=>0); # won't affect anyone else! |
| 416 |
</PRE></FONT> |
| 417 |
|
| 418 |
<P><B>To output newlines explicitly</B>, just use the special <CODE>nl</CODE> method |
| 419 |
in the Chocolate Interface: |
| 420 |
|
| 421 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 422 |
$HTML->nl; # one newline |
| 423 |
$HTML->nl(6); # six newlines |
| 424 |
</PRE></FONT> |
| 425 |
|
| 426 |
<P>I am sometimes asked, "why don't you put more newlines in automatically?" |
| 427 |
Well, mostly because... |
| 428 |
|
| 429 |
|
| 430 |
|
| 431 |
<UL> |
| 432 |
<P><LI> |
| 433 |
<P>Sometimes you'll be outputting stuff inside a <CODE>PRE</CODE> environment. |
| 434 |
|
| 435 |
<P><LI> |
| 436 |
<P>Sometimes you really do want to jam things (like images, or table |
| 437 |
cell delimiters and the things they contain) right up against each other. |
| 438 |
|
| 439 |
</UL> |
| 440 |
|
| 441 |
|
| 442 |
<P>So I've stuck to outputting newlines in places where it's most likely |
| 443 |
to be harmless. |
| 444 |
|
| 445 |
|
| 446 |
|
| 447 |
<P><HR> |
| 448 |
<A NAME="Entities"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Entities</H3></A> |
| 449 |
|
| 450 |
|
| 451 |
<P>As shown above, You can use the <CODE>ent()</CODE> (or <CODE>e()</CODE>) method to output |
| 452 |
an entity: |
| 453 |
|
| 454 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 455 |
$HTML->t('Copyright ')->e('copy')->t(' 1996 by Me!'); |
| 456 |
</PRE></FONT> |
| 457 |
|
| 458 |
<P>But this can be a pain, particularly for generating output with |
| 459 |
non-ASCII characters: |
| 460 |
|
| 461 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 462 |
$HTML -> t('Copyright ') |
| 463 |
-> e('copy') |
| 464 |
-> t(' 1996 by Fran') -> e('ccedil') -> t('ois, Inc.!'); |
| 465 |
</PRE></FONT> |
| 466 |
|
| 467 |
<P>Granted, Europeans can always type the 8-bit characters directly in |
| 468 |
their Perl code, and just have this: |
| 469 |
|
| 470 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 471 |
$HTML -> t("Copyright \251 1996 by Fran\347ois, Inc.!'); |
| 472 |
</PRE></FONT> |
| 473 |
|
| 474 |
<P>But folks without 8-bit text editors can find this kind of output |
| 475 |
cumbersome to generate. Sooooooooo... |
| 476 |
|
| 477 |
|
| 478 |
|
| 479 |
<P><HR> |
| 480 |
<A NAME="Auto-escaping_changing_the_way_text_is_escaped"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Auto-escaping: changing the way text is escaped</H3></A> |
| 481 |
|
| 482 |
|
| 483 |
<P><I>Auto-escaping</I> is the name I give to the act of taking an "unsafe" |
| 484 |
string (one with ">", "&", etc.), and magically outputting "safe" HTML. |
| 485 |
|
| 486 |
|
| 487 |
<P>The default "auto-escape" behavior of an HTML stream can be a drag if |
| 488 |
you've got a lot character entities that you want to output, or if |
| 489 |
you're using the Latin-1 character set, or some other input encoding. |
| 490 |
Fortunately, you can use the <CODE>auto_escape()</CODE> method to change the |
| 491 |
way a particular HTML::Stream works at any time. |
| 492 |
|
| 493 |
|
| 494 |
<P>First, here's a couple of special invocations: |
| 495 |
|
| 496 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 497 |
$HTML->auto_escape('ALL'); # Default; escapes [<>"&] and 8-bit chars. |
| 498 |
$HTML->auto_escape('LATIN_1'); # Like ALL, but uses Latin-1 entities |
| 499 |
# instead of decimal equivalents. |
| 500 |
$HTML->auto_escape('NON_ENT'); # Like ALL, but leaves "&" alone. |
| 501 |
</PRE></FONT> |
| 502 |
|
| 503 |
<P>You can also install your own auto-escape function (note |
| 504 |
that you might very well want to install it for just a little bit |
| 505 |
only, and then de-install it): |
| 506 |
|
| 507 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 508 |
sub my_auto_escape { |
| 509 |
my $text = shift; |
| 510 |
HTML::Entities::encode($text); # start with default |
| 511 |
$text =~ s/\(c\)/&copy;/ig; # (C) becomes copyright |
| 512 |
$text =~ s/\\,(c)/\&$1cedil;/ig; # \,c becomes a cedilla |
| 513 |
$text; |
| 514 |
} |
| 515 |
|
| 516 |
# Start using my auto-escape: |
| 517 |
my $old_esc = $HTML->auto_escape(\&my_auto_escape); |
| 518 |
|
| 519 |
# Output some stuff: |
| 520 |
$HTML-> IMG(SRC=>'logo.gif', ALT=>'Fran\,cois, Inc'); |
| 521 |
output $HTML 'Copyright (C) 1996 by Fran\,cois, Inc.!'; |
| 522 |
|
| 523 |
# Stop using my auto-escape: |
| 524 |
$HTML->auto_escape($old_esc); |
| 525 |
</PRE></FONT> |
| 526 |
|
| 527 |
<P>If you find yourself in a situation where you're doing this a lot, |
| 528 |
a better way is to create a <B>subclass</B> of HTML::Stream which installs |
| 529 |
your custom function when constructed. For an example, see the |
| 530 |
<B>HTML::Stream::Latin1</B> subclass in this module. |
| 531 |
|
| 532 |
|
| 533 |
|
| 534 |
<P><HR> |
| 535 |
<A NAME="Outputting_HTML_to_things_besides_filehandles"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Outputting HTML to things besides filehandles</H3></A> |
| 536 |
|
| 537 |
|
| 538 |
<P>As of Revision 1.21, you no longer need to supply <CODE>new()</CODE> with a |
| 539 |
filehandle: <I>any object that responds to a print() method will do</I>. |
| 540 |
Of course, this includes <B>blessed</B> FileHandles, and IO::Handles. |
| 541 |
|
| 542 |
|
| 543 |
<P>If you supply a GLOB reference (like <CODE>\*STDOUT</CODE>) or a string (like |
| 544 |
<CODE>"Module::FH"</CODE>), HTML::Stream will automatically create an invisible |
| 545 |
object for talking to that filehandle (I don't dare bless it into a |
| 546 |
FileHandle, since the underlying descriptor would get closed when |
| 547 |
the HTML::Stream is destroyed, and you might not want that). |
| 548 |
|
| 549 |
|
| 550 |
<P>You say you want to print to a string? For kicks and giggles, try this: |
| 551 |
|
| 552 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 553 |
package StringHandle; |
| 554 |
sub new { |
| 555 |
my $self = ''; |
| 556 |
bless \$self, shift; |
| 557 |
} |
| 558 |
sub print { |
| 559 |
my $self = shift; |
| 560 |
$$self .= join('', @_); |
| 561 |
} |
| 562 |
|
| 563 |
|
| 564 |
package main; |
| 565 |
use HTML::Stream; |
| 566 |
|
| 567 |
my $SH = new StringHandle; |
| 568 |
my $HTML = new HTML::Stream $SH; |
| 569 |
$HTML -> H1 -> t("Hello & <<welcome>>!") -> _H1; |
| 570 |
print "PRINTED STRING: ", $$SH, "\n"; |
| 571 |
</PRE></FONT> |
| 572 |
|
| 573 |
|
| 574 |
<P><HR> |
| 575 |
<A NAME="Subclassing"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Subclassing</H3></A> |
| 576 |
|
| 577 |
|
| 578 |
<P>This is where you can make your application-specific HTML-generating code |
| 579 |
<I>much</I> easier to look at. Consider this: |
| 580 |
|
| 581 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 582 |
package MY::HTML; |
| 583 |
@ISA = qw(HTML::Stream); |
| 584 |
|
| 585 |
sub Aside { |
| 586 |
$_[0] -> FONT(SIZE=>-1) -> I; |
| 587 |
} |
| 588 |
sub _Aside { |
| 589 |
$_[0] -> _I -> _FONT; |
| 590 |
} |
| 591 |
</PRE></FONT> |
| 592 |
|
| 593 |
<P>Now, you can do this: |
| 594 |
|
| 595 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 596 |
my $HTML = new MY::HTML \*STDOUT; |
| 597 |
|
| 598 |
$HTML -> Aside |
| 599 |
-> t("Don't drink the milk, it's spoiled... pass it on...") |
| 600 |
-> _Aside; |
| 601 |
</PRE></FONT> |
| 602 |
|
| 603 |
<P>If you're defining these markup-like, chocolate-interface-style functions, |
| 604 |
I recommend using mixed case with a leading capital. You probably |
| 605 |
shouldn't use all-uppercase, since that's what this module uses for |
| 606 |
real HTML tags. |
| 607 |
|
| 608 |
|
| 609 |
|
| 610 |
<P><HR> |
| 611 |
<A NAME="PUBLIC_INTERFACE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PUBLIC INTERFACE</H2></A> |
| 612 |
|
| 613 |
|
| 614 |
|
| 615 |
<P><HR> |
| 616 |
<A NAME="Functions"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Functions</H3></A> |
| 617 |
|
| 618 |
|
| 619 |
|
| 620 |
<DL> |
| 621 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:html_escape"><A NAME="item:html_escape_TEXT">html_escape TEXT</A></A></B></DT> |
| 622 |
<DD> |
| 623 |
Given a TEXT string, turn the text into valid HTML by escaping "unsafe" |
| 624 |
characters. Currently, the "unsafe" characters are 8-bit characters plus: |
| 625 |
|
| 626 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 627 |
< > = & |
| 628 |
</PRE></FONT> |
| 629 |
|
| 630 |
<P><B>Note:</B> provided for convenience and backwards-compatibility only. |
| 631 |
You may want to use the more-powerful <B>HTML::Entities::encode</B> |
| 632 |
function instead. |
| 633 |
|
| 634 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:html_tag"><A NAME="item:html_tag_TAG_PARAM_VALUE">html_tag TAG [, PARAM=>VALUE, ...]</A></A></B></DT> |
| 635 |
<DD> |
| 636 |
Return the text for a given TAG, possibly with parameters. |
| 637 |
As an efficiency hack, only the values are HTML-escaped currently: |
| 638 |
it is assumed that the tag and parameters will already be safe. |
| 639 |
|
| 640 |
|
| 641 |
<P>For convenience and readability, you can say <CODE>_A</CODE> instead of <CODE>"/A"</CODE> |
| 642 |
for the first tag, if you're into barewords. |
| 643 |
|
| 644 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:html_unescape"><A NAME="item:html_unescape_TEXT">html_unescape TEXT</A></A></B></DT> |
| 645 |
<DD> |
| 646 |
Remove angle-tag markup, and convert the standard ampersand-escapes |
| 647 |
(<CODE>lt</CODE>, <CODE>gt</CODE>, <CODE>amp</CODE>, <CODE>quot</CODE>, and <CODE>#ddd</CODE>) into ASCII characters. |
| 648 |
|
| 649 |
|
| 650 |
<P><B>Note:</B> provided for convenience and backwards-compatibility only. |
| 651 |
You may want to use the more-powerful <B>HTML::Entities::decode</B> |
| 652 |
function instead: unlike this function, it can collapse entities |
| 653 |
like <CODE>copy</CODE> and <CODE>ccedil</CODE> into their Latin-1 byte values. |
| 654 |
|
| 655 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:html_unmarkup"><A NAME="item:html_unmarkup_TEXT">html_unmarkup TEXT</A></A></B></DT> |
| 656 |
<DD> |
| 657 |
Remove angle-tag markup from TEXT, but do not convert ampersand-escapes. |
| 658 |
Cheesy, but theoretically useful if you want to, say, incorporate |
| 659 |
externally-provided HTML into a page you're generating, and are worried |
| 660 |
that the HTML might contain undesirable markup. |
| 661 |
|
| 662 |
</DL> |
| 663 |
|
| 664 |
|
| 665 |
|
| 666 |
<P><HR> |
| 667 |
<A NAME="Vanilla"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Vanilla</H3></A> |
| 668 |
|
| 669 |
|
| 670 |
|
| 671 |
<DL> |
| 672 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:new"><A NAME="item:new_PRINTABLE">new [PRINTABLE]</A></A></B></DT> |
| 673 |
<DD> |
| 674 |
<I>Class method.</I> |
| 675 |
Create a new HTML output stream. |
| 676 |
|
| 677 |
|
| 678 |
<P>The PRINTABLE may be a FileHandle, a glob reference, or any object |
| 679 |
that responds to a <CODE>print()</CODE> message. |
| 680 |
If no PRINTABLE is given, does a select() and uses that. |
| 681 |
|
| 682 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:auto_escape"><A NAME="item:auto_escape_NAME_SUBREF">auto_escape [NAME|SUBREF]</A></A></B></DT> |
| 683 |
<DD> |
| 684 |
<I>Instance method.</I> |
| 685 |
Set the auto-escape function for this HTML stream. |
| 686 |
|
| 687 |
|
| 688 |
<P>If the argument is a subroutine reference SUBREF, then that subroutine |
| 689 |
will be used. Declare such subroutines like this: |
| 690 |
|
| 691 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 692 |
sub my_escape { |
| 693 |
my $text = shift; # it's passed in the first argument |
| 694 |
... |
| 695 |
$text; |
| 696 |
} |
| 697 |
</PRE></FONT> |
| 698 |
|
| 699 |
<P>If a textual NAME is given, then one of the appropriate built-in |
| 700 |
functions is used. Possible values are: |
| 701 |
|
| 702 |
|
| 703 |
|
| 704 |
<DL> |
| 705 |
<P><DT><B><A NAME="item:ALL">ALL</A></B></DT> |
| 706 |
<DD> |
| 707 |
Default for HTML::Stream objects. This escapes angle brackets, |
| 708 |
ampersands, double-quotes, and 8-bit characters. 8-bit characters |
| 709 |
are escaped using decimal entity codes (like <CODE>#123</CODE>). |
| 710 |
|
| 711 |
<P><DT><B><A NAME="item:LATIN_1">LATIN_1</A></B></DT> |
| 712 |
<DD> |
| 713 |
Like <CODE>"ALL"</CODE>, but uses Latin-1 entity names (like <CODE>ccedil</CODE>) instead of |
| 714 |
decimal entity codes to escape characters. This makes the HTML more readable |
| 715 |
but it is currently not advised, as "older" browsers (like Netscape 2.0) |
| 716 |
do not recognize many of the ISO-8859-1 entity names (like <CODE>deg</CODE>). |
| 717 |
|
| 718 |
|
| 719 |
<P><B>Warning:</B> If you specify this option, you'll find that it attempts |
| 720 |
to "require" <B>HTML::Entities</B> at run time. That's because I didn't want |
| 721 |
to <I>force</I> you to have that module just to use the rest of HTML::Stream. |
| 722 |
To pick up problems at compile time, you are advised to say: |
| 723 |
|
| 724 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 725 |
use HTML::Stream; |
| 726 |
use HTML::Entities; |
| 727 |
</PRE></FONT> |
| 728 |
|
| 729 |
<P>in your source code. |
| 730 |
|
| 731 |
<P><DT><B><A NAME="item:NON_ENT">NON_ENT</A></B></DT> |
| 732 |
<DD> |
| 733 |
Like <CODE>"ALL"</CODE>, except that ampersands (&) are <I>not</I> escaped. |
| 734 |
This allows you to use &-entities in your text strings, while having |
| 735 |
everything else safely escaped: |
| 736 |
|
| 737 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 738 |
output $HTML "If A is an acute angle, then A > 90&deg;"; |
| 739 |
</PRE></FONT> |
| 740 |
</DL> |
| 741 |
|
| 742 |
|
| 743 |
<P>Returns the previously-installed function, in the manner of <CODE>select()</CODE>. |
| 744 |
No arguments just returns the currently-installed function. |
| 745 |
|
| 746 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:auto_format"><A NAME="item:auto_format_ONOFF">auto_format ONOFF</A></A></B></DT> |
| 747 |
<DD> |
| 748 |
<I>Instance method.</I> |
| 749 |
Set the auto-formatting characteristics for this HTML stream. |
| 750 |
Currently, all you can do is supply a single defined boolean |
| 751 |
argument, which turns auto-formatting ON (1) or OFF (0). |
| 752 |
The self object is returned. |
| 753 |
|
| 754 |
|
| 755 |
<P>Please use no other values; they are reserved for future use. |
| 756 |
|
| 757 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:comment"><A NAME="item:comment_COMMENT">comment COMMENT</A></A></B></DT> |
| 758 |
<DD> |
| 759 |
<I>Instance method.</I> |
| 760 |
Output an HTML comment. |
| 761 |
As of 1.29, a newline is automatically appended. |
| 762 |
|
| 763 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:ent"><A NAME="item:ent_ENTITY">ent ENTITY</A></A></B></DT> |
| 764 |
<DD> |
| 765 |
<I>Instance method.</I> |
| 766 |
Output an HTML entity. For example, here's how you'd output a |
| 767 |
non-breaking space: |
| 768 |
|
| 769 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 770 |
$html->ent('nbsp'); |
| 771 |
</PRE></FONT> |
| 772 |
|
| 773 |
<P>You may abbreviate this method name as <CODE>e</CODE>: |
| 774 |
|
| 775 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 776 |
$html->e('nbsp'); |
| 777 |
</PRE></FONT> |
| 778 |
|
| 779 |
<P><B>Warning:</B> this function assumes that the entity argument is legal. |
| 780 |
|
| 781 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:io">io</A></B></DT> |
| 782 |
<DD> |
| 783 |
Return the underlying output handle for this HTML stream. |
| 784 |
All you can depend upon is that it is some kind of object |
| 785 |
which responds to a print() message: |
| 786 |
|
| 787 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 788 |
$HTML->io->print("This is not auto-escaped or nuthin!"); |
| 789 |
</PRE></FONT> |
| 790 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:nl"><A NAME="item:nl_COUNT">nl [COUNT]</A></A></B></DT> |
| 791 |
<DD> |
| 792 |
<I>Instance method.</I> |
| 793 |
Output COUNT newlines. If undefined, COUNT defaults to 1. |
| 794 |
|
| 795 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:tag"><A NAME="item:tag_TAGNAME_PARAM_VALUE">tag TAGNAME [, PARAM=>VALUE, ...]</A></A></B></DT> |
| 796 |
<DD> |
| 797 |
<I>Instance method.</I> |
| 798 |
Output a tag. Returns the self object, to allow method chaining. |
| 799 |
You can say <CODE>_A</CODE> instead of <CODE>"/A"</CODE>, if you're into barewords. |
| 800 |
|
| 801 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:text"><A NAME="item:text_TEXT">text TEXT...</A></A></B></DT> |
| 802 |
<DD> |
| 803 |
<I>Instance method.</I> |
| 804 |
Output some text. You may abbreviate this method name as <CODE>t</CODE>: |
| 805 |
|
| 806 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 807 |
$html->t('Hi there, ', $yournamehere, '!'); |
| 808 |
</PRE></FONT> |
| 809 |
|
| 810 |
<P>Returns the self object, to allow method chaining. |
| 811 |
|
| 812 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:text_nbsp"><A NAME="item:text_nbsp_TEXT">text_nbsp TEXT...</A></A></B></DT> |
| 813 |
<DD> |
| 814 |
<I>Instance method.</I> |
| 815 |
Output some text, but with all spaces output as non-breaking-space |
| 816 |
characters: |
| 817 |
|
| 818 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 819 |
$html->t("To list your home directory, type: ") |
| 820 |
->text_nbsp("ls -l ~yourname.") |
| 821 |
</PRE></FONT> |
| 822 |
|
| 823 |
<P>Returns the self object, to allow method chaining. |
| 824 |
|
| 825 |
</DL> |
| 826 |
|
| 827 |
|
| 828 |
|
| 829 |
<P><HR> |
| 830 |
<A NAME="Strawberry"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Strawberry</H3></A> |
| 831 |
|
| 832 |
|
| 833 |
|
| 834 |
<DL> |
| 835 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:output"><A NAME="item:output_ITEM_ITEM">output ITEM,...,ITEM</A></A></B></DT> |
| 836 |
<DD> |
| 837 |
<I>Instance method.</I> |
| 838 |
Go through the items. If an item is an arrayref, treat it like |
| 839 |
the array argument to html_tag() and output the result. If an item |
| 840 |
is a text string, escape the text and output the result. Like this: |
| 841 |
|
| 842 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 843 |
output $HTML [A, HREF=>$url], "Here's my $caption!", [_A]; |
| 844 |
</PRE></FONT> |
| 845 |
</DL> |
| 846 |
|
| 847 |
|
| 848 |
|
| 849 |
<P><HR> |
| 850 |
<A NAME="Chocolate"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> Chocolate</H3></A> |
| 851 |
|
| 852 |
|
| 853 |
|
| 854 |
<DL> |
| 855 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:accept_tag"><A NAME="item:accept_tag_TAG">accept_tag TAG</A></A></B></DT> |
| 856 |
<DD> |
| 857 |
<I>Class method.</I> |
| 858 |
Declares that the tag is to be accepted as valid HTML (if it isn't already). |
| 859 |
For example, this... |
| 860 |
|
| 861 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 862 |
# Make sure methods MARQUEE and _MARQUEE are compiled on demand: |
| 863 |
HTML::Stream->accept_tag('MARQUEE'); |
| 864 |
</PRE></FONT> |
| 865 |
|
| 866 |
<P>...gives the Chocolate Interface permission to create (via AUTOLOAD) |
| 867 |
definitions for the MARQUEE and _MARQUEE methods, so you can then say: |
| 868 |
|
| 869 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 870 |
$HTML -> MARQUEE -> t("Hi!") -> _MARQUEE; |
| 871 |
</PRE></FONT> |
| 872 |
|
| 873 |
<P>If you want to set the default attribute of the tag as well, you can |
| 874 |
do so via the set_tag() method instead; it will effectively do an |
| 875 |
accept_tag() as well. |
| 876 |
|
| 877 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 878 |
# Make sure methods MARQUEE and _MARQUEE are compiled on demand, |
| 879 |
# *and*, set the characteristics of that tag. |
| 880 |
HTML::Stream->set_tag('MARQUEE', Newlines=>9); |
| 881 |
</PRE></FONT> |
| 882 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:private_tags">private_tags</A></B></DT> |
| 883 |
<DD> |
| 884 |
<I>Instance method.</I> |
| 885 |
Normally, HTML streams use a reference to a global table of tag |
| 886 |
information to determine how to do such things as auto-formatting, |
| 887 |
and modifications made to that table by <CODE>set_tag</CODE> will |
| 888 |
affect everyone. |
| 889 |
|
| 890 |
|
| 891 |
<P>However, if you want an HTML stream to have a private copy of that |
| 892 |
table to munge with, just send it this message after creating it. |
| 893 |
Like this: |
| 894 |
|
| 895 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 896 |
my $HTML = new HTML::Stream \*STDOUT; |
| 897 |
$HTML->private_tags; |
| 898 |
</PRE></FONT> |
| 899 |
|
| 900 |
<P>Then, you can say stuff like: |
| 901 |
|
| 902 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 903 |
$HTML->set_tag('PRE', Newlines=>0); |
| 904 |
$HTML->set_tag('BLINK', Newlines=>9); |
| 905 |
</PRE></FONT> |
| 906 |
|
| 907 |
<P>And it won't affect anyone else's <I>auto-formatting</I> (although they will |
| 908 |
possibly be able to use the BLINK tag method without a fatal |
| 909 |
exception <CODE>:-(</CODE> ). |
| 910 |
|
| 911 |
|
| 912 |
<P>Returns the self object. |
| 913 |
|
| 914 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:set_tag"><A NAME="item:set_tag_TAG_TAGINFO">set_tag TAG, [TAGINFO...]</A></A></B></DT> |
| 915 |
<DD> |
| 916 |
<I>Class/instance method.</I> |
| 917 |
Accept the given TAG in the Chocolate Interface, and (if TAGINFO |
| 918 |
is given) alter its characteristics when being output. |
| 919 |
|
| 920 |
|
| 921 |
|
| 922 |
<UL> |
| 923 |
<P><LI> |
| 924 |
<P><B>If invoked as a class method,</B> this alters the "master tag table", |
| 925 |
and allows a new tag to be supported via an autoloaded method: |
| 926 |
|
| 927 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 928 |
HTML::Stream->set_tag('MARQUEE', Newlines=>9); |
| 929 |
</PRE></FONT> |
| 930 |
|
| 931 |
<P>Once you do this, <I>all</I> HTML streams you open from then on |
| 932 |
will allow that tag to be output in the chocolate interface. |
| 933 |
|
| 934 |
<P><LI> |
| 935 |
<P><B>If invoked as an instance method,</B> this alters the "tag table" referenced |
| 936 |
by that HTML stream, usually for the purpose of affecting things like |
| 937 |
the auto-formatting on that HTML stream. |
| 938 |
|
| 939 |
|
| 940 |
<P><B>Warning:</B> by default, an HTML stream just references the "master tag table" |
| 941 |
(this makes <CODE>new()</CODE> more efficient), so <I>by default, the |
| 942 |
instance method will behave exactly like the class method.</I> |
| 943 |
|
| 944 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 945 |
my $HTML = new HTML::Stream \*STDOUT; |
| 946 |
$HTML->set_tag('BLINK', Newlines=>0); # changes it for others! |
| 947 |
</PRE></FONT> |
| 948 |
|
| 949 |
<P>If you want to diddle with <I>one</I> stream's auto-formatting <I>only,</I> |
| 950 |
you'll need to give that stream its own <I>private</I> tag table. Like this: |
| 951 |
|
| 952 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 953 |
my $HTML = new HTML::Stream \*STDOUT; |
| 954 |
$HTML->private_tags; |
| 955 |
$HTML->set_tag('BLINK', Newlines=>0); # doesn't affect other streams |
| 956 |
</PRE></FONT> |
| 957 |
|
| 958 |
<P><B>Note:</B> this will still force an default entry for BLINK in the <I>master</I> |
| 959 |
tag table: otherwise, we'd never know that it was legal to AUTOLOAD a |
| 960 |
BLINK method. However, it will only alter the <I>characteristics</I> of the |
| 961 |
BLINK tag (like auto-formatting) in the <I>object's</I> tag table. |
| 962 |
|
| 963 |
</UL> |
| 964 |
|
| 965 |
|
| 966 |
<P>The TAGINFO, if given, is a set of key=>value pairs with the following |
| 967 |
possible keys: |
| 968 |
|
| 969 |
|
| 970 |
|
| 971 |
<DL> |
| 972 |
<P><DT><B><A NAME="item:Newlines">Newlines</A></B></DT> |
| 973 |
<DD> |
| 974 |
Assumed to be a number which encodes how newlines are to be output |
| 975 |
before/after a tag. The value is the logical OR (or sum) of a set of flags: |
| 976 |
|
| 977 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 978 |
0x01 newline before <TAG> .<TAG>. .</TAG>. |
| 979 |
0x02 newline after <TAG> | | | | |
| 980 |
0x04 newline before </TAG> 1 2 4 8 |
| 981 |
0x08 newline after </TAG> |
| 982 |
</PRE></FONT> |
| 983 |
|
| 984 |
<P>Hence, to output BLINK environments which are preceded/followed by newlines: |
| 985 |
|
| 986 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 987 |
set_tag HTML::Stream 'BLINK', Newlines=>9; |
| 988 |
</PRE></FONT> |
| 989 |
</DL> |
| 990 |
|
| 991 |
|
| 992 |
<P>Returns the self object on success. |
| 993 |
|
| 994 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:tags">tags</A></B></DT> |
| 995 |
<DD> |
| 996 |
<I>Class/instance method.</I> |
| 997 |
Returns an unsorted list of all tags in the class/instance tag table |
| 998 |
(see <CODE>set_tag</CODE> for class/instance method differences). |
| 999 |
|
| 1000 |
</DL> |
| 1001 |
|
| 1002 |
|
| 1003 |
|
| 1004 |
<P><HR> |
| 1005 |
<A NAME="SUBCLASSES"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> SUBCLASSES</H2></A> |
| 1006 |
|
| 1007 |
|
| 1008 |
|
| 1009 |
<P><HR> |
| 1010 |
<A NAME="HTML_Stream_Latin1"><H3><A HREF="#__TOP__"><IMG SRC="icons/h2bullet.gif" ALT="Top" BORDER="0"></A> HTML::Stream::Latin1</H3></A> |
| 1011 |
|
| 1012 |
|
| 1013 |
<P>A small, public package for outputting Latin-1 markup. Its |
| 1014 |
default auto-escape function is <CODE>LATIN_1</CODE>, which tries to output |
| 1015 |
the mnemonic entity markup (e.g., <CODE>&ccedil;</CODE>) for ISO-8859-1 characters. |
| 1016 |
|
| 1017 |
|
| 1018 |
<P>So using HTML::Stream::Latin1 like this: |
| 1019 |
|
| 1020 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 1021 |
use HTML::Stream; |
| 1022 |
|
| 1023 |
$HTML = new HTML::Stream::Latin1 \*STDOUT; |
| 1024 |
output $HTML "\253A right angle is 90\260, \277No?\273\n"; |
| 1025 |
</PRE></FONT> |
| 1026 |
|
| 1027 |
<P>Prints this: |
| 1028 |
|
| 1029 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 1030 |
&laquo;A right angle is 90&deg;, &iquest;No?&raquo; |
| 1031 |
</PRE></FONT> |
| 1032 |
|
| 1033 |
<P>Instead of what HTML::Stream would print, which is this: |
| 1034 |
|
| 1035 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 1036 |
&#171;A right angle is 90&#176;, &#191;No?&#187; |
| 1037 |
</PRE></FONT> |
| 1038 |
|
| 1039 |
<P><B>Warning:</B> a lot of Latin-1 HTML markup is not recognized by older |
| 1040 |
browsers (e.g., Netscape 2.0). Consider using HTML::Stream; it will output |
| 1041 |
the decimal entities which currently seem to be more "portable". |
| 1042 |
|
| 1043 |
|
| 1044 |
<P><B>Note:</B> using this class "requires" that you have HTML::Entities. |
| 1045 |
|
| 1046 |
|
| 1047 |
|
| 1048 |
<P><HR> |
| 1049 |
<A NAME="PERFORMANCE"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> PERFORMANCE</H2></A> |
| 1050 |
|
| 1051 |
|
| 1052 |
<P>Slower than I'd like. Both the output() method and the various "tag" |
| 1053 |
methods seem to run about 5 times slower than the old |
| 1054 |
just-hardcode-the-darn stuff approach. That is, in general, this: |
| 1055 |
|
| 1056 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 1057 |
### Approach #1... |
| 1058 |
tag $HTML 'A', HREF=>"$href"; |
| 1059 |
tag $HTML 'IMG', SRC=>"logo.gif", ALT=>"LOGO"; |
| 1060 |
text $HTML $caption; |
| 1061 |
tag $HTML '_A'; |
| 1062 |
text $HTML $a_lot_of_text; |
| 1063 |
</PRE></FONT> |
| 1064 |
|
| 1065 |
<P>And this: |
| 1066 |
|
| 1067 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 1068 |
### Approach #2... |
| 1069 |
output $HTML [A, HREF=>"$href"], |
| 1070 |
[IMG, SRC=>"logo.gif", ALT=>"LOGO"], |
| 1071 |
$caption, |
| 1072 |
[_A]; |
| 1073 |
output $HTML $a_lot_of_text; |
| 1074 |
</PRE></FONT> |
| 1075 |
|
| 1076 |
<P>And this: |
| 1077 |
|
| 1078 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 1079 |
### Approach #3... |
| 1080 |
$HTML -> A(HREF=>"$href") |
| 1081 |
-> IMG(SRC=>"logo.gif", ALT=>"LOGO") |
| 1082 |
-> t($caption) |
| 1083 |
-> _A |
| 1084 |
-> t($a_lot_of_text); |
| 1085 |
</PRE></FONT> |
| 1086 |
|
| 1087 |
<P>Each run about 5x slower than this: |
| 1088 |
|
| 1089 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 1090 |
### Approach #4... |
| 1091 |
print '<A HREF="', html_escape($href), '>', |
| 1092 |
'<IMG SRC="logo.gif" ALT="LOGO">', |
| 1093 |
html_escape($caption), |
| 1094 |
'</A>'; |
| 1095 |
print html_escape($a_lot_of_text); |
| 1096 |
</PRE></FONT> |
| 1097 |
|
| 1098 |
<P>Of course, I'd much rather use any of first three <I>(especially #3)</I> |
| 1099 |
if I had to get something done right in a hurry. Or did you not notice |
| 1100 |
the typo in approach #4? <CODE>;-)</CODE> |
| 1101 |
|
| 1102 |
|
| 1103 |
<P>(BTW, thanks to Benchmark:: for allowing me to... er... benchmark stuff.) |
| 1104 |
|
| 1105 |
|
| 1106 |
|
| 1107 |
<P><HR> |
| 1108 |
<A NAME="VERSION"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> VERSION</H2></A> |
| 1109 |
|
| 1110 |
|
| 1111 |
<P>$Id: Stream.pm,v 1.54 2001/08/20 20:33:26 eryq Exp $ |
| 1112 |
|
| 1113 |
|
| 1114 |
|
| 1115 |
<P><HR> |
| 1116 |
<A NAME="CHANGE_LOG"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> CHANGE LOG</H2></A> |
| 1117 |
|
| 1118 |
|
| 1119 |
|
| 1120 |
<DL> |
| 1121 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:Version"><A NAME="item:Version_1_54_2001_08_20">Version 1.54 (2001/08/20)</A></A></B></DT> |
| 1122 |
<DD> |
| 1123 |
The terms-of-use have been placed in the distribution file "COPYING". |
| 1124 |
Also, small documentation tweaks were made. |
| 1125 |
|
| 1126 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:Version"><A NAME="item:Version_1_51_2001_08_16">Version 1.51 (2001/08/16)</A></A></B></DT> |
| 1127 |
<DD> |
| 1128 |
No real changes to code; just improved documentation, |
| 1129 |
and removed HTML::Entities and HTML::Parser from ./etc |
| 1130 |
at CPAN's request. |
| 1131 |
|
| 1132 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:Version"><A NAME="item:Version_1_47_2000_06_10">Version 1.47 (2000/06/10)</A></A></B></DT> |
| 1133 |
<DD> |
| 1134 |
No real changes to code; just improved documentation. |
| 1135 |
|
| 1136 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:Version"><A NAME="item:Version_1_45_1999_02_09">Version 1.45 (1999/02/09)</A></A></B></DT> |
| 1137 |
<DD> |
| 1138 |
Cleanup for Perl 5.005: removed duplicate typeglob assignments. |
| 1139 |
|
| 1140 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:Version"><A NAME="item:Version_1_44_1998_01_14">Version 1.44 (1998/01/14)</A></A></B></DT> |
| 1141 |
<DD> |
| 1142 |
Win95 install (5.004) now works. |
| 1143 |
Added SYNOPSIS to POD. |
| 1144 |
|
| 1145 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:Version"><A NAME="item:Version_1_41_1998_01_02">Version 1.41 (1998/01/02)</A></A></B></DT> |
| 1146 |
<DD> |
| 1147 |
Removed $& for efficiency. |
| 1148 |
<I>Thanks, Andreas!</I> |
| 1149 |
|
| 1150 |
|
| 1151 |
<P>Added support for OPTION, and default now puts newlines after SELECT |
| 1152 |
and /SELECT. Also altered "TELEM" syntax to put newline after end-tags |
| 1153 |
of list element tags (like /OPTION, /LI, etc.). In theory, this change |
| 1154 |
could produce undesireable results for folks who embed lists inside of PRE |
| 1155 |
environments... however, that kind of stuff was done in the days before |
| 1156 |
TABLEs; also, you can always turn it off if you really need to. |
| 1157 |
<I>Thanks to John D Groenveld for these patches.</I> |
| 1158 |
|
| 1159 |
|
| 1160 |
<P>Added text_nbsp(). |
| 1161 |
<I>Thanks to John D Groenveld for the patch.</I> |
| 1162 |
This method may also be invoked as nbsp_text() as in the original patch, |
| 1163 |
but that's sort of a private tip-of-the-hat to the patch author, and the |
| 1164 |
synonym may go away in the future. |
| 1165 |
|
| 1166 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:Version"><A NAME="item:Version_1_37_1997_02_09">Version 1.37 (1997/02/09)</A></A></B></DT> |
| 1167 |
<DD> |
| 1168 |
No real change; just trying to make CPAN.pm happier. |
| 1169 |
|
| 1170 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:Version"><A NAME="item:Version_1_32_1997_01_12">Version 1.32 (1997/01/12)</A></A></B></DT> |
| 1171 |
<DD> |
| 1172 |
<B>NEW TOOL for generating Perl code which uses HTML::Stream!</B> |
| 1173 |
Check your toolkit for <B>html2perlstream</B>. |
| 1174 |
|
| 1175 |
|
| 1176 |
<P>Added built-in support for escaping 8-bit characters. |
| 1177 |
|
| 1178 |
|
| 1179 |
<P>Added <CODE>LATIN_1</CODE> auto-escape, which uses HTML::Entities to generate |
| 1180 |
mnemonic entities. This is now the default method for HTML::Stream::Latin1. |
| 1181 |
|
| 1182 |
|
| 1183 |
<P>Added <CODE>auto_format(),</CODE> |
| 1184 |
so you can now turn auto-formatting off/on. |
| 1185 |
|
| 1186 |
|
| 1187 |
<P>Added <CODE>private_tags()</CODE>, |
| 1188 |
so it is now possible for HTML streams to each have their own "private" |
| 1189 |
copy of the %Tags table, for use by <CODE>set_tag()</CODE>. |
| 1190 |
|
| 1191 |
|
| 1192 |
<P>Added <CODE>set_tag()</CODE>. The tags tables may now be modified dynamically so |
| 1193 |
as to change how formatting is done on-the-fly. This will hopefully not |
| 1194 |
compromise the efficiency of the chocolate interface (until now, |
| 1195 |
the formatting was compiled into the method itself), and <I>will</I> add |
| 1196 |
greater flexibility for more-complex programs. |
| 1197 |
|
| 1198 |
|
| 1199 |
<P>Added POD documentation for all subroutines in the public interface. |
| 1200 |
|
| 1201 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:Version"><A NAME="item:Version_1_29_1996_12_10">Version 1.29 (1996/12/10)</A></A></B></DT> |
| 1202 |
<DD> |
| 1203 |
Added terminating newline to comment(). |
| 1204 |
<I>Thanks to John D Groenveld for the suggestion and the patch.</I> |
| 1205 |
|
| 1206 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:Version"><A NAME="item:Version_1_27_1996_12_10">Version 1.27 (1996/12/10)</A></A></B></DT> |
| 1207 |
<DD> |
| 1208 |
Added built-in HTML::Stream::Latin1, which does a very simple encoding |
| 1209 |
of all characters above ASCII 127. |
| 1210 |
|
| 1211 |
|
| 1212 |
<P>Fixed bug in accept_tag(), where 'my' variable was shadowing argument. |
| 1213 |
<I>Thanks to John D Groenveld for the bug report and the patch.</I> |
| 1214 |
|
| 1215 |
<P><DT><B><A HREF="#__TOP__"><IMG SRC="icons/itembullet.gif" ALT="Top" BORDER="0"></A> <A NAME="item:Version"><A NAME="item:Version_1_26_1996_09_27">Version 1.26 (1996/09/27)</A></A></B></DT> |
| 1216 |
<DD> |
| 1217 |
Start of history. |
| 1218 |
|
| 1219 |
</DL> |
| 1220 |
|
| 1221 |
|
| 1222 |
|
| 1223 |
<P><HR> |
| 1224 |
<A NAME="ACKNOWLEDGEMENTS"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> ACKNOWLEDGEMENTS</H2></A> |
| 1225 |
|
| 1226 |
|
| 1227 |
<P>Warmest thanks to... |
| 1228 |
|
| 1229 |
<FONT SIZE=3 FACE="courier"><PRE> |
| 1230 |
John Buckman For suggesting that I write an "html2perlstream", |
| 1231 |
and inspiring me to look at supporting Latin-1. |
| 1232 |
Tony Cebzanov For suggesting that I write an "html2perlstream" |
| 1233 |
John D Groenveld Bug reports, patches, and suggestions |
| 1234 |
B. K. Oxley (binkley) For suggesting the support of "writing to strings" |
| 1235 |
which became the "printable" interface. |
| 1236 |
</PRE></FONT> |
| 1237 |
|
| 1238 |
|
| 1239 |
<P><HR> |
| 1240 |
<A NAME="AUTHOR"><H2><A HREF="#__TOP__"><IMG SRC="icons/h1bullet.gif" ALT="Top" BORDER="0"></A> AUTHOR</H2></A> |
| 1241 |
|
| 1242 |
|
| 1243 |
<P>Eryq (<I><FILE><A HREF="mailto:[email protected]">[email protected]</A></FILE></I>). |
| 1244 |
President, ZeeGee Software Inc. (<I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I>). |
| 1245 |
|
| 1246 |
|
| 1247 |
<P>Go to <I><FILE><A HREF="http://www.zeegee.com">http://www.zeegee.com</A></FILE></I> for the latest downloads |
| 1248 |
and on-line documentation for this module. |
| 1249 |
|
| 1250 |
|
| 1251 |
<P>Enjoy. Yell if it breaks. |
| 1252 |
|
| 1253 |
<P><HR> |
| 1254 |
<ADDRESS><FONT SIZE=-1> |
| 1255 |
Generated Mon Aug 20 16:33:54 2001 by cvu_pod2html |
| 1256 |
</FONT></ADDRESS> |
| 1257 |
</FONT></BODY> |
| 1258 |
</HTML> |