1NAME
2 HTML::Stream - HTML output stream class, and some markup utilities
3
4SYNOPSIS
5 Here's small sample of some of the non-OO ways you can use this module:
6
7 use HTML::Stream qw(:funcs);
8
9 print html_tag('A', HREF=>$link);
10 print html_escape("<<Hello & welcome!>>");
11
12 And some of the OO ways as well:
13
14 use HTML::Stream;
15 $HTML = new HTML::Stream \*STDOUT;
16
17 # The vanilla interface...
18 $HTML->tag('A', HREF=>"$href");
19 $HTML->tag('IMG', SRC=>"logo.gif", ALT=>"LOGO");
20 $HTML->text($copyright);
21 $HTML->tag('_A');
22
23 # The chocolate interface...
24 $HTML -> A(HREF=>"$href");
25 $HTML -> IMG(SRC=>"logo.gif", ALT=>"LOGO");
26 $HTML -> t($caption);
27 $HTML -> _A;
28
29 # The chocolate interface, with whipped cream...
30 $HTML -> A(HREF=>"$href")
31 -> IMG(SRC=>"logo.gif", ALT=>"LOGO")
32 -> t($caption)
33 -> _A;
34
35 # The strawberry interface...
36 output $HTML [A, HREF=>"$href"],
37 [IMG, SRC=>"logo.gif", ALT=>"LOGO"],
38 $caption,
39 [_A];
40
41DESCRIPTION
42 The HTML::Stream module provides you with an object-oriented (and
43 subclassable) way of outputting HTML. Basically, you open up an "HTML
44 stream" on an existing filehandle, and then do all of your output to the
45 HTML stream. You can intermix HTML-stream-output and
46 ordinary-print-output, if you like.
47
48 There's even a small built-in subclass, HTML::Stream::Latin1, which can
49 handle Latin-1 input right out of the box. But all in good time...
50
51INTRODUCTION (the Neapolitan dessert special)
52 Function interface
53 Let's start out with the simple stuff. This module provides a collection
54 of non-OO utility functions for escaping HTML text and producing HTML
55 tags, like this:
56
57 use HTML::Stream qw(:funcs); # imports functions from @EXPORT_OK
58
59 print html_tag(A, HREF=>$url);
60 print '© 1996 by', html_escape($myname), '!';
61 print html_tag('/A');
62
63 By the way: that last line could be rewritten as:
64
65 print html_tag(_A);
66
67 And if you need to get a parameter in your tag that doesn't have an
68 associated value, supply the *undefined* value (*not* the empty
69 string!):
70
71 print html_tag(TD, NOWRAP=>undef, ALIGN=>'LEFT');
72
73 <TD NOWRAP ALIGN=LEFT>
74
75 print html_tag(IMG, SRC=>'logo.gif', ALT=>'');
76
77 <IMG SRC="logo.gif" ALT="">
78
79 There are also some routines for reversing the process, like:
80
81 $text = "This <i>isn't</i> "fun"...";
82 print html_unmarkup($text);
83
84 This isn't "fun"...
85
86 print html_unescape($text);
87
88 This isn't "fun"...
89
90 *Yeah, yeah, yeah*, I hear you cry. *We've seen this stuff before.* But
91 wait! There's more...
92
93 OO interface, vanilla
94 Using the function interface can be tedious... so we also provide an
95 "HTML output stream" class. Messages to an instance of that class
96 generally tell that stream to output some HTML. Here's the above
97 example, rewritten using HTML streams:
98
99 use HTML::Stream;
100 $HTML = new HTML::Stream \*STDOUT;
101
102 $HTML->tag(A, HREF=>$url);
103 $HTML->ent('copy');
104 $HTML->text(" 1996 by $myname!");
105 $HTML->tag(_A);
106
107 As you've probably guessed:
108
109 text() Outputs some text, which will be HTML-escaped.
110
111 tag() Outputs an ordinary tag, like <A>, possibly with parameters.
112 The parameters will all be HTML-escaped automatically.
113
114 ent() Outputs an HTML entity, like the © or < .
115 You mostly don't need to use it; you can often just put the
116 Latin-1 representation of the character in the text().
117
118 You might prefer to use "t()" and "e()" instead of "text()" and "ent()":
119 they're absolutely identical, and easier to type:
120
121 $HTML -> tag(A, HREF=>$url);
122 $HTML -> e('copy');
123 $HTML -> t(" 1996 by $myname!");
124 $HTML -> tag(_A);
125
126 Now, it wouldn't be nice to give you those "text()" and "ent()"
127 shortcuts without giving you one for "tag()", would it? Of course not...
128
129 OO interface, chocolate
130 The known HTML tags are even given their own tag-methods, compiled on
131 demand. The above code could be written even more compactly as:
132
133 $HTML -> A(HREF=>$url);
134 $HTML -> e('copy');
135 $HTML -> t(" 1996 by $myname!");
136 $HTML -> _A;
137
138 As you've probably guessed:
139
140 A(HREF=>$url) == tag(A, HREF=>$url) == <A HREF="/the/url">
141 _A == tag(_A) == </A>
142
143 All of the autoloaded "tag-methods" use the tagname in *all-uppercase*.
144 A "_" prefix on any tag-method means that an end-tag is desired. The "_"
145 was chosen for several reasons: (1) it's short and easy to type, (2) it
146 doesn't produce much visual clutter to look at, (3) "_TAG" looks a
147 little like "/TAG" because of the straight line.
148
149 * *I know, I know... it looks like a private method. You get used to
150 it. Really.*
151
152 I should stress that this module will only auto-create tag methods for
153 known HTML tags. So you're protected from typos like this (which will
154 cause a fatal exception at run-time):
155
156 $HTML -> IMGG(SRC=>$src);
157
158 (You're not yet protected from illegal tag parameters, but it's a start,
159 ain't it?)
160
161 If you need to make a tag known (sorry, but this is currently a *global*
162 operation, and not stream-specific), do this:
163
164 accept_tag HTML::Stream 'MARQUEE'; # for you MSIE fans...
165
166 Note: there is no corresponding "reject_tag". I thought and thought
167 about it, and could not convince myself that such a method would do
168 anything more useful than cause other people's modules to suddenly stop
169 working because some bozo function decided to reject the "FONT" tag.
170
171 OO interface, with whipped cream
172 In the grand tradition of C++, output method chaining is supported in
173 both the Vanilla Interface and the Chocolate Interface. So you can (and
174 probably should) write the above code as:
175
176 $HTML -> A(HREF=>$url)
177 -> e('copy') -> t(" 1996 by $myname!")
178 -> _A;
179
180 *But wait! Neapolitan ice cream has one more flavor...*
181
182 OO interface, strawberry
183 I was jealous of the compact syntax of HTML::AsSubs, but I didn't want
184 to worry about clogging the namespace with a lot of functions like p(),
185 a(), etc. (especially when markup-functions like tr() conflict with
186 existing Perl functions). So I came up with this:
187
188 output $HTML [A, HREF=>$url], "Here's my $caption", [_A];
189
190 Conceptually, arrayrefs are sent to "html_tag()", and strings to
191 "html_escape()".
192
193ADVANCED TOPICS
194 Auto-formatting and inserting newlines
195 *Auto-formatting* is the name I give to the Chocolate Interface feature
196 whereby newlines (and maybe, in the future, other things) are inserted
197 before or after the tags you output in order to make your HTML more
198 readable. So, by default, this:
199
200 $HTML -> HTML
201 -> HEAD
202 -> TITLE -> t("Hello!") -> _TITLE
203 -> _HEAD
204 -> BODY(BGCOLOR=>'#808080');
205
206 Actually produces this:
207
208 <HTML><HTML>
209 <HEAD>
210 <TITLE>Hello!</TITLE>
211 </HEAD>
212 <BODY BGCOLOR="#808080">
213
214 To turn off autoformatting altogether on a given HTML::Stream object,
215 use the "auto_format()" method:
216
217 $HTML->auto_format(0); # stop autoformatting!
218
219 To change whether a newline is automatically output before/after the
220 begin/end form of a tag at a global level, use "set_tag()":
221
222 HTML::Stream->set_tag('B', Newlines=>15); # 15 means "\n<B>\n \n</B>\n"
223 HTML::Stream->set_tag('I', Newlines=>7); # 7 means "\n<I>\n \n</I> "
224
225 To change whether a newline is automatically output before/after the
226 begin/end form of a tag for a given stream level, give the stream its
227 own private "tag info" table, and then use "set_tag()":
228
229 $HTML->private_tags;
230 $HTML->set_tag('B', Newlines=>0); # won't affect anyone else!
231
232 To output newlines explicitly, just use the special "nl" method in the
233 Chocolate Interface:
234
235 $HTML->nl; # one newline
236 $HTML->nl(6); # six newlines
237
238 I am sometimes asked, "why don't you put more newlines in
239 automatically?" Well, mostly because...
240
241 * Sometimes you'll be outputting stuff inside a "PRE" environment.
242
243 * Sometimes you really do want to jam things (like images, or table
244 cell delimiters and the things they contain) right up against each
245 other.
246
247 So I've stuck to outputting newlines in places where it's most likely to
248 be harmless.
249
250 Entities
251 As shown above, You can use the "ent()" (or "e()") method to output an
252 entity:
253
254 $HTML->t('Copyright ')->e('copy')->t(' 1996 by Me!');
255
256 But this can be a pain, particularly for generating output with
257 non-ASCII characters:
258
259 $HTML -> t('Copyright ')
260 -> e('copy')
261 -> t(' 1996 by Fran') -> e('ccedil') -> t('ois, Inc.!');
262
263 Granted, Europeans can always type the 8-bit characters directly in
264 their Perl code, and just have this:
265
266 $HTML -> t("Copyright \251 1996 by Fran\347ois, Inc.!');
267
268 But folks without 8-bit text editors can find this kind of output
269 cumbersome to generate. Sooooooooo...
270
271 Auto-escaping: changing the way text is escaped
272 *Auto-escaping* is the name I give to the act of taking an "unsafe"
273 string (one with ">", "&", etc.), and magically outputting "safe" HTML.
274
275 The default "auto-escape" behavior of an HTML stream can be a drag if
276 you've got a lot character entities that you want to output, or if
277 you're using the Latin-1 character set, or some other input encoding.
278 Fortunately, you can use the "auto_escape()" method to change the way a
279 particular HTML::Stream works at any time.
280
281 First, here's a couple of special invocations:
282
283 $HTML->auto_escape('ALL'); # Default; escapes [<>"&] and 8-bit chars.
284 $HTML->auto_escape('LATIN_1'); # Like ALL, but uses Latin-1 entities
285 # instead of decimal equivalents.
286 $HTML->auto_escape('NON_ENT'); # Like ALL, but leaves "&" alone.
287
288 You can also install your own auto-escape function (note that you might
289 very well want to install it for just a little bit only, and then
290 de-install it):
291
292 sub my_auto_escape {
293 my $text = shift;
294 HTML::Entities::encode($text); # start with default
295 $text =~ s/\(c\)/©/ig; # (C) becomes copyright
296 $text =~ s/\\,(c)/\&$1cedil;/ig; # \,c becomes a cedilla
297 $text;
298 }
299
300 # Start using my auto-escape:
301 my $old_esc = $HTML->auto_escape(\&my_auto_escape);
302
303 # Output some stuff:
304 $HTML-> IMG(SRC=>'logo.gif', ALT=>'Fran\,cois, Inc');
305 output $HTML 'Copyright (C) 1996 by Fran\,cois, Inc.!';
306
307 # Stop using my auto-escape:
308 $HTML->auto_escape($old_esc);
309
310 If you find yourself in a situation where you're doing this a lot, a
311 better way is to create a subclass of HTML::Stream which installs your
312 custom function when constructed. For an example, see the
313 HTML::Stream::Latin1 subclass in this module.
314
315 Outputting HTML to things besides filehandles
316 As of Revision 1.21, you no longer need to supply "new()" with a
317 filehandle: *any object that responds to a print() method will do*. Of
318 course, this includes blessed FileHandles, and IO::Handles.
319
320 If you supply a GLOB reference (like "\*STDOUT") or a string (like
321 "Module::FH"), HTML::Stream will automatically create an invisible
322 object for talking to that filehandle (I don't dare bless it into a
323 FileHandle, since the underlying descriptor would get closed when the
324 HTML::Stream is destroyed, and you might not want that).
325
326 You say you want to print to a string? For kicks and giggles, try this:
327
328 package StringHandle;
329 sub new {
330 my $self = '';
331 bless \$self, shift;
332 }
333 sub print {
334 my $self = shift;
335 $$self .= join('', @_);
336 }
337
338
339 package main;
340 use HTML::Stream;
341
342 my $SH = new StringHandle;
343 my $HTML = new HTML::Stream $SH;
344 $HTML -> H1 -> t("Hello & <<welcome>>!") -> _H1;
345 print "PRINTED STRING: ", $$SH, "\n";
346
347 Subclassing
348 This is where you can make your application-specific HTML-generating
349 code *much* easier to look at. Consider this:
350
351 package MY::HTML;
352 @ISA = qw(HTML::Stream);
353
354 sub Aside {
355 $_[0] -> FONT(SIZE=>-1) -> I;
356 }
357 sub _Aside {
358 $_[0] -> _I -> _FONT;
359 }
360
361 Now, you can do this:
362
363 my $HTML = new MY::HTML \*STDOUT;
364
365 $HTML -> Aside
366 -> t("Don't drink the milk, it's spoiled... pass it on...")
367 -> _Aside;
368
369 If you're defining these markup-like, chocolate-interface-style
370 functions, I recommend using mixed case with a leading capital. You
371 probably shouldn't use all-uppercase, since that's what this module uses
372 for real HTML tags.
373
374PUBLIC INTERFACE
375 Functions
376 html_escape TEXT
377 Given a TEXT string, turn the text into valid HTML by escaping
378 "unsafe" characters. Currently, the "unsafe" characters are 8-bit
379 characters plus:
380
381 < > = &
382
383 Note: provided for convenience and backwards-compatibility only. You
384 may want to use the more-powerful HTML::Entities::encode function
385 instead.
386
387 html_tag TAG [, PARAM=>VALUE, ...]
388 Return the text for a given TAG, possibly with parameters. As an
389 efficiency hack, only the values are HTML-escaped currently: it is
390 assumed that the tag and parameters will already be safe.
391
392 For convenience and readability, you can say "_A" instead of "/A"
393 for the first tag, if you're into barewords.
394
395 html_unescape TEXT
396 Remove angle-tag markup, and convert the standard ampersand-escapes
397 ("lt", "gt", "amp", "quot", and "#ddd") into ASCII characters.
398
399 Note: provided for convenience and backwards-compatibility only. You
400 may want to use the more-powerful HTML::Entities::decode function
401 instead: unlike this function, it can collapse entities like "copy"
402 and "ccedil" into their Latin-1 byte values.
403
404 html_unmarkup TEXT
405 Remove angle-tag markup from TEXT, but do not convert
406 ampersand-escapes. Cheesy, but theoretically useful if you want to,
407 say, incorporate externally-provided HTML into a page you're
408 generating, and are worried that the HTML might contain undesirable
409 markup.
410
411 Vanilla
412 new [PRINTABLE]
413 *Class method.* Create a new HTML output stream.
414
415 The PRINTABLE may be a FileHandle, a glob reference, or any object
416 that responds to a "print()" message. If no PRINTABLE is given, does
417 a select() and uses that.
418
419 auto_escape [NAME|SUBREF]
420 *Instance method.* Set the auto-escape function for this HTML
421 stream.
422
423 If the argument is a subroutine reference SUBREF, then that
424 subroutine will be used. Declare such subroutines like this:
425
426 sub my_escape {
427 my $text = shift; # it's passed in the first argument
428 ...
429 $text;
430 }
431
432 If a textual NAME is given, then one of the appropriate built-in
433 functions is used. Possible values are:
434
435 ALL Default for HTML::Stream objects. This escapes angle brackets,
436 ampersands, double-quotes, and 8-bit characters. 8-bit
437 characters are escaped using decimal entity codes (like "#123").
438
439 LATIN_1
440 Like "ALL", but uses Latin-1 entity names (like "ccedil")
441 instead of decimal entity codes to escape characters. This makes
442 the HTML more readable but it is currently not advised, as
443 "older" browsers (like Netscape 2.0) do not recognize many of
444 the ISO-8859-1 entity names (like "deg").
445
446 Warning: If you specify this option, you'll find that it
447 attempts to "require" HTML::Entities at run time. That's because
448 I didn't want to *force* you to have that module just to use the
449 rest of HTML::Stream. To pick up problems at compile time, you
450 are advised to say:
451
452 use HTML::Stream;
453 use HTML::Entities;
454
455 in your source code.
456
457 NON_ENT
458 Like "ALL", except that ampersands (&) are *not* escaped. This
459 allows you to use &-entities in your text strings, while having
460 everything else safely escaped:
461
462 output $HTML "If A is an acute angle, then A > 90°";
463
464 Returns the previously-installed function, in the manner of
465 "select()". No arguments just returns the currently-installed
466 function.
467
468 auto_format ONOFF
469 *Instance method.* Set the auto-formatting characteristics for this
470 HTML stream. Currently, all you can do is supply a single defined
471 boolean argument, which turns auto-formatting ON (1) or OFF (0). The
472 self object is returned.
473
474 Please use no other values; they are reserved for future use.
475
476 comment COMMENT
477 *Instance method.* Output an HTML comment. As of 1.29, a newline is
478 automatically appended.
479
480 ent ENTITY
481 *Instance method.* Output an HTML entity. For example, here's how
482 you'd output a non-breaking space:
483
484 $html->ent('nbsp');
485
486 You may abbreviate this method name as "e":
487
488 $html->e('nbsp');
489
490 Warning: this function assumes that the entity argument is legal.
491
492 io Return the underlying output handle for this HTML stream. All you
493 can depend upon is that it is some kind of object which responds to
494 a print() message:
495
496 $HTML->io->print("This is not auto-escaped or nuthin!");
497
498 nl [COUNT]
499 *Instance method.* Output COUNT newlines. If undefined, COUNT
500 defaults to 1.
501
502 tag TAGNAME [, PARAM=>VALUE, ...]
503 *Instance method.* Output a tag. Returns the self object, to allow
504 method chaining. You can say "_A" instead of "/A", if you're into
505 barewords.
506
507 text TEXT...
508 *Instance method.* Output some text. You may abbreviate this method
509 name as "t":
510
511 $html->t('Hi there, ', $yournamehere, '!');
512
513 Returns the self object, to allow method chaining.
514
515 text_nbsp TEXT...
516 *Instance method.* Output some text, but with all spaces output as
517 non-breaking-space characters:
518
519 $html->t("To list your home directory, type: ")
520 ->text_nbsp("ls -l ~yourname.")
521
522 Returns the self object, to allow method chaining.
523
524 Strawberry
525 output ITEM,...,ITEM
526 *Instance method.* Go through the items. If an item is an arrayref,
527 treat it like the array argument to html_tag() and output the
528 result. If an item is a text string, escape the text and output the
529 result. Like this:
530
531 output $HTML [A, HREF=>$url], "Here's my $caption!", [_A];
532
533 Chocolate
534 accept_tag TAG
535 *Class method.* Declares that the tag is to be accepted as valid
536 HTML (if it isn't already). For example, this...
537
538 # Make sure methods MARQUEE and _MARQUEE are compiled on demand:
539 HTML::Stream->accept_tag('MARQUEE');
540
541 ...gives the Chocolate Interface permission to create (via AUTOLOAD)
542 definitions for the MARQUEE and _MARQUEE methods, so you can then
543 say:
544
545 $HTML -> MARQUEE -> t("Hi!") -> _MARQUEE;
546
547 If you want to set the default attribute of the tag as well, you can
548 do so via the set_tag() method instead; it will effectively do an
549 accept_tag() as well.
550
551 # Make sure methods MARQUEE and _MARQUEE are compiled on demand,
552 # *and*, set the characteristics of that tag.
553 HTML::Stream->set_tag('MARQUEE', Newlines=>9);
554
555 private_tags
556 *Instance method.* Normally, HTML streams use a reference to a
557 global table of tag information to determine how to do such things
558 as auto-formatting, and modifications made to that table by
559 "set_tag" will affect everyone.
560
561 However, if you want an HTML stream to have a private copy of that
562 table to munge with, just send it this message after creating it.
563 Like this:
564
565 my $HTML = new HTML::Stream \*STDOUT;
566 $HTML->private_tags;
567
568 Then, you can say stuff like:
569
570 $HTML->set_tag('PRE', Newlines=>0);
571 $HTML->set_tag('BLINK', Newlines=>9);
572
573 And it won't affect anyone else's *auto-formatting* (although they
574 will possibly be able to use the BLINK tag method without a fatal
575 exception ":-(" ).
576
577 Returns the self object.
578
579 set_tag TAG, [TAGINFO...]
580 *Class/instance method.* Accept the given TAG in the Chocolate
581 Interface, and (if TAGINFO is given) alter its characteristics when
582 being output.
583
584 * If invoked as a class method, this alters the "master tag
585 table", and allows a new tag to be supported via an autoloaded
586 method:
587
588 HTML::Stream->set_tag('MARQUEE', Newlines=>9);
589
590 Once you do this, *all* HTML streams you open from then on will
591 allow that tag to be output in the chocolate interface.
592
593 * If invoked as an instance method, this alters the "tag table"
594 referenced by that HTML stream, usually for the purpose of
595 affecting things like the auto-formatting on that HTML stream.
596
597 Warning: by default, an HTML stream just references the "master
598 tag table" (this makes "new()" more efficient), so *by default,
599 the instance method will behave exactly like the class method.*
600
601 my $HTML = new HTML::Stream \*STDOUT;
602 $HTML->set_tag('BLINK', Newlines=>0); # changes it for others!
603
604 If you want to diddle with *one* stream's auto-formatting
605 *only,* you'll need to give that stream its own *private* tag
606 table. Like this:
607
608 my $HTML = new HTML::Stream \*STDOUT;
609 $HTML->private_tags;
610 $HTML->set_tag('BLINK', Newlines=>0); # doesn't affect other streams
611
612 Note: this will still force an default entry for BLINK in the
613 *master* tag table: otherwise, we'd never know that it was legal
614 to AUTOLOAD a BLINK method. However, it will only alter the
615 *characteristics* of the BLINK tag (like auto-formatting) in the
616 *object's* tag table.
617
618 The TAGINFO, if given, is a set of key=>value pairs with the
619 following possible keys:
620
621 Newlines
622 Assumed to be a number which encodes how newlines are to be
623 output before/after a tag. The value is the logical OR (or sum)
624 of a set of flags:
625
626 0x01 newline before <TAG> .<TAG>. .</TAG>.
627 0x02 newline after <TAG> | | | |
628 0x04 newline before </TAG> 1 2 4 8
629 0x08 newline after </TAG>
630
631 Hence, to output BLINK environments which are preceded/followed
632 by newlines:
633
634 set_tag HTML::Stream 'BLINK', Newlines=>9;
635
636 Returns the self object on success.
637
638 tags
639 *Class/instance method.* Returns an unsorted list of all tags in the
640 class/instance tag table (see "set_tag" for class/instance method
641 differences).
642
643SUBCLASSES
644 HTML::Stream::Latin1
645 A small, public package for outputting Latin-1 markup. Its default
646 auto-escape function is "LATIN_1", which tries to output the mnemonic
647 entity markup (e.g., "ç") for ISO-8859-1 characters.
648
649 So using HTML::Stream::Latin1 like this:
650
651 use HTML::Stream;
652
653 $HTML = new HTML::Stream::Latin1 \*STDOUT;
654 output $HTML "\253A right angle is 90\260, \277No?\273\n";
655
656 Prints this:
657
658 «A right angle is 90°, ¿No?»
659
660 Instead of what HTML::Stream would print, which is this:
661
662 «A right angle is 90°, ¿No?»
663
664 Warning: a lot of Latin-1 HTML markup is not recognized by older
665 browsers (e.g., Netscape 2.0). Consider using HTML::Stream; it will
666 output the decimal entities which currently seem to be more "portable".
667
668 Note: using this class "requires" that you have HTML::Entities.
669
670PERFORMANCE
671 Slower than I'd like. Both the output() method and the various "tag"
672 methods seem to run about 5 times slower than the old
673 just-hardcode-the-darn stuff approach. That is, in general, this:
674
675 ### Approach #1...
676 tag $HTML 'A', HREF=>"$href";
677 tag $HTML 'IMG', SRC=>"logo.gif", ALT=>"LOGO";
678 text $HTML $caption;
679 tag $HTML '_A';
680 text $HTML $a_lot_of_text;
681
682 And this:
683
684 ### Approach #2...
685 output $HTML [A, HREF=>"$href"],
686 [IMG, SRC=>"logo.gif", ALT=>"LOGO"],
687 $caption,
688 [_A];
689 output $HTML $a_lot_of_text;
690
691 And this:
692
693 ### Approach #3...
694 $HTML -> A(HREF=>"$href")
695 -> IMG(SRC=>"logo.gif", ALT=>"LOGO")
696 -> t($caption)
697 -> _A
698 -> t($a_lot_of_text);
699
700 Each run about 5x slower than this:
701
702 ### Approach #4...
703 print '<A HREF="', html_escape($href), '>',
704 '<IMG SRC="logo.gif" ALT="LOGO">',
705 html_escape($caption),
706 '</A>';
707 print html_escape($a_lot_of_text);
708
709 Of course, I'd much rather use any of first three *(especially #3)* if I
710 had to get something done right in a hurry. Or did you not notice the
711 typo in approach #4? ";-)"
712
713 (BTW, thanks to Benchmark:: for allowing me to... er... benchmark
714 stuff.)
715
716VERSION
717 $Id: Stream.pm,v 1.60 2008/08/06 dstaal Exp $
718
719CHANGE LOG
720 Version 1.60 (2008/08/06)
721 Fixed up the tests some more, updated changelog. (Which I'd
722 forgotten about...)
723
724 Version 1.59 (2008/06/01)
725 Better tests, better Meta.yml.
726
727 Version 1.58 (2008/05/28)
728 Another attempt at cleanup, as well expanding the Meta.yml file.
729
730 Version 1.57 (2008/05/28)
731 Cleaned up the Mac-specific files that were getting created in the
732 archive.
733
734 Version 1.56 (2008/05/27)
735 Added the start of a testing suite. In the process, I found an
736 error: HTML defines the tag 'NOFRAMES', not 'NOFRAME'. Both are
737 currently in the tag list, but consider 'NOFRAME' depriciated.
738
739 The test suite requires Test::More and Test::Output.
740
741 Version 1.55 (2003/10/28)
742 New maintainer: Daniel T. Staal. No major changes in the code,
743 except to complete the tag list to HTML 4.01 specifications. (With
744 the exception of the 'S' tag, which I want to test, and is
745 depreciated anyway. Note that the DOCTYPE is not actually a HTML
746 tag, and is not currently included.)
747
748 Version 1.54 (2001/08/20)
749 The terms-of-use have been placed in the distribution file
750 "COPYING". Also, small documentation tweaks were made.
751
752 Version 1.51 (2001/08/16)
753 No real changes to code; just improved documentation, and removed
754 HTML::Entities and HTML::Parser from ./etc at CPAN's request.
755
756 Version 1.47 (2000/06/10)
757 No real changes to code; just improved documentation.
758
759 Version 1.45 (1999/02/09)
760 Cleanup for Perl 5.005: removed duplicate typeglob assignments.
761
762 Version 1.44 (1998/01/14)
763 Win95 install (5.004) now works. Added SYNOPSIS to POD.
764
765 Version 1.41 (1998/01/02)
766 Removed $& for efficiency. *Thanks, Andreas!*
767
768 Added support for OPTION, and default now puts newlines after SELECT
769 and /SELECT. Also altered "TELEM" syntax to put newline after
770 end-tags of list element tags (like /OPTION, /LI, etc.). In theory,
771 this change could produce undesireable results for folks who embed
772 lists inside of PRE environments... however, that kind of stuff was
773 done in the days before TABLEs; also, you can always turn it off if
774 you really need to. *Thanks to John D Groenveld for these patches.*
775
776 Added text_nbsp(). *Thanks to John D Groenveld for the patch.* This
777 method may also be invoked as nbsp_text() as in the original patch,
778 but that's sort of a private tip-of-the-hat to the patch author, and
779 the synonym may go away in the future.
780
781 Version 1.37 (1997/02/09)
782 No real change; just trying to make CPAN.pm happier.
783
784 Version 1.32 (1997/01/12)
785 NEW TOOL for generating Perl code which uses HTML::Stream! Check
786 your toolkit for html2perlstream.
787
788 Added built-in support for escaping 8-bit characters.
789
790 Added "LATIN_1" auto-escape, which uses HTML::Entities to generate
791 mnemonic entities. This is now the default method for
792 HTML::Stream::Latin1.
793
794 Added "auto_format()," so you can now turn auto-formatting off/on.
795
796 Added "private_tags()", so it is now possible for HTML streams to
797 each have their own "private" copy of the %Tags table, for use by
798 "set_tag()".
799
800 Added "set_tag()". The tags tables may now be modified dynamically
801 so as to change how formatting is done on-the-fly. This will
802 hopefully not compromise the efficiency of the chocolate interface
803 (until now, the formatting was compiled into the method itself), and
804 *will* add greater flexibility for more-complex programs.
805
806 Added POD documentation for all subroutines in the public interface.
807
808 Version 1.29 (1996/12/10)
809 Added terminating newline to comment(). *Thanks to John D Groenveld
810 for the suggestion and the patch.*
811
812 Version 1.27 (1996/12/10)
813 Added built-in HTML::Stream::Latin1, which does a very simple
814 encoding of all characters above ASCII 127.
815
816 Fixed bug in accept_tag(), where 'my' variable was shadowing
817 argument. *Thanks to John D Groenveld for the bug report and the
818 patch.*
819
820 Version 1.26 (1996/09/27)
821 Start of history.
822
823COPYRIGHT
824 This program is free software. You may copy or redistribute it under the
825 same terms as Perl itself.
826
827ACKNOWLEDGEMENTS
828 Warmest thanks to...
829
830 Eryq For writing the orginal version of this module.
831
832 John Buckman For suggesting that I write an "html2perlstream",
833 and inspiring me to look at supporting Latin-1.
834 Tony Cebzanov For suggesting that I write an "html2perlstream"
835 John D Groenveld Bug reports, patches, and suggestions
836 B. K. Oxley (binkley) For suggesting the support of "writing to strings"
837 which became the "printable" interface.
838
839AUTHOR
840 Daniel T. Staal (DStaal@usa.net).
841
842 Enjoy. Yell if it breaks.
843
844
