HTML-Stream: README

"Fossies" - the Fresh Open Source Software Archive

Member "HTML-Stream-1.60/README" (7 Aug 2008, 31790 Bytes) of package /linux/www/old/HTML-Stream-1.60.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

1 NAME 2 HTML::Stream - HTML output stream class, and some markup utilities 3 4 SYNOPSIS 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 41 DESCRIPTION 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 51 INTRODUCTION (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 isn't "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 193 ADVANCED 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\n \n\n" 223 HTML::Stream->set_tag('I', Newlines=>7); # 7 means "\n\n \n " 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 374 PUBLIC 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 643 SUBCLASSES 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 670 PERFORMANCE 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 716 VERSION 717 $Id: Stream.pm,v 1.60 2008/08/06 dstaal Exp $ 718 719 CHANGE 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 823 COPYRIGHT 824 This program is free software. You may copy or redistribute it under the 825 same terms as Perl itself. 826 827 ACKNOWLEDGEMENTS 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 839 AUTHOR 840 Daniel T. Staal (DStaal@usa.net). 841 842 Enjoy. Yell if it breaks. 843