Libraries available for www.washington.edu Developers

The following Perl5 libraries are available in the www/lib directory:

browser-features.pl

This library exports the features available from the current browser.

Usage:

require "/www/lib/browser-features.pl";

$feature = $browser_features{"feature"};
The features currently available for testing are:
"Netscape"
Client is Netscape, and thus has Netscape's HTML extensions.
"Scale GIFs"
Client can scale at least a couple GIFs.
"Multiple Scaled GIFs"
Client can scale any number of GIFs on the same page. Be careful to use this instead of "Scale GIFs" if your page has more than a couple GIFs which need to be scaled. If you fail to test for this in particular, the browser may crash!
"Tables"
Clent supports tables, as described in HTML3.
"Backgrounds"
Client can use Texture backgrounds, as well as redefine the color for hotlinks.
"Dynamic Documents"
Clent supports both server push and client pull dynamic documents. Note that server push documents are discouraged on the www.washington.edu servers if they hold the connection open for any significant amount of time.

hist.pl

This module plots a colorful bar histogram. It allows multiple items to be plotted for each key, and will use a different color for each. Currently allows up to six different items, but does not check for more than six items, so be warned!

You may also specify whether the histogram to be plotted takes advantage of browsers which can scale multiple GIFs. See "Multiple Scaled GIFs" in the browser-features.pl library. Output will also be compatible (of a fashion) with Lynx.

Usage:

require "/www/lib/hist.pl";

sub lookup {    # optional
    my ($tag, $key, @order) = @_;
    do lookup functions here;
    ($total, $val1, $val2 etc.);
}

sub rewrite {   # optional
    my ($tag, $key) = @_;
    do rewriting here;
    ($string, $printable_length);
}

$histogram = &hist ($tag, \&lookup, \&rewrite, \@order, $canscale, @keys);
&hist will return a string containing the histogram. The actual format of this string is described below.

Arguments to &hist

$tag
Constant passed to all calls of \&lookup and \&rewrite. Never evaluated, so can be used to pass flags and/or state to those callbacks.
\&lookup
Callback subroutine to look up actual values to plot. Called with:
&lookup ($tag, $key, @orders);
The arguments are:
$tag
Constant originally passed to &hist.
$key
Key to look up.
@orders
Order which returned values are expected to represent. Same as \@orders passed to &hist.

Returned values should be:

($total, $val1, $val2 etc.);
Where:
$total
Total of all values.
$val1 etc.
Individual values, each with a one-to-one correspondence to values passed into @orders.

If \&lookup is undef, then the value which would have been passed into $key is assumed to be a plottable value and will be used.

\&rewrite
Callback to change the way a key is written as a label. Called with:
&rewrite ($tag, $key);
Arguments are:
$tag
Constant originally passed to &hist.
$key
Key to rewrite.

Returned values should be:

($string, $printable_length);
Where:
$string
String to use as the label.
$printable_length
Length of this string when printed.

Note that length $string is not necessarily the same as $printable_length, since $string could have an HTML reference associated with it.

If \&lookup is undef then the value which would have been passed in as $key will be used as the label, and length $key as the length.

\@order
A reference to an array consisting of the different values to be printed. These values are ones which will have stacked bars on the histogram. The top of the histogram will contain a legend with these values as labels. Elements of this array which are undef are ignored, both in the legend and the histogram plot.

If @order is undef then only one value per bucket to be plotted is assumed, and no legend will be printed.

$canscale
Whether the color bars generated should be whole bars or bars of width 1 but scaled to the full width.
@keys
Elements to plot. These become $key in calling both &lookup and &rewrite.

Format of &hist Output

&hist returns a string divided into a legend and a histogram. The legend consists of an unordered list of color bars, one for each key in @keys which is not the undef value.

The histogram is formatted so that the label for each line is right-justified, followed by the total count for this item, followed by a series of stacked color bars representing the value of each item passed in through \@orders. The label section has a maximum width of $hist::namewid characters (default 20, but can be changed before calling &hist). If the label is too wide to fit within $hist::namewid characters but can fit if squeezed into the extra spaces before the number representing the total for that item, then those spaces are utilized. Otherwise, the label is printed on a line of its own and all other information on the following line.

The width of the histogram field itself is limited to $hist::barmax pixels (default 400), or $hist::prewid ascii characters (default 50).

The order of the colors used is defined in @hist::color_order, and the colors themselves are defined in %hist::colors, with each color's value being a reference to an associative array containing "dir" (the directory within /www/world/cbars containing .gif files for that color in addition to a dir.gif file containing a one-pixel-wide gif) and "char", which is the character used to plot an ASCII histogram. Each set of stacked color bars is followed by a one-pixel-width black bar. This is to both give a better visual indication of the end of the bar and to have an indication that there are no missing parts of the bar for plotted items wich have a value of 0 (or close enough to 0 to be unplottable).

Immediately after the number representing the total value for the given item is an HTML comment consisting of numbers separated by / characters. These are the values (in order)for the different bars which are plotted, including values of 0. For example, if an entry has a total of 10, with individual item values of 5, 2, 0, and 3, the value and comment would be:

10<!--5/2/0/3-->

Color Bars Directory

The directory www/world/cbars contains a set of directories which themselves contain GIF files of color bars with a height of 10 pixels. Given:

then the path to that image is

www/world/cbars/color/d/n.gif
In addition, a one-pixel-width GIF image exists for each color as: 
www/world/cbars/color.gif

Images exist up to 500 pixels wide for each color. The defined colors and directories are:

Dir
Color
r
red
g
green
b
blue
c
cyan
m
magenta
y
yellow
k
black

date.pl

This library allows you to convert from internal Unix date format to a string. It is used by chtml.

Usage:

require "/www/lib/date.pl";

$datestr = &date::eval (format, time);
$gmtdatestr = &date::gmteval (format, time);
The format string can be any string with date fields represented by escape sequences beginning with %. The defined sequences are shown below, with example fields for Sunday, January 1, 1995 at 1:45:00pm.
Option Description Example
%a Short weekday name Sun
%A Full weekday name Sunday
%b Short month name Jan
%B Full month name January
%d Day of month between 1 and 31 1
%D Day of month between 01 and 31 01
%H Hour as decimal between 00 and 23 13
%I Hour as decimal between 1 and 12 1
%m Number of month between 1 and 12 1
%M Minute between 00 and 59 45
%n Number of month between 01 and 12 01
%S Second between 00 and 59 00
%p Lowercase am or pm pm
%P Uppercase AM or PM PM
%y Year without century 95
%Y Year with century 1995
%% Literal % %

geturl.pl

This library allows you to get a file via HTTP.

Usage:

require "/www/lib/date.pl";

$retval = &geturl::http (url, localfile);
$retval is positive if the contents of url have been successfully received and written into localfile, negative if the file in localfile has not changed, and zero if there was an error (the remote system was unreachable, the file isn't there or requires authentication, or there was an error in writing localfile).

lockfile.pl

This library provides a mechanism with which you can lock a file to ensure no other process is also using the file.

Usage:

require "/www/lib/lockfile.pl";

unless (lockfile (filename)) {
    unable to lock file
}

process the file

unlockfile (filename);