Debian Codegraph @

docs/HTML/Stream.pm.html

raw
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=&gt;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=&gt;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=&gt;$link);
105 print html_escape(&quot;&lt;&lt;Hello &amp; welcome!&gt;&gt;&quot;);
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-&gt;tag('A', HREF=&gt;&quot;$href&quot;);
116 $HTML-&gt;tag('IMG', SRC=&gt;&quot;logo.gif&quot;, ALT=&gt;&quot;LOGO&quot;);
117 $HTML-&gt;text($copyright);
118 $HTML-&gt;tag('_A');
119
120 # The chocolate interface...
121 $HTML -&gt; A(HREF=&gt;&quot;$href&quot;);
122 $HTML -&gt; IMG(SRC=&gt;&quot;logo.gif&quot;, ALT=&gt;&quot;LOGO&quot;);
123 $HTML -&gt; t($caption);
124 $HTML -&gt; _A;
125
126 # The chocolate interface, with whipped cream...
127 $HTML -&gt; A(HREF=&gt;&quot;$href&quot;)
128 -&gt; IMG(SRC=&gt;&quot;logo.gif&quot;, ALT=&gt;&quot;LOGO&quot;)
129 -&gt; t($caption)
130 -&gt; _A;
131 </PRE></FONT>
132 <FONT SIZE=3 FACE="courier"><PRE>
133 # The strawberry interface...
134 output $HTML [A, HREF=&gt;&quot;$href&quot;],
135 [IMG, SRC=&gt;&quot;logo.gif&quot;, ALT=&gt;&quot;LOGO&quot;],
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 &quot;HTML stream&quot; 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=&gt;$url);
174 print '&amp;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=&gt;undef, ALIGN=&gt;'LEFT');
189
190 &lt;TD NOWRAP ALIGN=LEFT&gt;
191
192 print html_tag(IMG, SRC=&gt;'logo.gif', ALT=&gt;'');
193
194 &lt;IMG SRC=&quot;logo.gif&quot; ALT=&quot;&quot;&gt;
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 = &quot;This &lt;i&gt;isn't&lt;/i&gt; &amp;quot;fun&amp;quot;...&quot;;
201 print html_unmarkup($text);
202
203 This isn't &amp;quot;fun&amp;quot;...
204
205 print html_unescape($text);
206
207 This isn't &quot;fun&quot;...
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>&quot;HTML output stream&quot;</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-&gt;tag(A, HREF=&gt;$url);
229 $HTML-&gt;ent('copy');
230 $HTML-&gt;text(&quot; 1996 by $myname!&quot;);
231 $HTML-&gt;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 &lt;A&gt;, possibly with parameters.
240 The parameters will all be HTML-escaped automatically.
241
242 ent() Outputs an HTML entity, like the &amp;copy; or &amp;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 -&gt; tag(A, HREF=&gt;$url);
252 $HTML -&gt; e('copy');
253 $HTML -&gt; t(&quot; 1996 by $myname!&quot;);
254 $HTML -&gt; 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 -&gt; A(HREF=&gt;$url);
271 $HTML -&gt; e('copy');
272 $HTML -&gt; t(&quot; 1996 by $myname!&quot;);
273 $HTML -&gt; _A;
274 </PRE></FONT>
275
276 <P>As you've probably guessed:
277
278 <FONT SIZE=3 FACE="courier"><PRE>
279 A(HREF=&gt;$url) == tag(A, HREF=&gt;$url) == &lt;A HREF=&quot;/the/url&quot;&gt;
280 _A == tag(_A) == &lt;/A&gt;
281 </PRE></FONT>
282
283 <P>All of the autoloaded &quot;tag-methods&quot; use the tagname in <I>all-uppercase</I>.
284 A <CODE>&quot;_&quot;</CODE> prefix on any tag-method means that an end-tag is desired.
285 The <CODE>&quot;_&quot;</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 -&gt; IMGG(SRC=&gt;$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 &quot;reject_tag&quot;.</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 -&gt; A(HREF=&gt;$url)
336 -&gt; e('copy') -&gt; t(&quot; 1996 by $myname!&quot;)
337 -&gt; _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=&gt;$url], &quot;Here's my $caption&quot;, [_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 -&gt; HTML
378 -&gt; HEAD
379 -&gt; TITLE -&gt; t(&quot;Hello!&quot;) -&gt; _TITLE
380 -&gt; _HEAD
381 -&gt; BODY(BGCOLOR=&gt;'#808080');
382 </PRE></FONT>
383
384 <P>Actually produces this:
385
386 <FONT SIZE=3 FACE="courier"><PRE>
387 &lt;HTML&gt;&lt;HTML&gt;
388 &lt;HEAD&gt;
389 &lt;TITLE&gt;Hello!&lt;/TITLE&gt;
390 &lt;/HEAD&gt;
391 &lt;BODY BGCOLOR=&quot;#808080&quot;&gt;
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-&gt;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-&gt;set_tag('B', Newlines=&gt;15); # 15 means &quot;\n&lt;B&gt;\n \n&lt;/B&gt;\n&quot;
406 HTML::Stream-&gt;set_tag('I', Newlines=&gt;7); # 7 means &quot;\n&lt;I&gt;\n \n&lt;/I&gt; &quot;
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 &quot;tag info&quot; table, and then use <CODE>set_tag()</CODE>:
412
413 <FONT SIZE=3 FACE="courier"><PRE>
414 $HTML-&gt;private_tags;
415 $HTML-&gt;set_tag('B', Newlines=&gt;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-&gt;nl; # one newline
423 $HTML-&gt;nl(6); # six newlines
424 </PRE></FONT>
425
426 <P>I am sometimes asked, &quot;why don't you put more newlines in automatically?&quot;
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-&gt;t('Copyright ')-&gt;e('copy')-&gt;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 -&gt; t('Copyright ')
463 -&gt; e('copy')
464 -&gt; t(' 1996 by Fran') -&gt; e('ccedil') -&gt; 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 -&gt; t(&quot;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 &quot;unsafe&quot;
484 string (one with &quot;&gt;&quot;, &quot;&amp;&quot;, etc.), and magically outputting &quot;safe&quot; HTML.
485
486
487 <P>The default &quot;auto-escape&quot; 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-&gt;auto_escape('ALL'); # Default; escapes [&lt;&gt;&quot;&amp;] and 8-bit chars.
498 $HTML-&gt;auto_escape('LATIN_1'); # Like ALL, but uses Latin-1 entities
499 # instead of decimal equivalents.
500 $HTML-&gt;auto_escape('NON_ENT'); # Like ALL, but leaves &quot;&amp;&quot; 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\)/&amp;copy;/ig; # (C) becomes copyright
512 $text =~ s/\\,(c)/\&amp;$1cedil;/ig; # \,c becomes a cedilla
513 $text;
514 }
515
516 # Start using my auto-escape:
517 my $old_esc = $HTML-&gt;auto_escape(\&amp;my_auto_escape);
518
519 # Output some stuff:
520 $HTML-&gt; IMG(SRC=&gt;'logo.gif', ALT=&gt;'Fran\,cois, Inc');
521 output $HTML 'Copyright (C) 1996 by Fran\,cois, Inc.!';
522
523 # Stop using my auto-escape:
524 $HTML-&gt;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>&quot;Module::FH&quot;</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 -&gt; H1 -&gt; t(&quot;Hello &amp; &lt;&lt;welcome&gt;&gt;!&quot;) -&gt; _H1;
570 print &quot;PRINTED STRING: &quot;, $$SH, &quot;\n&quot;;
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] -&gt; FONT(SIZE=&gt;-1) -&gt; I;
587 }
588 sub _Aside {
589 $_[0] -&gt; _I -&gt; _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 -&gt; Aside
599 -&gt; t(&quot;Don't drink the milk, it's spoiled... pass it on...&quot;)
600 -&gt; _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 &quot;unsafe&quot;
624 characters. Currently, the &quot;unsafe&quot; characters are 8-bit characters plus:
625
626 <FONT SIZE=3 FACE="courier"><PRE>
627 &lt; &gt; = &amp;
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=&gt;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>&quot;/A&quot;</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>&quot;ALL&quot;</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 &quot;older&quot; 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 &quot;require&quot; <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>&quot;ALL&quot;</CODE>, except that ampersands (&amp;) are <I>not</I> escaped.
734 This allows you to use &amp;-entities in your text strings, while having
735 everything else safely escaped:
736
737 <FONT SIZE=3 FACE="courier"><PRE>
738 output $HTML &quot;If A is an acute angle, then A &gt; 90&amp;deg;&quot;;
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-&gt;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-&gt;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-&gt;io-&gt;print(&quot;This is not auto-escaped or nuthin!&quot;);
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=&gt;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>&quot;/A&quot;</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-&gt;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-&gt;t(&quot;To list your home directory, type: &quot;)
820 -&gt;text_nbsp(&quot;ls -l ~yourname.&quot;)
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=&gt;$url], &quot;Here's my $caption!&quot;, [_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-&gt;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 -&gt; MARQUEE -&gt; t(&quot;Hi!&quot;) -&gt; _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-&gt;set_tag('MARQUEE', Newlines=&gt;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-&gt;private_tags;
898 </PRE></FONT>
899
900 <P>Then, you can say stuff like:
901
902 <FONT SIZE=3 FACE="courier"><PRE>
903 $HTML-&gt;set_tag('PRE', Newlines=&gt;0);
904 $HTML-&gt;set_tag('BLINK', Newlines=&gt;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 &quot;master tag table&quot;,
925 and allows a new tag to be supported via an autoloaded method:
926
927 <FONT SIZE=3 FACE="courier"><PRE>
928 HTML::Stream-&gt;set_tag('MARQUEE', Newlines=&gt;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 &quot;tag table&quot; 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 &quot;master tag table&quot;
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-&gt;set_tag('BLINK', Newlines=&gt;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-&gt;private_tags;
955 $HTML-&gt;set_tag('BLINK', Newlines=&gt;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=&gt;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 &lt;TAG&gt; .&lt;TAG&gt;. .&lt;/TAG&gt;.
979 0x02 newline after &lt;TAG&gt; | | | |
980 0x04 newline before &lt;/TAG&gt; 1 2 4 8
981 0x08 newline after &lt;/TAG&gt;
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=&gt;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>&amp;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 &quot;\253A right angle is 90\260, \277No?\273\n&quot;;
1025 </PRE></FONT>
1026
1027 <P>Prints this:
1028
1029 <FONT SIZE=3 FACE="courier"><PRE>
1030 &amp;laquo;A right angle is 90&amp;deg;, &amp;iquest;No?&amp;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 &amp;#171;A right angle is 90&amp;#176;, &amp;#191;No?&amp;#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 &quot;portable&quot;.
1042
1043
1044 <P><B>Note:</B> using this class &quot;requires&quot; 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 &quot;tag&quot;
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=&gt;&quot;$href&quot;;
1059 tag $HTML 'IMG', SRC=&gt;&quot;logo.gif&quot;, ALT=&gt;&quot;LOGO&quot;;
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=&gt;&quot;$href&quot;],
1070 [IMG, SRC=&gt;&quot;logo.gif&quot;, ALT=&gt;&quot;LOGO&quot;],
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 -&gt; A(HREF=&gt;&quot;$href&quot;)
1081 -&gt; IMG(SRC=&gt;&quot;logo.gif&quot;, ALT=&gt;&quot;LOGO&quot;)
1082 -&gt; t($caption)
1083 -&gt; _A
1084 -&gt; 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 '&lt;A HREF=&quot;', html_escape($href), '&gt;',
1092 '&lt;IMG SRC=&quot;logo.gif&quot; ALT=&quot;LOGO&quot;&gt;',
1093 html_escape($caption),
1094 '&lt;/A&gt;';
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 &quot;COPYING&quot;.
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 $&amp; 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 &quot;TELEM&quot; 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 &quot;private&quot;
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 &quot;html2perlstream&quot;,
1231 and inspiring me to look at supporting Latin-1.
1232 Tony Cebzanov For suggesting that I write an &quot;html2perlstream&quot;
1233 John D Groenveld Bug reports, patches, and suggestions
1234 B. K. Oxley (binkley) For suggesting the support of &quot;writing to strings&quot;
1235 which became the &quot;printable&quot; 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>