ShowTable(3pm)

📦
version 4.6 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

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

okay bestie, sit down, hydrate, because this is the manual page for ShowTable — you know, the module from the User Contributed Perl Documentation section of 3pm. We're doing this in four parts and this is part 1, so don't get up to leave yet. 🫶

✨ NAME ✨

ShowTable — a whole lil family of routines whose entire job is displaying tabular data in several formats. iconic behavior honestly. 👑

🌸 USAGE 🌸

here's the vibe, verbatim, no cap:

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

look at all those ways in. it's giving choose your own adventure. ✨

🦋 DESCRIPTION 🦋

So the ShowTable module hands you a bunch of subroutines that display tabular data — typially from a database — in nicely formatted columns, across several formats. and the way it takes its arguments? either in a fixed order, or as a single anonymous hash-array. pick your fighter. 💅

Every single invocation can come out in one of four possible output styles:

  • Box — a tabular format where the column titles and the entire table are wrapped in a "box" made of "+", "-", and "|" characters. so aesthetic. see ShowBoxTable for the details.
  • Table — a simple tabular format with columns aligned automatically and column titles up top. see ShowSimpleTable.
  • List — a list style, where columns of data are written as a name:value pair, one pair per line, with each row being one or more column values separated by an empty line. see ShowListTable.
  • HTML — the data gets output as an HTML TABLE, perfect for displaying through a Web-client. see ShowHTMLTable. your input can be plain ASCII text, or text with embedded HTML elements — depends on an argument or a global parameter. 💖

and the subroutines that actually do all this displaying? they're listed right below. ⬇️

👑 EXPORTED NAMES 👑

This module exports the following subroutines, so like, they're yours now:

  • 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

and all of these subroutines, plus others, get described in detail in the following sections. yes, plus others. stay tuned. 🎀

🧚 MODULES 🧚

💜 ShowTable 💜

Format and display the contents of one or more rows of data. that's the whole job description. 💅

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. and it supports four modes of display: Box, Table, List, and HTML. each one gets its own little section below, don't worry.

Now — the arguments to ShowTable can arrive in one of two ways: as a hashed-array, or as a combination of fixed-order arguments plus some package-global variable settings. the hash-array parameters correspond exactly to the fixed arguments and the global-parameter settings. lowkey elegant. ✨

In the list below, both the hash-array parameter name and the fixed-order argument name are given as the value. and if there's no fixed-order argument for a given parameter-value pair? then the corresponding global variable name is what you get instead.

  • "titles" => \@titles — a reference to an array of column names, aka titles. if a particular column name is null, then the string Field_num gets used by default. and if you want a column to have no title at all, pass the empty string. silence is an option. 🤫
  • "types" => \@types — a reference to an array of types, one for each column. these types get passed to the fmt_sub for appropriate formatting. also, if a column type matches the regexp "/text|char|string/i", then that column's alignment goes left-justified — otherwise it goes right-justified. text girlies lean left, numbers lean right. 🫶
  • "widths" => \@widths — a reference to an array of column widths, which you can give either as an integer, or as a string of the form: width.precision.
  • "row_sub" => \&row_sub — a reference to a subroutine that successively returns rows of values in an array. it gets called for two purposes, and each one deserves its own moment:
    • To fetch successive rows of data:
@row = &$row_sub(0);

when given a null, zero, or empty argument, the next row comes back. simple as that.

  • 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 that 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, so it can discover whether or not the data is rewindable. and here's the rule, bestie: if the data cannot be rewound, row_sub will only be called with a zero argument from then on. ⚠️

Specifically, the 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
}

and the consequence of having 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. not a crime, just a lil stretched. 💀

  • "fmtsub" => \&fmt_sub — a reference to a subroutine that formats a value according to its type, width, precision, and the current column width. it gets 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 you omit \&fmt_sub, then a default subroutine, ShowTableValue, steps in, and it uses Perl's standard string formatting rules.

The arguments to \&fmt_sub — whether 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 you don't give it, it 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. that's it, that's the whole plot.

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's a special case usage of ShowTable — which means you can pass it any parameter that's suitable for ShowTable. it's giving nepotism but make it useful. 💅

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

🍓 ShowTables 🍓

Show an array of table names. short and sweet.

ShowTables \@tblnames;

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

ShowTables is used to display a list of table names, under the column heading of "Tables". it's a special case usage of ShowTable, and it can be passed any "ShowTable" argument parameter. yes, any. go wild. 🌸

🎀 ShowColumns 🎀

Display a table of column names, types, and attributes. the whole lil portfolio. 👑

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's a special case usage of ShowTable, and it 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 lives at $col_attrs->[0]. and the first attribute of the second column? that's $col_attrs->[1][0]. nested, bestie. 🪆

The columns, types, lengths, and attributes are all displayed in a table with the column headings: "Column", "Type", "Length", and "Attributes". and again — this is a special case usage of ShowTable, so you can pass it additional arguments suitable for "ShowTable". 💖

💅 ShowBoxTable 💅

Okay bestie, this one's the aesthetic queen of the bunch — it shows you tabular data inside an actual box made of ASCII graphics. Cute and functional.

ShowBoxTable { parameter = value, ... };

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

It displays tabular data in titled columns using a "box" of ASCII graphics, and it looks a lil 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 literally the same as with ShowTable. And heads up — if the @titles array is empty, the header row just gets omitted. No titles, no top row, periodt.

🌸 ShowSimpleTable 🌸

Displays a table of data using a simple table format. No frills, just vibes:

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

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

The ShowSimpleTable subroutine formats data into a simple table of aligned columns, like so:

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

Columns are auto-sized by the data's widths, plus two spaces between columns. And if a value is too long for the maximum column width? It gets wrapped within the column. Flexible, we love her 💖

👑 ShowHTMLTable 👑

Displays a table of data nicely using HTML tables. She went to the web for this one 🦋

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. On top of the usual parameter arguments of ShowTable, these extra parameter arguments are defined:

  • "url_keys" => \%URL_Keys — this is a hash array of column names (titles) and their corresponding base URLs. The values of any column names or indexes occurring as keys in the hash array will be generated as hypertext anchors, using the associated printf-like string as the base URL. You can use either the column name or the column index (beginning with 1) as the hash key — dealer's choice.

In that string value, these macros get 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 defaults to the global variable %URL_Keys.

  • "no_escape" => boolean — unless $no_escape is set, HTML-escaping is performed on the data values so the special HTML formatting characters display properly: '<', '>', and '&'. If you wanna display data with embedded HTML text, you must set $no_escape.

Enabling embedded HTML turns on certain heuristics which let the user define the appearance of the table way more completely. For instance, any <TR> tokens found embedded anywhere within a row of data will be placed at the front of the row, inside 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 get appended in the opposite order. Symmetry, bestie ✨

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 🎀

Displays a table of data using a list format. Different energy, same data.

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 the ones 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. Blunt, but honest 💀

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 with 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 continued 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. She's the little engine that feeds everybody else 🚂

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.

So here's the tea:

  • 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. Lowkey elegant, ngl.

🧚 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 omitted, $max_width is assumed.
  • "precision" => $precision / $precision — the number of decimal digits; zero is assumed if omitted.
  • "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.
Yes bestie, $width, $precision and $max_width each show up twice on that list — that's exactly how she's written. Same name, different hat. Iconic behavior, honestly 💅

✨ PlainText ✨

okay so this is the lil glow-up dip 💅

$plaintext = &PlainText($htmltext);

&PlainText

&PlainText takes your HTML-y text and rips every single HTML formatting sequence right out of it ✨. Pass it an argument and it works on that; pass it nothing and it just goes straight for $_ like it pays rent there 🫶. Either way, the resulting plain text is what you get back as the result. no cap, it's giving "de-influencing" but for markup 🎀

✨ VARIABLES ✨

bestie you can set these yourself and they change how everything looks 👀 — the defaults are hanging out inside the square brackets [..]:

  • $Show_Mode [Box] — the default display mode when you're using ShowTable 👑. If this variable is null or the empty string, the environment variable $ENV{'SHOW_MODE'} gets used instead. The possible values are: "Box", "List", "Table", and "HTML". case is insignificant, so go off however you like.
  • $List_Wrap_Margin [2] — this one decides how big a margin to keep before a long value's display gets wrapped inside a column 🎀. literally only used in "List" mode.
  • $Max_List_Width [80] — "List" mode again, babes: this says how long an output line can get before it gets wrapped 🌸. When it's null, the environment variable $ENV{'COLUMNS'} is used to define this value ✨
  • $Max_Table_Width [''] — set this and every table gets its columns scaled so that their total combined width doesn't exceed this value 🔥. When it's not set (which is the default case), there's no maximum table width and no scaling happens at all. periodt.
  • $No_Escape [''] — if you set it, embedded HTML text is allowed to be included in the data displayed in an HTML-formatted table 😳. by default, though, the HTML formatting characters ("<", ">", and "&") that occur in values get escaped. safety first, bestie 🫶
  • %URL_Keys — in HTML mode, this is what's used to recognize which columns should be displayed with a corresponding hypertext anchor 🔗. see "ShowHTMLTable" for the full tea.
  • @HTML_Elements — an array of HTML elements (as of HTML 3.0) that get used to recognize and strip things out 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;

So you hand it the @argv that originally got passed to the calling sub, plus the hash of named parameters as %params, plus the array of parameter names in the order expected for a pass-by-value invocation — and it sets the values of each of the variables named in @vars 💅

If the only element of the @argv is a hash array, then the variables get set to the values of their corresponding parameters used as keys to that hash array 🔑. And if a parameter isn't a key of the %params hash, and isn't a key in the global hash %ShowTableParams, then an error is noted 😭

When @argv has multiple elements, or just isn't a hash array, then each variable gets set — in the order given inside @arglist — to the values from the @argv, setting the variables named by each value in %params ✨

Variables may be given either by name or by reference 🫶

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

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 one, $prefixes, is an array of prefixes containing the corresponding HTML formatting elements from \@html_formats
  • the second one, $suffixes, holds 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 as "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, also with the proper HTML element syntax 💅

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

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

then the two resulting arrays come back looking like:

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

iconic behaviour honestly 🦋

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 set up internal variables before formatting anything for display 🌈. Calc_widths handles the column width and precision analysis, including scanning the data (if it's rewindable) for appropriate default values 👀

The number of columns in the data is returned, along with three arrays: the declared column widths, the column precision values, and the maximum column widths ✨

RETURN VALUES

  • $num_cols — the number of columns in the data. If the data isn't rewindable, this gets 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 — the column widths array ref, without the precision specs (if there are any). Each column's width value is determined by the original $widthspec value and/or the maximum length of the formatted data for that column 💅
  • $precision — 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 gets examined to determine the maximum default precision 🔍
  • $max_widths — 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, a 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 the column title length are used to work out a reasonable default.

If a column's width portion is a positive, non-zero number, then that column will be exactly this wide, regardless of the value 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 isn't rewindable, and a column's width value is null or zero, then the length of the column title gets 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 saying whether or not the data being formatted is rewindable 🔄. If it's true, one pass over the data gets done to calculate the maximum lengths of the actual formatted data, using $fmt_sub (below), rather than just relying 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 you don't want 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 that 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. $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 get scaled down uniformly 📉. If not set (null), no column width scaling is done at all. periodt.

putcell

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

Outputs 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 gets selected when $wrap_flag is zero or null, or when there's no more text in the current one to be output. The second element gets selected when $wrap_flag is non-zero, and when there's 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 — and neither 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 minimum 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

okay so htmltext is the translator bestie 💅 it takes your regular, unserious plain text and turns it into text that's safe to output into an HTML document. why does that matter? because some characters are little menaces — specifically "&", ">", and "<" — and they must be escaped or they'll absolutely wreck the document. it's giving "text, but make it HTML-legal." ✨

$output = &htmltext( $input [, $allflag ] );
  • $input — the text you're feeding in, bestie.
  • $allflag — if this is non-zero, then all characters are escaped. normally (aka when it's zero or you just don't pass it), only the four HTML syntactic break characters get escaped.

that's the whole vibe. no cap. 🎀

📤 out

Prints text, then a newline. that's it. that's the subroutine. queen behavior honestly 👑

out $fmt [, @text ];

🫧 put

Same energy as out, except no trailing newline — it prints the text and just dips, no goodbye. 🙈

out $fmt [, @text ];
yeah bestie, the page literally shows out in the put synopsis, not put. we are simply reporting the lore as it stands. we do not write it. 🫶

👑 AUTHOR

Alan K. Stebbens <aks@stebbens.org> — the icon, the legend, the main character who wrote this entire thing. crown them. 💖

💀 BUGS

okay so bug report time, respectfully:

  • 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. 💬 so like, if you have thoughts, go off, but do it nicely, fr fr. constructive only, bestie.

and that's the whole page, we're done, periodt 🎀 this was the charm from the ShowTable(3pm) manual — perl v5.36.0, dated 2022-10-13. go forth and slay those tables. 💅🌈💖

📦 where this page comes from