# Data::ShowTable Man Page

           ShowTable - routines to display tabular data in several
           formats.

## USAGE

           use Data::ShowTable;

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

           $Data::ShowTable::Show_Mode = 'mode';

           $Data::ShowTable::Term_Columns = NNN;

           $Data::ShowTable::Max_Table_Width = NNN;

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

           ShowDatabases \@dbnames;

           ShowTables \@tblnames;

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

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

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

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

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

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

## DESCRIPTION

           The ShowTable module provides subroutines to display
           tabular data, typially from a database, in nicely
           formatted columns, in several formats.  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 the section on
                     ShowBoxTable for details.

           Table     A simple tabular format, with columns

           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 the section on
                     ShowListTable.

           HTML      The data is output as an HTML TABLE, suitable
                     for display through a Web-client.  See the
                     section on ShowHTMLTable.

           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

           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 \@titles, \@types, \@widths, \&row_sub [,
           \&fmt_sub ];

             $Data::ShowTable::Show_Mode = 'mode';

             $Data::ShowTable::Term_Columns = NNN;

             $Data::ShowTable::Max_Table_Width = NNN;

           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 are:

                     titles.  If a particular column name is null,
                     then the string Column num is used by default.
                     To have a column have no title, use the empty
                     string.

           \@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  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 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:

                         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.

           \&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
                     this way:

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

                     The $max_width is the maximum width for the
                     column currently being formatted.

                     If $width is omitted, $max_width is assumed.

                     If $precision is omitted, zero is assumed.

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

## 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
           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.

## ShowDatabases

           Show a list of database names.

             ShowDatabases \@dbnames;

           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.

           The argument, \@dbnames, is a reference to an array of
           strings.

## ShowTables

           Show an array of table names.

             ShowTables \@tblnames;

           ShowTables is used to display a list of table names, under
           the column heading of "Tables".  It is a special case
           usage of ShowTable.

## ShowColumns

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

             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.

           The arguments are:

           \@columns An array of column names.

                     An array of column types names.

           \@col_lengths
                     An array of maximum lengths for corresponding
                     columns.

           \@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.

## ShowBoxTable

           Show tabular data in a box.

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

           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];

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

              -------  -------  -------
              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 \@titles, \@types, \@widths, \&row_sub [,
           \&fmt_sub];

           The ShowHTMLTable displays one or more rows of columns of
           data using the HTML C<\ShowTable.

           If the @titles array is empty, no header row is generated.

           There is a variable which controls if and how hypertext
           links are generated within the table:

           %URL_Keys This is a hash array of column names (titles)
                     and corresponding base URLs.  The values of any
                     columns occuring as keys in the hash array will
                     be generated as hypertext anchors using the
                     associated base URL and the column value as a
                     querystring for the "val" parameter.

           For example, if we define the array:

               $base_url = "http://www.$domain/cgi/lookup";
               %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>

## ShowListTable

           Display a table of data using a list format.

             ShowListTable \@titles, \@types, \@widths, \&row_sub [,
           \&fmt_sub];
           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:

           o         two empty lines indicate the end of data.

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

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

                         Field2: blah blah blah
                               : blah blah blah

           o         On a continuation, the null field is an
                     arbitrary number of leading white space, a colon
                     ':', and exactly one blank, followed by the
                     continued text.

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

           o         If the @Titles array is empty, the field names
                     "Field NN" are used instead.

## ShowTableValue

           Prepare and return a formatted representation of a value.
           A value argument, using its corresponding type, effective

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

           $value    The value to be formatted.

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

           $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.

## 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{'SHOWMODE'}, 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.

           $Term_Columns [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
                     this variable is not set, which is the default
                     case, there is no maximum table width, and no
                     scaling will be done.

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

## INTERNAL SUBROUTINES

## calc_widths

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

           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.

                     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

           $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.

## 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

## 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 );

## AUTHOR

           Alan K. Stebbens <aks@sgi.com>