man > Data::ShowTable

ShowTable(3pm) User Contributed Perl Documentation ShowTable(3pm)

📛 NAME

ShowTable – routines to display tabular data in several formats.

🚀 Quick Reference

Use Case	Command	Description
📊 Display a table of data (auto‑mode)	ShowTable	Formats data in Box, Table, List, or HTML mode
🗄️ Show database list	ShowDatabases	Displays a single‑column list under “Databases”
📋 Show table list	ShowTables	Displays a single‑column list under “Tables”
🏛️ Show column info	ShowColumns	Displays column names, types, lengths, attributes
📦 Box‑style table	ShowBoxTable	ASCII box with +‑‑‑+ borders
📄 Simple table	ShowSimpleTable	Aligned columns with dashes under headers
🌐 HTML table	ShowHTMLTable	Generates <TABLE> with optional hyperlinks
📑 List format	ShowListTable	Field:value pairs per row, wrapped
🔁 Row callback	ShowRow	Fetches rows from arrays for use with ShowTable
🔢 Format a single value	ShowTableValue	Returns formatted string given value, type, width
🧹 Strip HTML	PlainText	Removes HTML tags from a string

📖 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, typically 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.
• 📄 Table – A simple tabular format, with columns automatically aligned and column titles. See ShowSimpleTable.
• 📑 List – A list style where columns are shown as name:value pairs, one per line, rows separated by an empty line. See ShowListTable.
• 🌐 HTML – The data is output as an HTML TABLE, suitable for a Web client. See ShowHTMLTable. Input can be plain ASCII or text with embedded HTML elements.

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 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. It supports four modes: Box, Table, List, and HTML. Arguments may be given as a hashed‑array or fixed‑order arguments plus package‑global variable settings.

Parameter list (hash‑array name / fixed‑order argument / global variable):

• 📌 "titles" => \@titles – A reference to an array of column names. If a name is null, "Field_num" is used by default.
• 🏷️ "types" => \@types – A reference to an array of types, one per column. Used for formatting and alignment (left‑justified if matching /text|char|string/i, else right‑justified).
• 📏 "widths" => \@widths – A reference to an array of column widths, given as integer or "width.precision".
• 🔄 "row_sub" => \&row_sub – A reference to a subroutine that successively returns rows of values. It is called with 0 to fetch the next row, and with 1 to rewind (if rewindable).
• 🔧 "fmtsub" => \&fmt_sub – A reference to a subroutine that formats a value. If omitted, ShowTableValue is used.
• 📐 "max_width" => number – Maximum table width; defaults to $Max_Table_Width.
• 🖥️ "show_mode" => 'mode' – Display mode: 'Box', 'Table', 'Simple', 'List', or 'HTML'.

🗄️ ShowDatabases

Show a list of database names.

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

Displays a single column under the heading "Databases". A special case of ShowTable.

📋 ShowTables

Show an array of table names.

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

Displays a single column under the heading "Tables". A special case of ShowTable.

🏛️ ShowColumns

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

ShowColumns { parameter => values, ... };
ShowColumns \@columns, \@col_types, \@col_lengths, \@col_attrs;

Displays columns, types, lengths, and attributes with headings "Column", "Type", "Length", "Attributes". A special case of ShowTable.

• "columns" = \@columns – Array of column names (first output column).
• "col_types" = \@col_types – Array of type names (second output column).
• "col_lengths" = \@col_lengths – Array of maximum lengths (third output column).
• "col_attrs" = \@col_attrs – Array of array references for attributes (fourth output column).

📦 ShowBoxTable

Show tabular data in a box.

ShowBoxTable { parameter = value, ... };
ShowBoxTable \@titles, \@types, \@widths, \&row_sub [, [ \&fmt_sub ] [, $max_width ] ];

Displays data in a box of ASCII graphics, e.g.:

+------------+----------+-----+----------+
| Column1    | Column2  | ... | ColumnN  |
+------------+----------+-----+----------+
| Value11    | Value12  | ... | Value 1M |
| Value21    | Value22  | ... | Value 2M |
+------------+----------+-----+----------+

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, ... };

Formats data into a simple table of aligned columns:

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

Columns are auto‑sized by data widths, plus two spaces between columns. Values too long are wrapped.

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

Additional parameters:

• 🔗 "url_keys" => \%URL_Keys – Hash of column names to base URLs. Macros: %K (column name), %V (value), %I (index).
• 🚫 "no_escape" => boolean – If set, HTML escaping is disabled; embedded HTML elements are allowed.
• 🎨 "title_formats" / "tformats" => \@title_formats – Array of HTML formatting elements for column titles.
• 🎨 "data_formats" / "dformats" => \@data_formats – Similar for data rows.
• 📐 "table_attrs" => $table_attrs – String of attributes inserted into the <TABLE> tag (e.g., '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 ] ] ];

Output example:

Field1_1: Value1_1
Field1_2: Value1_2
<empty line>
Field2_1: Value2_1
Field2_2: Value2_2

• 📐 "max_width" – Maximum line width; defaults to $Max_List_Width.
• 📐 "wrap_margin" – Margin for wrapping; defaults to $List_Wrap_Margin.
• Two empty lines indicate end of data.
• Long lines can be continued with a null field (colon alone).
• Embedded newlines are shown as "\n", tabs as "\t", returns as "\r".
• If @titles is empty, fields are named "Field_NN".

🔁 ShowRow

Fetch rows successively from one or more columns of data.

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

Designed as a callback for ShowTable. If two or more array references are given, elements selected by $index are returned as the row. If a single array reference is given and each element is an array, the subarray is returned. When $rewindflag is set, the index resets to zero and returns true.

🔢 ShowTableValue

Prepare and return a formatted representation of a value.

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

• "value" – The value to format.
• "type" – Type name (e.g., "char", "int").
• "maxwidth" – Maximum width of any value in the column.
• "width" – Default width of the value.
• "precision" – Number of decimal digits.
• "showmode" – One of "table","list","box","html".

🧹 PlainText

$plaintext = &PlainText($htmltext);
&PlainText   # operates on $_

Removes any HTML formatting sequences from the input and returns the plain text.

⚙️ VARIABLES

Default values in square brackets:

• $Show_Mode [Box] – Default display mode. Environment variable $ENV{'SHOW_MODE'} used if null.
• $List_Wrap_Margin [2] – Margin before wrapping long values in List mode.
• $Max_List_Width [80] – Maximum line length in List mode. Environment $ENV{'COLUMNS'} used if null.
• $Max_Table_Width [undef] – When set, scales column widths to fit within this value.
• $No_Escape [undef] – If set, allows embedded HTML in HTML‑formatted tables.
• %URL_Keys – Columns to display as hyperlinks (see ShowHTMLTable).
• @HTML_Elements – Array of HTML 3.0 elements used for width calculations.
• $HTML_Elements – Regex formed from @HTML_Elements.

🔧 INTERNAL SUBROUTINES

🔍 get_params

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

Given the original @argv, named parameters %params, and an ordered list of parameter names @arglist, sets the values of each variable. If the only element of @argv is a hash, uses its keys; otherwise uses positional arguments. Returns a HASH reference.

🏷️ html_formats

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

Takes an array reference of HTML formatting elements and builds two arrays: prefixes (opening elements) and suffixes (closing elements in reverse order). Each element is a list of HTML elements separated by comma, semicolon, or vertical bar.

📐 calc_widths

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

Generalized subroutine used by all ShowTable variants to set up column widths, precisions, and maximum widths. Handles scanning of rewindable data for optimal defaults.

Returns: number of columns, array ref of widths, array ref of precisions, array ref of maximum widths.

📤 putcell

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

Outputs the contents of an array cell, wrapping text longer than $cell_width for subsequent calls. Returns non‑zero if wrapping occurred.

🎯 center

$field = center $string, $width;

Center a string within a given width.

📈 max

$max = &max( @values );

Compute the maximum value from a list.

📉 min

$min = &min( @values );

Compute the minimum value from a list.

📏 max_length

$maxlength = &max_length( \@array_ref );

Compute the maximum length of strings in an array reference.

🔤 htmltext

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

Translate regular text for HTML output, escaping "&", ">", "<". If $allflag is non‑zero, all characters are escaped.

📝 out

out $fmt [, @text ];

Print text followed by a newline.

📝 put

put $fmt [, @text ];

Print text without a trailing newline.

👤 AUTHOR

Alan K. Stebbens <aks@stebbens.org>

🐛 BUGS

• Embedded HTML allows formatting overrides, but the HTML formatting techniques have not been given much consideration – feel free to provide constructive feedback.

perl v5.32.0 2021‑01‑06 ShowTable(3pm)