Provided by: libdata-showtable-perl_4.6-4_all bug

NAME

       ShowTable - routines to display tabular data in several formats.

USAGE

       "use Data::ShowTable;"

       ShowTable { parameter => value, ... };

       ShowTable \@titles, \@types, \@widths, \&row_sub [, \&fmt_sub ];

       ShowDatabases \@dbnames;

       ShowDatabases { parameter => value, ... };

       ShowTables \@tblnames;

       ShowTables { parameter => value, ... };

       ShowColumns \@columns, \@col_types, \@col_lengths, \@col_attrs;

       ShowColumns { parameter => value, ... };

       ShowBoxTable \@titles, \@types, \@widths, \&row_sub [, \&fmt_sub ];

       ShowBoxTable { parameter => value, ... };

       ShowSimpleTable \@titles, \@types, \@widths, \&row_sub [, \&fmt_sub];

       ShowSimpleTable { parameter => value, ... };

       ShowHTMLTable \@titles, \@types, \@widths, \&row_sub [, \&fmt_sub];

       ShowHTMLTable { parameter => value, ... };

       ShowListTable \@titles, \@types, \@widths, \&row_sub [, \&fmt_sub];

       ShowListTable { parameter => value, ... };

       "package Data::ShowTable";

       $Show_Mode = 'mode';

       $Max_Table_Width = number;

       $Max_List_Width = number;

       $No_Escape = flag;

       %URL_Keys = { "$colname" => "$col_URL", ... };

       @Title_Formats = ( fmt1_html, <fmt2_html>, ... );

       @Data_Formats = ( fmt1_html, <fmt2_html>, ... );

       ShowRow $rewindflag, \$index, $col_array_1 [, $col_array_2, ...;]

       $fmt = ShowTableValue $value, $type, $max_width, $width, $precision, $showmode;

       [$plaintext = ] PlainText [$htmltext];

DESCRIPTION

       The ShowTable module provides subroutines to display tabular data, typially from a
       database, in nicely formatted columns, in several formats.  Its arguments can either be
       given in a fixed order, or, as a single, anonymous hash-array.

       The output format for any one invocation can be one of four possible styles:

       Box       A tabular format, with the column titles and the entire table surrounded by a
                 "box" of ""+"", ""-"", and ""|"" characters.  See "ShowBoxTable" for details.

       Table     A simple tabular format, with columns automatically aligned, with column titles.
                 See "ShowSimpleTable".

       List      A list style, where columns of data are listed as a name:value pair, one pair
                 per line, with rows being one or more column values, separated by an empty line.
                 See "ShowListTable".

       HTML      The data is output as an HTML TABLE, suitable for display through a Web-client.
                 See "ShowHTMLTable".  Input can either be plain ASCII text, or text with
                 embedded HTML elements, depending upon an argument or global parameter.

       The subroutines which perform these displays are listed below.

EXPORTED NAMES

       This module exports the following subroutines:

        ShowDatabases    - show list of databases
        ShowTables       - show list of tables
        ShowColumns      - show table of column info
        ShowTable        - show a table of data
        ShowRow          - show a row from one or more columns
        ShowTableValue   - show a single column's value
        ShowBoxTable     - show a table of data in a box
        ShowListTable    - show a table of data in a list
        ShowSimpleTable  - show a table of data in a simple table
        ShowHTMLTable    - show a table of data using HTML
        PlainText        - convert HTML text into plain text

       All of these subroutines, and others, are described in detail in the following sections.

MODULES

ShowTable

       Format and display the contents of one or more rows of data.

         ShowTable { parameter => value, ... };

         ShowTable \@titles, \@types, \@widths, \&row_sub [, \&fmt_sub [, $max_width ] [,
       $show_mode ] ];

       The ShowTable subroutine displays tabular data aligned in columns, with headers.
       ShowTable supports four modes of display: Box, Table, List, and HTML.  Each mode is
       described separately below.

       The arguments to ShowTable may be given in one of two ways: as a hashed-array, or by a
       combination of fixed order arguments, and some package-global variable settings.  The
       hash-array parameters correspond to the fixed arguments and the global-parameter settings.

       In the list below, both the hash-array parameter name and the fixed-order argument name is
       given as the value.  In the case where there is no fixed-order argument for a given
       parameter-value pair, then the corresponding global variable name is given.

       "titles" => \@titles
                 A reference to an array of column names, or titles.  If a particular column name
                 is null, then the string "Field_num" is used by default.  To have a column have
                 no title, use the empty string.

       "types" => \@types
                 A reference to an array of types, one for each column.  These types are passed
                 to the fmt_sub for appropriate formatting.  Also, if a column type matches the
                 regexp ""/text|char|string/i"", then the column alignment will be left-
                 justified, otherwise it will be right-justified.

       "widths" => \@widths
                 A reference to an array of column widths, which may be given as an integer, or
                 as a string of the form: "width.precision".

       "row_sub" => \&row_sub
                 A reference to a subroutine which successively returns rows of values in an
                 array.  It is called for two purposes, each described separately:

                 * To fetch successive rows of data:

                     @row = &$row_sub(0);

                 When given a null, zero, or empty argument, the next row is returned.

                 * To initialize or rewind the data traversal.

                     $rewindable = &$row_sub(1);

                 When invoked with a non-null argument, the subroutine should rewind its row
                 pointer to start at the first row of data.  If the data which row_sub is
                 traversing is not rewindable, it must return zero or null.  If the data is
                 rewindable, a non-null, non-zero value should be returned.

                 The row_sub must expect to be invoked once with a non-null argument, in order to
                 discover whether or not the data is rewindable.  If the data cannot be rewound,
                 row_sub will thereafter only be called with a zero argument.

                 Specifically, row_sub subroutine is used in this manner:

                     $rewindable = &$row_sub(1);
                     if ($rewindable) {
                         while ((@row = &$row_sub(0)), $#row >= 0) {
                             # examine lengths for optimal formatting
                         }
                         &$row_sub(1);   # rewind
                     }
                     while ((@row = &$row_sub(0)), $#row >= 0) {
                         # format the data
                     }

                 The consequence of data that is not rewindable, a reasonably nice table will
                 still be formatted, but it may contain fairly large amounts of whitespace for
                 wide columns.

       "fmtsub" => \&fmt_sub
                 A reference to a subroutine which formats a value, according to its type, width,
                 precision, and the current column width.  It is invoked either with a fixed list
                 of arguments, or with a hash-array of parameter and value pairs.

                   $string = &fmt_sub { I<parameter> => I<value>, ... };

                   $string = &fmt_sub($value, $type, $max_width, $width, $precision)

                 If \&fmt_sub is omitted, then a default subroutine, ShowTableValue, will be
                 used, which will use Perl's standard string formatting rules.

                 The arguments to \&fmt_sub, either as values passed in a fixed order, or as part
                 of the parameter value pair, are described in the section on "ShowTableValue
                 below.

       "max_width" => number,
                 The maximum table width, including the table formatting characters.  If not
                 given, defaults to the global variable $Max_Table_Width;

       "show_mode" => 'mode',
                 The display mode of the output.  One of five strings: 'Box', 'Table', 'Simple',
                 'List', and 'HTML'.

ShowDatabases

       Show a list of database names.

         ShowDatabases \@dbnames;

         ShowDatabases { 'data' => \@dbnames, parameter => value, ...};

       ShowDatabases is intended to be used to display a list of database names, under the column
       heading of "Databases".  It is a special case usage of ShowTable (and can thus be passed
       any parameter suitable for ShowTable.

       The argument, \@dbnames, is a reference to an array of strings, used as the values of the
       single column display.

ShowTables

       Show an array of table names.

         ShowTables \@tblnames;

         ShowTables { 'data' => \@tblnames, parameter => value, ...};

       ShowTables is used to display a list of table names, under the column heading of "Tables".
       It is a special case usage of ShowTable, and can be passed any "ShowTable" argument
       parameter.

ShowColumns

       Display a table of column names, types, and attributes.

         ShowColumns { parameter => values, ... };

         ShowColumns \@columns, \@col_types, \@col_lengths, \@col_attrs;

       The ShowColumns subroutine displays a table of column names, types, lengths, and other
       attributes in a nicely formatted table.  It is a special case usage of ShowTable, and can
       be passed any argument suitable for "ShowTable";

       The arguments are:

       "columns" = \@columns
                 An array of column names.  This provides the value for the first column of the
                 output.

       "col_types" = \@col_types
                 An array of column types names.  This provides the value for the second column.

       "col_lengths" = \@col_lengths
                 An array of maximum lengths for corresponding columns.  This provides the value
                 for the third column of the output.

       "col_attrs" = \@col_attrs
                 An array of column attributes array references (ie: an array of arrays).  The
                 attributes array for the first column are at "$col_attrs-\>[0]".  The first
                 attribute of the second column is "$col_attrs-\>[1][0]".

       The columns, types, lengths, and attributes are displayed in a table with the column
       headings: "Column", "Type", "Length", and "Attributes".  This is a special case usage of
       ShowTable, and can be passed additional arguments suitable for "ShowTable".

ShowBoxTable

       Show tabular data in a box.

         ShowBoxTable { parameter = value, ... };

         ShowBoxTable \@titles, \@types, \@widths, \&row_sub       [, [ \&fmt_sub ] [, $max_width
       ] ];

       The ShowBoxTable displays tabular data in titled columns using a "box" of ASCII graphics,
       looking something like this:

               +------------+----------+-----+----------+
               | Column1    | Column2  | ... | ColumnN  |
               +------------+----------+-----+----------+
               | Value11    | Value12  | ... | Value 1M |
               | Value21    | Value22  | ... | Value 2M |
               | Value31    | Value32  | ... | Value 3M |
               |  ...       |  ...     | ... |  ...     |
               | ValueN1    | ValueN2  | ... | Value NM |
               +------------+----------+-----+----------+

       The arguments are the same as with "ShowTable".  If the @titles array is empty, the header
       row is omitted.

ShowSimpleTable

       Display a table of data using a simple table format.

         ShowSimpleTable \@titles, \@types, \@widths, \&row_sub [, \&fmt_sub];

         ShowSimpleTable { parameter => values, ... };

       The ShowSimpleTable subroutine formats data into a simple table of aligned columns, in the
       following example:

          Column1  Column2  Column3
          -------  -------  -------
          Value1   Value2   Value3
          Value12  Value22  Value32

       Columns are auto-sized by the data's widths, plus two spaces between columns.  Values
       which are too long for the maximum colulmn width are wrapped within the column.

ShowHTMLTable

       Display a table of data nicely using HTML tables.

         ShowHTMLTable { parameter => value, ... };

         ShowHTMLTable \@titles, \@types, \@widths, \&row_sub [, \&fmt_sub [, $max_width [,
       \%URL_Keys [, $no_escape [, \@title_formats [, \@data_formats [, $table_attrs ] ] ] ] ] ]
       ];

       The ShowHTMLTable displays one or more rows of columns of data using the HTML "\<TABLE\">
       feature.  In addition to the usual parameter arguments of "ShowTable", the following
       parameter arguments are defined:

       "url_keys" => \%URL_Keys,
                 This is a hash array of column names (titles) and corresponding base URLs.  The
                 values of any column names or indexes occuring as keys in the hash array will be
                 generated as hypertext anchors using the associated printf-like string as the
                 base URL. Either the column name or the column index (beginning with 1) may be
                 used as the hash key.

                 In the string value, these macros can be substituted:

                 "%K" is replaced with the column name.

                 "%V" is replaced with the column value;

                 "%I" is replaced with the column index.

                 For example, if we define the array:

                     $base_url = "http://www.$domain/cgi/lookup?col=%K?val=%V";
                     %url_cols = ('Author' => $base_url,
                                  'Name'   => $base_url);

                 Then, the values in the "Author" column will be generated with the following
                 HTML text:

                     <A HREF="http://www.$domain/cgi/lookup?col=Author?val=somevalue>somevalue</A>

                 and the values in the "Name" column will be generated with the URL:

                     <A HREF="http://www.$domain/cgi/lookup?col=Name?val=othervalue>othervalue</A>

                 If this variable is not given, it will default to the global variable
                 "\%URL_Keys".

       "no_escape" => boolean,
                 Unless $no_escape is set, HTML-escaping is performed on the data values in order
                 to properly display the special HTML formatting characters : '\<', '\>', and
                 '&'.  If you wish to display data with embedded HTML text, you must set
                 $no_escape.

                 Enabling embedded HTML, turns on certain heuristics which enable the user to
                 more completely define appearance of the table.  For instance, any "\<TR\">
                 tokens found embedded *anywhere* within a row of data will be placed at the
                 front of the row, within the generated "\<TR\">.

                 Similarly, a row of data containing the "\<THEAD\"> or "\<TFOOT\"> tokens, and
                 their closing counterparts, will begin and end, respectively a table header or
                 footer data.

       "title_formats" => \@title_formats,
       "tformats" => \@title_formats,
                 An array of HTML formatting elements for the column titles, one for each column.
                 Each array element is a list of one or more HTML elements, given as
                 "\<ELEMENT\"> or plainly, "ELEMENT", and separated by a comma ',', semi-colon
                 ';', or vertical bar '|'.  Each given HTML element is prepended to the
                 corresponding column title, in the order given.  The corresponding HTML closing
                 elements are appended in the opposite order.

                 For example, if \@title_formats contains the two elements:

                     [ 'FONT SIZE=+2,BOLD', 'FONT COLOR=red,EM' ]

                 then the text output for the title of the first column would be:

                     <FONT SIZE=+2><BOLD>I<column_1_title></BOLD></FONT>

                 If "title_formats" is omitted, the global variable @Title_Formats is used by
                 default.

       "data_formats" => \@data_formats,
       "dformats" => \@data_formats,
                 Similar to "title_formats", this array provides HTML formatting for the columns
                 of each row of data.  If "data_formats" is omitted or null, then the global
                 variable \@Data_Formats is used by default.

       "table_attrs" => $table_attrs,
                 This variable defines a string of attributes to be inserted within the
                 "\<TABLE\"> token.  For example, if the user wishes to have no table border:

                     ShowHTMLTable {
                         ...
                         table_attrs => 'BORDER=0',
                         ...
                     };

ShowListTable

       Display a table of data using a list format.

         ShowListTable { parameter => value, ... };

         ShowListTable \@titles, \@types, \@widths, \&row_sub [, \&fmt_sub [, $max_width [,
       $wrap_margin ] ] ];

       The arguments for ShowListTable are the same as for "ShowTable", except for those
       described next.

       "max_width" = number,
       "wrap_margin" = number,
                 Lines are truncated, and wrapped when their length exceeds $max_width.  Wrapping
                 is done on a word-basis, unless the resulting right margin exceeds $wrap_margin,
                 in which case the line is simply truncated at the $max_width limit.

                 The $max_width variable defaults to $Max_List_Width.  The $wrap_margin defaults
                 to $List_Wrap_Margin.

       In List mode, columns (called "fields" in List mode) are displayed wth a field name and
       value pair per line, with records being one or more fields .  In other words, the output
       of a table would look something like this:

           Field1_1: Value1_1
           Field1_2: Value1_2
           Field1_3: Value1_3
           ...
           Field1-N: Value1_M
           <empty line>
           Field2_1: Value2_1
           Field2_2: Value2_2
           Field2_3: Value2_3
           ...
           Field2_N: Value2_N
           ...
           FieldM_1: ValueM_1
           FieldM_2: ValueM_2
           ...
           FieldM_N: ValueM_N
           <empty line>
           <empty line>

       Characteristics of List mode:

       •         two empty lines indicate the end of data.

       •         An empty field (column) may be omitted, or may have a label, but no data.

       •         A long line can be continue by a null field (column):

                     Field2: blah blah blah
                           : blah blah blah

       •         On a continuation, the null field is an arbitrary number of leading white space,
                 a colon ':', a single blank or tab, followed by the continued text.

       •         Embedded newlines are indicated by the escape mechanism "\n".  Similarly,
                 embedded tabs are indicated with "\t", returns with "\r".

       •         If the @titles array is empty, the field names ""Field_"NN" are used instead.

ShowRow

       Fetch rows successively from one or more columns of data.

         ShowRow $rewindflag, \$index, $col_array_1 [, $col_array_2, ...;]

       The ShowRow subroutine returns a row of data from one or more columns of data.  It is
       designed to be used as a callback routine, within the ShowTable routine.   It can be used
       to select elements from one or more array reference arguments.

       If passed two or more array references as arguments, elements of the arrays selected by
       $index are returned as the "row" of data.

       If a single array argument is passed, and each element of the array is itself an array,
       the subarray is returned as the "row" of data.

       If the $rewindflag flag is set, then the $index pointer is reset to zero, and "true" is
       returned (a scalar 1).  This indicates that the data is rewindable to the ShowTable
       routines.

       When the $rewindflag is not set, then the current row of data, as determined by $index is
       returned, and $index will have been incremented.

       An actual invocation (from ShowColumns) is:

         ShowTable \@titles, \@types, \@lengths,
             sub { &ShowRow( $_[0], \$current_row, $col_names, $col_types,
                             $col_lengths, \@col_attrs); };

       In the example above, after each invocation, the $current_row argument will have been
       incremented.

ShowTableValue

       Prepare and return a formatted representation of a value.  A value argument, using its
       corresponding type, effective width, and precision is formatted into a field of a given
       maximum width.

         $fmt = ShowTableValue $value, $type, $max_width, $width, $precision, $showmode;

       "width" => $width
       $width    The width of the current value.  If omittied, $max_width is assumed.

       "precision" => $precision
       $precision
                 The number of decimal digits; zero is assumed if omittied.

       "value" => $value
       $value    The value to be formatted.

       $type     The type name of the value; eg: "char", "varchar", "int", etc.

       "maxwidth" => $max_width
       $max_width
                 The maximum width of any value in the current value's column.  If $width is zero
                 or null, $max_width is used by default.  $max_width is also used as a minimum
                 width, in case $width is a smaller value.

       $width    The default width of the value, obtained from the width specification of the
                 column in which this value occurs.

       $precision
                 The precision specification, if any, from the column width specification.

       $showmode The mode of the output: one of "table", "list", "box", or "html".  Currently,
                 only the "html" mode is significant: it is used to avoid using HTML tokens as
                 part of the formatted text and length calculations.

PlainText

         $plaintext = &PlainText($htmltext);

         &PlainText

       This function removes any HTML formatting sequences from the input argument, or from $_ if
       no argument is given.  The resulting plain text is returned as the result.

VARIABLES

       The following variables may be set by the user to affect the display (with the defaults
       enclosed in square brackets [..]):

       $Show_Mode [Box]
                 This is the default display mode when using ShowTable.  The environment
                 variable, $ENV{'SHOW_MODE'}, is used when this variable is null or the empty
                 string.  The possible values for this variable are: "Box", "List", "Table", and
                 "HTML".  Case is insignificant.

       $List_Wrap_Margin [2]
                 This variable's value determines how large a margin to keep before wrarpping a
                 long value's display in a column.  This value is only used in "List" mode.

       $Max_List_Width [80]
                 This variable, used in "List" mode, is used to determine how long an output line
                 may be before wrapping it.  The environment variable, $ENV{'COLUMNS'}, is used
                 to define this value when it is null.

       $Max_Table_Width ['']
                 This variable, when set, causes all tables to have their columns scaled such
                 that their total combined width does not exceed this value.  When this variable
                 is not set, which is the default case, there is no maximum table width, and no
                 scaling will be done.

       $No_Escape ['']
                 If set, allows embedded HTML text to be included in the data displayed in an
                 HTML-formatted table.  By default, the HTML formatting characters ("<", ">", and
                 "&") occuring in values are escaped.

       %URL_Keys In HTML mode, this variable is used to recognize which columns are to be
                 displayed with a corresponding hypertext anchor.  See "ShowHTMLTable" for more
                 details.

       @HTML_Elements
                 An array of HTML elements (as of HTML 3.0) used to recognize and strip for width
                 calculations.

       $HTML_Elements
                 A regular expression string formed from the elements of @HTML_Elements.

INTERNAL SUBROUTINES

get_params

         my $args = &get_params \@argv, \%params, \@arglist;

       Given the @argv originally passed to the calling sub, and the hash of named parameters as
       %params, and the array of parameter names in the order expected for a pass-by-value
       invocation, set the values of each of the variables named in @vars.

       If the only element of the @argv is a hash array, then set the variables to the values of
       their corresponding parameters used as keys to the hash array.  If the parameter is not a
       key of the %params hash, and is not a key in the global hash %ShowTableParams, then an
       error is noted.

       When @argv has multiple elements, or is not a hash array, set each variable, in the order
       given within @arglist, to the values from the @argv, setting the variables named by each
       value in %params.

       Variables may given either by name or by reference.

       The result is a HASH array reference, either corresponding directly to the HASH array
       passed as the single argument, or one created by associating the resulting variable values
       to the parameter names associated with the variable names.

html_formats

         ($prefixes,$suffixes) = html_formats \@html_formats;

       The html_format function takes an array reference of HTML formatting elements
       \@html_formats, and builds two arrays of strings: the first: $prefixes, is an array of
       prefixes containing the corresponding HTML formatting elements from \@html_formats, and
       the second, $suffixes, containing the appropriate HTML closing elements, in the opposite
       order.

       The result is designed to be used as prefixes and suffixes for the corresponding titles
       and column values.

       The array \@html_formats contains lists of HTML formatting elements, one for each column
       (either title or data).  Each array element is a list of one or more HTML elements, either
       given in HTML syntax, or as a "plain" name (ie: given as "\<ELEMENT\"> or plainly,
       "ELEMENT").  Multiple elements are separated by a comma ','.

       The resulting array of $prefixes contains the corresponding opening elements, in the order
       given, with the proper HTML element syntax.  The resulting array of $suffixes contains the
       closing elements, in the opposite order given, with the proper HTML element syntax.

       For example, if \@html_formats contains the two elements:

           [ 'FONT SIZE=+2,BOLD', 'FONT COLOR=red,EM' ]

       then the resulting two arrays will be returned as:

           [ [ '<FONT SIZE=+2><BOLD>', '<FONT COLOR=red><EM>' ],
             [ '</FONT></BOLD>',       '</FONT></EM>' ] ]

calc_widths

         ($num_cols, $widths, $precision, $max_widths) =   &calc_widths( $widthspec, $titles,
       $rewindable,       $row_sub, $fmt_sub, $types, $showmode,       $max_width);

   DESCRIPTION
       calc_widths is a generalized subroutine used by all the ShowTable variant subroutines to
       setup internal variables prior to formatting for display.  Calc_widths handles the column
       width and precision analysis, including scanning the data (if rewindable) for appropriate
       default values.

       The number of columns in the data is returned, as well as three arrays: the declared
       column widths, the column precision values, and the maximum column widths.

   RETURN VALUES
       $num_cols is the number of columns in the data.  If the data is not rewindable, this is
                 computed as the maximum of the number of elements in the $widthspec array and
                 the number of elements in the $titles array.  When the data is rewindable, this
                 is the maximum of the number of columns of each row of data.

       $widths   is the column widths array ref, without the precision specs (if any).  Each
                 column's width value is determined by the original $widthspec value and/or the
                 maximum length of the formatted data for the column.

       $precision
                 is the precision component (if any) of the original $widthspec array ref.  If
                 there was no original precision component from the $widthspec, and the data is
                 rewindable, then the data is examined to determine the maximum default
                 precision.

       $max_widths
                 is the ref to the array of maximum widths for the given columns.

   ARGUMENTS
       $widthspec
                 A reference to an array of column width (or length) values, each given as an
                 integer, real number, or a string value of "width.precision".  If a value is
                 zero or null, the length of the corresponding formatted data (if rewindable) and
                 column title length are used to determine a reasonable default.

                 If a column's width portion is a positive, non-zero number, then the column will
                 be this wide, regardless of the values lengths of the data in the column.

                 If the column's width portion is given as a negative number, then the positive
                 value is used as a minimum column width, with no limit on the maximum column
                 width.  In other words, the column will be at least width characters wide.

                 If the data is not rewindable, and a column's width value is null or zero, then
                 the length of the column title is used.  This may cause severe wrapping of data
                 in the column, if the column data lengths are much greater than the column title
                 widths.

       $titles   The array ref to the column titles; used to determine the minimum acceptable
                 width, as well as the default number of columns.  If the $titles array is empty,
                 then the $widthspec array is used to determine the default number of columns.

       $rewindable
                 A flag indicating whether or not the data being formatted is rewindable.  If
                 this is true, a pass over the data will be done in order to calculate the
                 maximum lengths of the actual formatted data, using $fmt_sub (below), rather
                 than just rely on the declared column lengths.  This allows for optimal column
                 width adjustments (ie: the actual column widths may be less than the declared
                 column widths).

                 If it is not desired to have the column widths dynamically adjusted, then set
                 the $rewindable argument to 0, even if the data is rewindable.

       $row_sub  The code reference to the subroutine which returns the data; invoked only if
                 $rewindable is non-null.

       $fmt_sub  The subroutine used to determine the length of the data when formatted; if this
                 is omitted or null, the length of the data is used by default.  The $fmt_sub is
                 used only when the data is rewindable.

       $types    An array reference to the types of each of the value columns; used only when
                 $fmt_sub is invoked.

       $showmode A string indicating the mode of the eventual display; one of four strings:
                 ""box"", ""table"", ""list"", and ""html"".  Used to adjust widths for
                 formatting requirements.

       $max_width
                 The maximum width of the table being formatted.  If set, and the total sum of
                 the individual columns exceeds this value, the column widths are scaled down
                 uniformly.  If not set (null), no column width scaling is done.

putcell

         $wrapped = &putcell( \@cells, $c, $cell_width, \@prefix, \@suffix, $wrap_flag );

       Output the contents of an array cell at $cell[$c], causing text longer than $cell_width to
       be saved for output on subsequent calls.  Prefixing the output of each cell's value is a
       string from the two-element array @prefix.  Suffixing each cell's value is a string from
       the two-element array @suffix.  The first element of either array is selected when
       $wrap_flag is zero or null, or when there is no more text in the current to be output.
       The second element is selected when $wrap_flag is non-zero, and when there is more text in
       the current cell to be output.

       In the case of text longer than $cell_width, a non-zero value is returned.

       Cells with undefined data are not output, nor are the prefix or suffix strings.

center

       Center a string within a given width.

         $field = center $string, $width;

max

       Compute the maximum value from a list of values.

         $max = &max( @values );

min

       Compute the minum value from a list of values.

         $min = &min( @values );

max_length

       Compute the maximum length of a set of strings in an array reference.

         $maxlength = &max_length( \@array_ref );

htmltext

       Translate regular text for output into an HTML document.  This means certain characters,
       such as "&", ">", and "<" must be escaped.

         $output = &htmltext( $input [, $allflag ] );

       If $allflag is non-zero, then all characters are escaped.  Normally, only the four HTML
       syntactic break characters are escaped.

out

       Print text followed by a newline.

         out $fmt [, @text ];

put

       Print text (without a trailing newline).

         out $fmt [, @text ];

AUTHOR

       Alan K. Stebbens <aks@stebbens.org>

BUGS

       •         Embedded HTML is how the user can insert formatting overrides.  However, the
                 HTML formatting techniques have not been given much consideration -- feel free
                 to provide constructive feedback.