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 ;
[$plaintext = ] PlainText [$htmltext];
The output format for any one invocation can be one of four possible styles:
+'', ``-'', and ``|'' characters. See ``ShowBoxTable'' for details.
All of these subroutines, and others, are described in detail in the following sections.
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.
Field_I
-
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 \@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 \@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 { 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:
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:
The arguments are the same as with ``ShowTable''. If the @titles array is empty, the header row is omitted.
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:
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 { parameter => value , ... };
ShowHTMLTable \@titles, \@types, \@widths, \&row_sub [, \&fmt_sub [, $max_width [, \ %URL_Keys [, $no_escape [, I<\@title_formats [, I<\@data_formats ] ] ] ] ] ];
The ShowHTMLTable displays one or more rows of columns of data using
the HTML
If this variable is not given, it will default to the global variable
If the @titles array is empty, no header row is generated.
For example, if \@title_formats contains the two elements:
then the text output for the title of the first column would be:
If
title_formats
is omitted, the global variable @Title_Formats
is used by default.
Then, the values in the
and the values in the
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.
The
$max_width
variable defaults to
$Max_List_Width
. The
$wrap_margin defaults to
$List_Wrap_Margin
.
Characteristics of
List
mode:
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:
In the example above, after each invocation, the $current_row argument
will have been incremented.
$fmt =
ShowTableValue
$value
,
$type
,
$max_width
,
$width
,
$precision
;
&PlainText
This function removes any HTML formatting sequences from the input argument,
or from
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.
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 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:
then the resulting two arrays will be returned as:
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.
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.
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.
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.
$field = center $string,
$width
;
$max = &max( @values );
$min = &min( @values );
$maxlength = &max_length( \@array_ref );
$output = &htmltext( $input );
\<TABLE\``ShowTable'', the following parameter arguments are allowed:
For example, if we define the array:.
$base_url = ``http://www.$domain/cgi/lookup'';
%url_cols = ('Author' => $base_url,
'Name' => $base_url);
\
%URL_Keys
.
\<ELEMENT\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.
Author column will be generated with the following
HTML text:
Name column will be generated with the URL:
ShowListTable
Display a table of data using a list format.
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:
.
Field_NN'' are used
instead.
ShowRow
Fetch rows successively from one or more columns of data.
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.
.
char, varchar, int, etc.
PlainText
$plaintext = &PlainText($htmltext);
$_ 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 [..]):
.
$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.
$ENV{'COLUMNS'}, is
used to define this value when it is null.
INTERNAL SUBROUTINES
get_params
my $args = &get_params \@argv, \%params, \@arglist;
html_formats
($prefixes,$suffixes) =
html_formats
\@html_formats;
\<ELEMENT\ELEMENT).
Multiple elements are separated by a comma ','.
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.
RETURN VALUES
.
ARGUMENTS
box'', ``table'', ``list'', and ``html''. Used to adjust widths
for formatting requirements.
putcell
$wrapped = &putcell( \@cells, $c, $cell_width, \@prefix, \@suffix, $wrap_flag );
center
Center a string within a given width.
max
Compute the maximum value from a list of values.
min
Compute the minum value from a list of values.
max_length
Compute the maximum length of a set of strings in an array reference.
htmltext
Translate regular text for output into an HTML document. This means
certain characters, such as ``&'', ``>'', and ``<'' must be escaped.
AUTHOR
Alan K. Stebbens <aks@sgi.com>
BUGS