libHTML.pm

Contents


Module Description

This is yet another HTML/CGI module. Why? Well, I did not like the way most of the other modules did things. I wanted something more compact, and more directed to my needs. Besides, it's been fun!

The paradigm here is: you create a new libHTML object, complete with destination, and any methods you invoke print to that destination. This is much more concise in some respects, and somewhat limiting in others. All-in-all, I find it much better than most others, which is why I wrote it! One of the things I like best is that you can string method calls together.

For example, in Lincoln Stein's CGI.PM you would say something like:

	$query = new CGI;
	open OUT ">out";
	print OUT $query->hr;
	print OUT $query->h3("Reviews");
	print OUT $query->em("What a silly art exhibit!");
	print OUT $query->a({href=>"silly.html"}, "Silly");
whereas in libHTML you would say:
	$h = new libHTML("out");
	$h->HR->H3("Reviews");
	$h->EM('What a silly art exhibit!')->A("Silly", HREF => "silly.html");
NOTE: This module assumes that you have a working knowledge of HTML, and only facilitates its use in a perl script. If you don't know HTML, you will have trouble using this module.


Business Stuff

Version

This file documents the following version of libHTML: 1.10.00 (08-Nov-98)

Copyright

Copyright © 1997-8 Joseph L. Casadonte Jr. All rights reserved.

This code provided and distributed under the terms of Larry Wall's Artistic License (http://www.perl.com/perl/misc/Artistic.html) and GNU's Library General Public License (http://www.gnu.org/copyleft/lgpl.html). Both are distributed as part of this package. Where the two conflict, the Artistic License takes precedence.

Disclaimer

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

I do not guarantee ANYTHING with this package. If you use it you are doing so AT YOUR OWN RISK! I may or may not support this depending on my time schedule.


Features/Limits/Future

Features

Limits

Future


Installation Instructions

Simply copy the libHTML.pm file into your \PERL\LIB directory.


Bug Reports

Please send bug reports to Joe Casadonte (joc@netaxs.com). Include the following (as appropriate):

What version of Perl and libHTML do I have?


Obtaining the Latest Version

You can grab it from my homepage (http://www.netaxs.com/~joc/perl.html) or from a CPAN site near you (see below).


For More Information on Perl

CPAN - Comprehensive Perl Archive Network - Selected Sites


Basic Usage

First off, you need to get a new libHTML object. When created, the object can be directed to output to STDOUT or a file. The new libHTML object will automatically initialize itself with any CGI parameters, if appropriate.
	use libHTML;
	my($h) = new LibHTML("out.html");
You can access CGI parameters with the Param method. If the parameter was set on the command line or in the environment, the value will be returned. If not, undef will be returned.
	my($password) = $h->Param('password');
If creating output for a CGI command, you would then start with some basic CGI and HTML.
	$h->StartCGI->StartHTML;
You can also customize StartCGI to send cookies, and StartHTML to set things like the title and META attributtes.
	$h->SetCookie('Cookie1', 'ChocoChip');
	$data{'ID'} = 'foo';
	$data{'PWD'} = 'bar';
	$time = libHTML::expdate(time + 86400);
	$h->SetCookie('Cookie2', \%data, EXPIRES => $time);
	$h->StartCGI('Cookie1', 'Cookie2');
	$h->StartHTML(TITLE => 'Foo Bar Homepage', META => {keywords => "foo bar"});
Then, you start adding HTML. Some commands have multiple ways of invoking them, depending on whether or not the content spans multiple lines.
	$h->H1('This is a heading');
	$h->STRONG('This is a strong message')->P;
	$h->sSTRONG;
	$h->Text('this is a paragraph')->BR;
	$h->Text('second line')->BR if $second;
	$h->eSTRONG;
The module gives you control over the output, as far as where to put newlines (NL) and indenting (ID). Newlines and indenting are important when viewing HTML source; if you don't put them in, all of the HTML will be on a single line. The browser will ignore both of them, of course.
	$h->H1('This is a heading')->NL;
	$h->STRONG('This is a strong message')->NL->P->NL;
	$h->sUL->NL;
		$h->ID->LI->Text('foo');
		$h->ID->LI->Text('bar');
		$h->ID->LI->Text('biz');
		$h->ID->LI->Text('baz');
	$h->eUL->NL;
Once you are done, you wrap things up.
	$h->EndHTML->NL;
Putting it all together, you get:
	use libHTML;
	#***** get new HTML object *****
	my($h) = new libHTML("out.html");
	#***** get parameters passed in from form *****
	#***** construct a cookie to save them *****
	my(%login);
	$login{'id'} = $h->Param('id');
	$login{'pwd'} = $h->Param('password');
	$h->SetCookie('LoginInfo', \%login);
	#***** start the output *****
	$h->StartCGI('LoginInfo')->StartHTML(TITLE => 'This & That');
	#***** list the parameters *****
	$h->sUL->NL;
	$h->ID->LI->STRONG('id:')->Text(" $login{'id'}")->NL;
	$h->ID->LI->STRONG('password:')->Text(" $login{'pwd'}")->NL;
	$h->eUL->NL;
	#***** we are finished now *****
	$h->EndHTML;
which (assuming id=foo and password=bar) would produce the following:
	Set-Cookie: LoginInfo=pwd&bar&id&foo
	Content-type: text/html
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
	<!-- ************************************************************** -->
	<!-- ************************************************************** -->
	<!-- ************************************************************** -->
	<HTML>
	<!-- ***** Heading ***** -->
	<HEAD>
		<!-- ***** Title ***** -->
		<TITLE>This &amp; That</TITLE>
	</HEAD>
	<!-- ************************************************************** -->
	<BODY>
	<!-- ***** Main Heading ***** -->
	<H1 ALIGN="center">This &amp; That</H1>
	<UL>
		<LI><STRONG>id:</STRONG> foo
		<LI><STRONG>password:</STRONG> bar
	</UL>
	</BODY>
	</HTML>

Object Methods


Constructors & Destructors

new libHTML
new libHTML fname
new libHTML fname, skipcmdline
Creates a new libHTML object. If successful, it returns a reference to the new object; otherwise it returns undef and stores an error message. If fname is specified, the file will be opened for output and the file handle will be stored. If fname is not specified, STDOUT is used.

If there are no CGI parameters set in the environment, or set on the command line, then the module will prompt for the parameters (useful for debugging). If skipcmdline is set to a non-zero value, then the program will not prompt for parameters.

Example:
use libHTML;
my($h) = new libHTML;
die qq(libHTML error: ), libHTML::GetInternalError, qq(\n) if !$h;
See also: GetInternalError

Close
Closes all filehandles associated with the object (except the internal debugging filehandle).
Example:
$h->Close;
See also: CloseDebug

CloseDebug
Closes the internal debugging filehandle.
Example:
$h->CloseDebug;
See also: Close


General Method Properties

Functions, Arguments & Attributes
Most of the methods listed below fall into one of two categories: those which stand alone (denoted by the tag name - DD), and those which have a start and an end (denoted by the tag name prepended by 's' or 'e' - sBODY, eBODY). Sometimes the same HTML tag can fall into both categories, and they will have 3 method calls (e.g. FONT, sFONT, eFONT).

Some of the methods will take non-optional arguments, and most will take attributes. Attributes are implemented as anonymous hashes, are not case-sensitive, and are completely optional. Each method will describe the attributes allowed (e.g. "BGCOLOR="). If the attribute name is followed by an equal sign (e.g. "COLOR="), then it takes an argument, and if it is followed by a tilde (e.g. "HREF~"), then the attribute argument retains its case (of course, you can always leave the attribute's case alone; see setATTRCASE for more info). If the attribute argument is to come from a set of values, the values will be listed (e.g. ALIGN=left|center|right). If the attribute does not take an argument, you must still give the hash key a non-zero value to turn it "on". In the following example, the OPTION tag has an argument of "Option Name" and 2 attributes (VALUE= and SELECTED):

	$h->OPTION("Option Name", VALUE => "opt_name", SELECTED => 1);
which would produce the code:
	<OPTION SELECTED VALUE="opt_name">Option Name
Unless noted otherwise, methods can be strung together:
	$h->HR->H1("Header")->HR(ALIGN => "center")->BR;
which would produce the code:
	<HR><H1>Header</H1><HR ALIGN="center"><BR>

Embedded HTML Entities
One of the features of this and many other HTML modules is that it automatically converts a string like "<foo&bar>" into "&lt;foo&amp;bar&gt;" so that it will display properly in the browser. One of the side-effects of this behaviour, though, is that it can make embedding a real HTML entity (like the ampersand) tricky, especially in string arguments to functions. Instead of being able to say:

	my($title) = "$foo&nbsp;$bar";
	$h->H1($title)->NL;
you'd have to say:
	my($title) = "$foo&nbsp;$bar";
	$h->sH1->AsIs($title)->eH1->NL;
which is kind of a drag. You really need to say something like this:
	
	$h->sH1->Text($foo)->AsIs("&nbsp;")->Text($bar)->eH1->NL;
because both $foo and $bar may have HTML entities in them that you do want converted. Start using form functions, like fListBox, which takes a list of arguments, any of which can contain embedded entities, and you start having to write way too much HTML code in AsIs blocks, which is exactly what this module is not about.

Enter: Embedded HTML Entities. All of the argument strings (i.e. non-attributes) taken in any function which would normally "cleanse" the strings of HTML entities can have special, normally non-printable characters embedded in them, which will be substituted with the appropriate HTML entities when it comes time to print. You can embed their hex or octal code, or you can use the exportable module variables:

	use libHTML qw(:EMBEDABLE_VARS);
	...
	my($title) = "$foo$NBSP$bar";
	$h->H1($title)->NL;
Current Embedded HTML Entities:

HTML EntityVariableHexOctal
&NBSP;$NBSPx1F037
<BR>$BRx1E036

If you can think of others that would be helpful, let me know.


Basic HTML Methods

TagArgument AttributesOutput Produced
A anchor HREF~
NAME~
<A ATTRIBUTES>anchor</A>
sA   HREF~
NAME~
<A ATTRIBUTES>
eA    </A>
ADDRESS string   <ADDRESS>string<ADDRESS>
sADDRESS     <ADDRESS>
eADDRESS     </ADDRESS>
sBODY   ALINK=
BACKGROUND~
BGCOLOR=
LINK=
TEXT=
VLINK=
<BODY ATTRIBUTES>
eBODY    </BODY>
BR   CLEAR=left|all|right|none <BR ATTRIBUTES>
CENTER string   <CENTER>string</CENTER>
sCENTER     <CENTER>
eCENTER     </CENTER>
DD     <DD>
sDL   COMPACT <DL ATTRIBUTES>
eDL     </DL>
DT     <DT>
EM string   <EM>string</EM>
sEM     <EM>
eEM     </EM>
FONT string COLOR~
SIZE=
<FONT ATTRIBUTES>string</FONT>
sFONT   COLOR~
SIZE=
<FONT ATTRIBUTES>
eFONT     </FONT>
sFORM   METHOD=get|post
ACTION~
ENCTYPE=
<FORM ATTRIBUTES>
eFORM     </FORM>
H1 header ALIGN=left|center|right <H1 ATTRIBUTES>header</H1>
sH1   ALIGN=left|center|right <H1 ATTRIBUTES>
eH1     </H1>
H2 header ALIGN=left|center|right <H2 ATTRIBUTES>header</H2>
sH2   ALIGN=left|center|right <H2 ATTRIBUTES>
eH2     </H2>
H3 header ALIGN=left|center|right <H3 ATTRIBUTES>header</H3>
sH3   ALIGN=left|center|right <H3 ATTRIBUTES>
eH3     </H3>
H4 header ALIGN=left|center|right <H4 ATTRIBUTES>header</H4>
H5 header ALIGN=left|center|right <H5 ATTRIBUTES>header</H5>
H6 header ALIGN=left|center|right <H6 ATTRIBUTES>header</H6>
sHEAD     <HEAD>
eHEAD     </HEAD>
HR   ALIGN=left|center|right
NOSHADE
SIZE=
WIDTH=
<HR ATTRIBUTES>
sHTML     <HTML>
eHTML     </HTML>
IMG   SRC~
BORDER=
HEIGHT=
WIDTH=
ALIGN=top|middle|bottom|left|right
ALT~
<IMG ATTRIBUTES>
INPUT string ALIGN=top|middle|bottom|left|right
CHECKED
MAXLENGTH=
NAME~
SIZE=
SRC~
TYPE=text|password|checkbox|radio|submit|reset|file|hidden|image
VALUE~
<INPUT ATTRIBUTES>string
LI string VALUE=
TYPE~disc|square|circle|1|a|A|i|I
<LI ATTRIBUTES>string
META   NAME=
CONTENT~
HTTP-EQUIV=
<META ATTRIBUTES>
sOL   START=
TYPE~1|a|A|i|I
<OL ATTRIBUTES>
eOL     </OL>
sNOSCRIPT     <NOSCRIPT>
eNOSCRIPT     </NOSCRIPT>
OPTION string SELECTED
VALUE~
<OPTION ATTRIBUTES>string
P   ALIGN=left|center|right <P ATTRIBUTES>
PRE string   <PRE>string</PRE>
sPRE     <PRE>
ePRE     </PRE>
sSCRIPT   LANGUAGE~ <SCRIPT ATTRIBUTES>
eSCRIPT     </SCRIPT>
sSELECT   MULTIPLE
NAME~
SIZE=
<SELECT ATTRIBUTES>
eSELECT     </SELECT>
STRONG string   <STRONG>string</STRONG>
sSTRONG     <STRONG>
eSTRONG     </STRONG>
sTABLE   ALIGN=left|center|right
BORDER=
WIDTH=
<TABLE ATTRIBUTES>
eTABLE     </TABLE>
TD   ALIGN=left|center|right
COLSPAN=
NOWRAP
ROWSPAN=
VALIGN=top|middle|bottom|baseline
<TD ATTRIBUTES>
TEXTAREA string COLS=
ROWS=
NAME~
<TEXTAREA ATTRIBUTES>string</TEXTAREA>
TH   ALIGN=left|center|right
COLSPAN=
NOWRAP
ROWSPAN=
VALIGN=top|middle|bottom|baseline
<TH ATTRIBUTES>
TITLE string   <TITLE>string</TITLE>
TR   ALIGN=left|center|right
VALIGN=top|middle|bottom|baseline
<TR ATTRIBUTES>
sTT     <TT>
eTT     </TT>
sUL   TYPE=disc|square|circle <UL ATTRIBUTES>
eUL     </UL>

Aggregate HTML Methods

AsIs list
Prints each element of list to the output destination without any escaping or encoding.
Example:
$h->AsIs(']&nbsp;&nbsp;')->NL;
Produces:
]&nbsp;&nbsp;
See also: Text

Comment string
Prints string inside an HTML comment.
Example:
$h->Comment("Foo Bar")->NL;
Produces:
<-- Foo Bar -->

CommentLine
Prints a line of astericks (* x 62) with a newline inside of an HTML comment.
Example:
$h->CommentLine->Comment("***** Section Header *****")->NL;
Produces:
<-- ************************************************************** -->
<-- ***** Section Header ***** -->

ContentType attributes
Prints the MIME header for the document. Attributes may include one or more of the following:

content-type~ - MIME type (default: text/html)
status~ - server status (default: 200 OK) (see also: setNPH)
location~ - redirection indicator; overrides normal MIME header (see also: Redirect)
nocache~ - sets no-cache pragma (see also: MetaNoCache)

See General Method Properties for more information on attributes.

Example:
$h->ContentType(NOCACHE => 1);
Produces:
Content-type: text/html
Pragma: no-cache

DocType
DocType doctype
Prints the DOCTYPE directive. If doctype is not specified, "-//W3C//DTD HTML 3.2//EN" is used.
Example:
$h->DocType
Produces:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">

EndHTML
Prints out a standard (for me) HTML footer. Right now, this only includes a </BODY> tag and a </HTML> tag.
Example:
$h->EndHTML
Produces:
</BODY>
</HTML>

ID
Prints the indent string to the output destination. Helpful when you need to look at the generated HTML.
Example:
$h->sOL->NL;
$h->ID->LI->Text("foo")->NL;
$h->ID->LI->Text("bar")->NL;
$h->eOL->NL;
Produces:
<OL>
	<LI>foo
	<LI>bar
</OL>
See also: setID

NL
Prints the newline string to the output destination. Helpful when you need to look at the generated HTML.
Example:
$h->sSTRONG->Text("Foo Bar")->eSTRONG->NL;
See also: setNL

Merge fn, string
Escapes and encodes string as needed, then passes it to the function fn for postprocessing. Prints the return value of fn AsIs.
Example:
$h->LI->Text("Foo & Bar")->NL;
Produces:
<LI>Foo &amp; Bar
See also: AsIs

MetaNoCache
Prints a no-cache directive inside of a META tag.
Example:
$h->MetaNoCache;
Produces:
<META HTTP-EQUIV="Pragma" CONTENT="no-cache">

StartHTML attributes
Prints a standard (for me) HTML header. See example output for what it produces. Attributes can be one or more of the following:

TITLE~ - title of the HTML document (default: "(untitled)")
BGColor~ - if present, sets the BGCOLOR attribute on the BODY tag
BGColorName~ - if present, puts the color name in a comment
Meta~ - an anonymous hash of META NAME attributes for the HEAD section
Equiv~ - an anonymous hash of META HTTP-EQUIV attributes for the HEAD section
Hook1~ - text to be printed AsIs immediately before the <HTML> tag
Hook2~ - text to be printed AsIs immediately after the <H1> tag
Hook3a~ - text to be printed AsIs immediately before the title within the <H1> tag
Hook3b~ - text to be printed AsIs immediately after the title within the <H1> tag

See General Method Properties for more information on attributes.

Example:
$name{'description'} = "This is a description";
$name{'keywords'} = "These are the keywords";
$equiv{'Refresh'} = "3; url=next.html";
$h->StartHTML(TITLE => "Sample Title",
		BGColor => "F5CCB0",
		BGColorName => "Camel",
		META => \%name,
		META => \%equiv,
		HOOK1 => "<!-- this is hook1 -->",
		Hook2 => "<!-- this is hook2 -->",
		Hook3a => "<IMG SRC="Hook3a">",
		Hook3b => "<IMG SRC="Hook3b">",);
Produces:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<!-- ************************************************************** -->
<!-- ************************************************************** -->
<!-- ************************************************************** -->
<!-- this is hook1 -->
<HTML>
<!-- ***** Heading ***** -->
<HEAD>
	<!-- ***** Title ***** -->
	<TITLE>Sample Title</TITLE>
	<META NAME="description" CONTENT="This is a description">
	<META NAME="keywords" CONTENT="These are the keywords">
	<META HTTP-EQUIV="Refresh" CONTENT="3; url=next.html">
</HEAD>
<!-- ************************************************************** -->
<BODY BGCOLOR="#F5CCB0"><!-- Camel -->
<!-- ***** Main Heading ***** -->
<H1 ALIGN="center"><IMG SRC="Hook3a">Sample Title<IMG SRC="Hook3b"></H1>
<!-- this is hook2 -->

Text list
Prints each element of list to the destination output, escaping and encoding characters as needed.
Example:
$h->LI->Text("Foo & Bar")->NL;
Produces:
<LI>Foo &amp; Bar
See also: AsIs

TAG first, last, string, expected, attr-hash
Allows you to "roll your own" tags. All libHTML tags are implemented using this function. The first argument is always expected to be something other than an empty string. Basically, the first argument is printed out, along with any attributes found by joining expected (a space delimited list of allowable attributes) with the keys from attr-hash, then the string, if present, and finally the last tag, if present. Note: as shown in the example below, by putting the new subroutine into the libHTML namespace, it can be called and strung together as if it were part of the module. Just remember to return the libHTML object....

See General Method Properties for more information on attributes.

Example:
sub libHTML::NewTag
{
	my($self, $str, %attr) = @_;
	$self->TAG("T1", "/T1", $str, "ALIGN=left|center|right FOO BAR~", %attr);
	$self;
}
$h->NewTag("Hello World", FOO => 1, BAR => "Perl Rules", ALIGN => right)->NL;
Produces:
<T1 ALIGN="right" FOO BAR="Perl Rules">Hello World</T1>


Aggregate Form Methods

fCheckBox label, name, value, checked
This function automates the production of an INPUT tag of type 'checkbox'.
Example:
$h->fCheckBox("Foo", "check_list1", "FOO", 0)->NL;
Produces:
<INPUT NAME="check_list1" TYPE="checkbox" VALUE="FOO">Foo

fHidden name, value
This function automates the production of an INPUT tag of type 'hidden'.
Example:
$h->fHidden("pass_thru1", "kittie")->NL;
Produces:
<INPUT NAME="pass_thru1" TYPE="hidden" VALUE="kittie">

fPassword name, size, maximum
This function automates the production of an INPUT tag of type 'password'.
Example:
$h->fPassword("pwd", 20, 20)->NL;
Produces:
<INPUT MAXLENGTH="20" NAME="pwd" SIZE="20" TYPE="password">

fRadioButton label, name, value, checked
This function automates the production of an INPUT tag of type 'radio'.
Example:
$h->fRadioButton("Foo", "radio1", "FOO", $radio1 == "FOO")->NL;
Produces:
<INPUT CHECKED NAME="radio1" TYPE="radio" VALUE="FOO">Foo

fReset label
This function automates the production of an INPUT tag of type 'reset'.
Example:
$h->fReset("Reset Form")->NL;
Produces:
<INPUT TYPE="reset" VALUE="Reset Form">

fSubmit name, label
This function automates the production of an INPUT tag of type 'submit'. label will be the text of the button displayed, and name will be the value of the CGI parameter passed back. Both will default to "Submit" if omitted.
Example:
$h->fSubmit("Action", "Send Mail")->NL;
Produces:
<INPUT TYPE="submit" NAME="Action" VALUE="Send Mail">

fTextBox name, size, maximum, default
This function automates the production of an INPUT tag of type 'text'.
Example:
$h->fTextBox("text1", 25, 100, $foo)->NL;
Produces:
<INPUT MAXLENGTH="100" NAME="text1" SIZE="25" TYPE="text" VALUE="Hello World">


CGI Methods

Cookie cookie-list
This function prints a series of "Set-Cookie" lines, one for each cookie in cookie-list. Usually called by the module via StartCGI or Redirect.
Example:
$h->Cookie("Foo", "Bar");
Produces:
Set-Cookie: Foo=something
Set-Cookie: Bar=something else
See also: DeleteCookie, Redirect, SetCookie, StartCGI

DeleteCookie cookie-list
Sets the cookie expiry to be "Thu, 01-Jan-1970 00:01:00 GMT" for each cookie in cookie-list. The cookie needs to have been set already, either from the environment or via SetCookie. Note: this sets it internally only; you still need to send the cookie via StartCGI or Cookie.
Example:
$h->DeleteCookie("Foo");
See also: Cookie, SetCookie

GetCookie cookie
This will return the value of the cookie. Function will return an array or hash if in the appropriate context. Because of its return value, this function cannot be strung together with other functions.
Example:
$cookie = $h->GetCookie("Foo");
See also: SetCookie

Param wanted-list
This function allows access to the CGI parameters with which the script was started. If a particular value was not set, it will return a zero or the null string. In an array context, it returns the values for each of the parameters in wanted-list. In a scalar context, it only returns the first element of the array of values. Because of its return value, this function cannot be strung together with other functions.
Example:
my($foo, $bar) = $h->Param("Foo", "Bar");
See also: Params

Params
This function returns a hash reference of all of the CGI parameters with which the script was started. It's useful if you're going to be accessing a lot of paramters, and don't want the overhead of multiple Param calls. Because of its return value, this function cannot be strung together with other functions.
Example:
my($p) = $h->Params;
if ($p->{'Foo'}) {
   ...
}
See also: Param

Redirect location
Redirect location, cookie-list
This function automates a redirection, using the "Location:" header instead of the MIME type header. Each cookie in cookie-list is set first. This function would be called instead of, not in addition to, StartCGI.
Example:
$h->Redirect("http://www.netaxs.com/~joc/perlwin32.html");
Produces:
Location: http://www.netaxs.com/~joc/perlwin32.html
See also: StartCGI

SetCookie name, value, attr-hash
Stores cookie values for future use with StartCGI, Redirect or Cookie. Each cookie must have a name and a value (even if the value is nothing, or ""). Attributes are optional and can be one of the following: DOMAIN~, PATH~, EXPIRES~, SECURE. See General Method Properties for more information on attributes.
Example:
$expires = libHTML::expdate(time + 86400);
$h->SetCookie("Foo", "Some Meaningful Value", EXPIRES => $expires);
See also: expdate, GetCookie, StartCGI, Redirect, Cookie

StartCGI cookie-list
Sets each cookie in cookie-list, and then calls ContentType with no arguments or attributes.
Example:
$h->StartCGI("Foo");
Produces:
Set-Cookie: Foo=Some%20Meaningful%20Value; EXPIRES=Fri, 11-Apr-97 17:43:26 GMT
Content-type: text/html


Error Processing Methods

ClearError
Clears the object's error. There really isn't a reason to call this....
Example:
$h->ClearError;
See also: GetError, SetError

GetError
Returns the object's error. Because of its return value, this function cannot be strung together with other functions.
Example:
print qq(There was an error - ), $h->GetError(), qq(\n);
See also: ClearError, SetError

libHTML::GetInternalError
Returns the package's internal error. Because of its return value, this function cannot be strung together with other functions.
Example:
print qq(There was an internal error - ), libHTML::GetInternalError(), qq(\n);
See also: SetInternalError

SetError function, message
Sets the object's error message. There really isn't a reason to call this....
Example:
$h->SetError("NewTag", "Error condition: Blue!");
See also: ClearError, GetError

libHTML::SetInternalError libHTML-ref
libHTML::SetInternalError function, message
Sets the packages internal error message to an object's error message or a specified message. There really isn't a reason to call this....
Example:
libHTML::SetInternalError("NewerTag", "Error condition: Red!");
See also: GetInternalError


Logging/Debugging Methods

die string-list
This function acts exactly like Perl's die(), except that output is sent to the current output destination (file or STDOUT). StartCGI is called first if neither one of ContentType or DocType has previously been called. Output can be customized using SetDieTags.

Both libHTML::die and libHTML::warn can be called automatically using signals, should any other part of the program call Perl's built-in equivalents. See example for details (the "CALL_FRAMES" bit helps unwind the call stack so that the correct filename and line number are reported -- don't change the recommendations unless you know what you're doing).

Example:
$h = new libHTML;
$SIG{'__WARN__'} = sub { $h->{'CALL_FRAMES'}++; $h->warn(@_); };
$SIG{'__DIE__'} = sub { $h->{'CALL_FRAMES'}++; $h->die(@_); };
open(FOO, "<foo.txt") || die qq([ERROR] Cannot open "foo.txt");
Produces:
Content-type: text/html
<P><FONT SIZE="+1"><STRONG>A fatal error occured:<BR>
[ERROR] Cannot open "foo.txt" at foo.pl line 9.
</STRONG></FONT><P>
See also: warn, SetDieTags

dump
This dumps the following values out to the current logging destination: the object's attributes, the parameters that the CGI script was called with, and all relevant CGI environment variables.
Example:
$h->dump;
See also: log, setLOG

log string-list
This function prints each element of string-list to the logging destination, in the current logging style. This is quite useful when debugging CGI scripts (unless you can interpret "Document contains no data").
Example:
$h->log("Before the really suspect code");
See also: dump, setLOG

warn string-list
This function acts exactly like Perl's warn(), except that output is sent to the current output destination (file or STDOUT). StartCGI is called first if neither one of ContentType or DocType has previously been called. Output can be customized using SetWarnTags.

Both libHTML::die and libHTML::warn can be called automatically using signals, should any other part of the program call Perl's built-in equivalents. See example for details (the "CALL_FRAMES" bit helps unwind the call stack so that the correct filename and line number are reported -- don't change the recommendations unless you know what you're doing).

Example:
$h = new libHTML;
$SIG{'__WARN__'} = sub { $h->{'CALL_FRAMES'}++; $h->warn(@_); };
$SIG{'__DIE__'} = sub { $h->{'CALL_FRAMES'}++; $h->die(@_); };
warn qq([ERROR] "foo.txt" not found);
Produces:
Content-type: text/html
<P><FONT SIZE="+1">A warning was issued:<BR>
[ERROR] "foo.txt" not found at foo.pl line 9.
</FONT><P>
See also: die, SetWarnTags

SetDieTags before, during, after
This function sets the values to be printed out before, during and after a program's die message is printed. before is printed out prior to the error message (useful for setting up font sizes and styles), during is printed out before each string in the string list, and after is printed out after the error message. Default values are:

before - <P><FONT SIZE="+1"><STRONG>A fatal error occured:<BR>
during -
after - </STRONG></FONT><P>
Example:
$h->SetDieTags("<STRONG><UL>", "<LI>", "</UL></STRONG>");
See also: die, SetWarnTags

SetWarnTags before, during, after
This function sets the values to be printed out before, during and after a program's warn message is printed. before is printed out prior to the error message (useful for setting up font sizes and styles), during is printed out before each string in the string list, and after is printed out after the error message. Default values are:

before - <P><FONT SIZE="+1">A warning was issued:<BR>
during -
after - </FONT><P>
Example:
$h->SetWarnTags("<STRONG><UL>", "<LI>", "</UL></STRONG>");
See also: warn, SetDieTags


Miscellaneous Methods

libHTML::expdate time
Converts and returns time from seconds into the format needed to form a cookie expiration date. Because of its return value, this function cannot be strung together with other functions.
Example:
$expires = libHTML::expdate(time + 86400);
$h->SetCookie("Foo", "Some Meaningful Value", EXPIRES => $expires);

Reopen fname
This function closes the current output file and opens a new file for output. Returns undef on error (check the Internal Error for details). Because of its return value, this function cannot be strung together with other functions.
Example:
$rc = $h->Reopen("foo");
die qq(Cannot Reopen "foo" - ), libHTML::GetInternalError, qq(\n) if ! $rc;
See also: Close, GetInternalError

setATTRCASE newcase
When printing an attribute's argument, the module can convert the case of the argument, if desired. Regardless of this setting, certain attribute arguments will always retain their case (see General Method Properties for more information on attributes). Valid values for newcase are:

$libHTML::UC - upcase's the attribute argument
$libHTML::UCFIRST - upcase's the first letter of the attribute argument
$libHTML::LC - lowcase's the attribute argument (default)
$libHTML::LCFIRST - lowcase's the first letter of the attribute argument
$libHTML::NONE - leaves the attribute argument's case alone

Returns the previous setting. Because of its return value, this function cannot be strung together with other functions.

Example:
$h->setATTRCASE($libHTML::NONE);

setFH newfilehandle
Sets the object's destination filehandle to newfilehandle. Returns the previous filehandle. Because of its return value, this function cannot be strung together with other functions.
Example:
$savefh = $h->setFH($newfh);

setID newidstr
Sets the object's indent string to newidstr. Default is a tab. Returns the previous indent string. Because of its return value, this function cannot be strung together with other functions.
Example:
$h->setID("   ");

setLOG newdest, newtype
Sets the logging destination and type. This is used for debugging. newdest can be set to one of:

$libHTML::WARN - logs to STDERR (default)
$libHTML::FH - logs to the object's destination filehandle
"" - keep the existing value

and newtype can be set to one of:

$libHTML::STD - prints the log info as is (default)
$libHTML::HTML - prints the log info as a <LI> tag
"" - keep the existing value

Returns the previous settings in an array ($olddest, $oldtype). Because of its return value, this function cannot be strung together with other functions.

Example:
$h->setLOG("", $libHTML::STD);

setNL newnewline
Sets the object's newline string to newnewline. For your convenience, newnewline can be set to one of the following (but it is not limited to this list):

$libHTML::UNIX - "\012" (default)
$libHTML::WIN - "\015\012"
$libHTML::MAC - "\015"

Returns the previous newline string. Because of its return value, this function cannot be strung together with other functions.

Example:
$h->setNL($libHTML::WIN);

setNPH newnph
Sets the object's No Parse Header flag. Returns the previous NPH setting. Because of its return value, this function cannot be strung together with other functions.
Example:
$h->setNPH(1);

setTAGCASE
When printing a tag or an attribute, the module can convert the case of the tag or attribute, if desired. Valid values for newcase are:

$libHTML::UC - upcase's the tag or attribute (default)
$libHTML::UCFIRST - upcase's the first letter of the tag or attribute
$libHTML::LC - lowcase's the tag or attribute
$libHTML::LCFIRST - lowcase's the first letter of the tag or attribute
$libHTML::NONE - leaves the tag's or attribute's case alone

Returns the previous setting. Because of its return value, this function cannot be strung together with other functions.

Example:
$h->setTAGCASE($libHTML::NONE);

Tie newobject
Ties two libhtml objects together, so that whatever is printed to the main object's output filehandle will be printed to newobject's output filehandle, too. Note: This is real low-level stuff; settings such as ATTRCASE and NL are ignored for newobject, and are taken from the main libhtml object. Returns undef on error (check main filehandle's error for message). Because of its return value, this function cannot be strung together with other functions.
Example:
$rc = $h->Tie($h2);
die qq(Tie error - ), $h->GetError, qq(\n) if ! $rc;
$h->H1("This is a title");
See also: Untie, GetError

Untie
Clears the current tie setting.
Example:
$rc = $h->Tie($h2);
$h->H1("This is a title");
...
$h->Untie;
See also: Tie

libHTML::Version
Returns the module's version and date as a string. Because of its return value, this function cannot be strung together with other functions.
Example:
print libHTML::Version;
Produces:
libHTML.PM Version 1.00 (alpha 8) (10-Apr-97)

libHTML::version
Returns the version string and date as an array (string, date). Because of its return value, this function cannot be strung together with other functions.
Example:
my($str, $date) = libHTML::version;


Index of Methods

A ADDRESS AsIs BR CENTER ClearError
Close CloseDebug Comment CommentLine ContentType Cookie
DD debug DeleteCookie DocType DT dump
eA eADDRESS eBODY eCENTER eDL eEM
eFONT eFORM eH1 eH2 eH3 eHEAD
eHTML EM EndHTML eNOSCRIPT eOL ePRE
eSCRIPT eSELECT eSTRONG eTABLE eTT eUL
expdate fCheckBox fHidden FONT fPassword fRadioButton
fReset fSubmit fTextBox GetCookie GetError GetInternalError
H1 H2 H3 H4 H5 H6
HR ID IMG INPUT LI log
Merge META MetaNoCache new NL OPTION
P Param PRE Redirect Reopen sA
sADDRESS sBODY sCENTER sDL sEM setATTRCASE
SetCookie SetError setFH setID SetInternalError setLOG
setNL setNPH setTAGCASE sFONT sFORM sH1
sH2 sH3 sHEAD sHTML sNOSCRIPT sOL
sPRE sSCRIPT sSELECT sSTRONG sTABLE StartCGI
StartHTML STRONG sTT sUL TAG TD
Text TEXTAREA TH Tie TITLE TR
Untie Version version

This page maintained by Joe Casadonte. Please let me if something is wrong or does not make sense. Send these or other documentation comments to: joc@netaxs.com (see also: Bug Reports)

This page validated to be HTML 3.2 compliant.

Copyright © Joseph L. Casadonte Jr. 1997-8. All rights reserved.
libHTML.pm / 02 January 1998 / joc@netaxs.com