| 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 <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 |
|
| 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<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 |
|
| 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 ([email protected]). |
| 841 |
|
| 842 |
Enjoy. Yell if it breaks. |
| 843 |
|