KEYS

Keys to move around:

• the "ArrowDown" key (or the "j" key) to move down and the "ArrowUp" key (or the "k" key) to move up.
• the "PageUp" key (or "Ctrl-P") to go to the previous page, the "PageDown" key (or "Ctrl-N") to go to the next page.
• the "Insert" key to go back 10 pages, the "Delete" key to go forward 10 pages.
• the "Home" key (or "Ctrl-A") to jump to the first row of the table, the "End" key (or "Ctrl-E") to jump to the last row of the table.

If table_expand is set to 0, the "Enter" key closes the table if the cursor is on the first row.

If table_expand is enabled and the cursor is on the first row, pressing "Enter" three times in succession closes the table. If the cursor is auto-jumped to the first row, it is required only one "Enter" to close the table.

If the cursor is not on the first row:

• with the option table_expand disabled the cursor jumps to the table head if "Enter" is pressed.
• with the option table_expand enabled each column of the selected row is output in its own line preceded by the column name if "Enter" is pressed. Another "Enter" closes this output and goes back to the table output. If a row is selected twice in succession, the pointer jumps to the first row.

If the size of the window has changed, the screen is rewritten as soon as the user presses a key.

"Ctrl-F" opens a prompt. A regular expression is expected as input. This enables one to only display rows where at least one column matches the entered pattern. See option "search".

Output

If the option "table_expand" is enabled and a row is selected with "Enter", each column of that row is output in its own line preceded by the column name.

If the table has more rows than the terminal, the table is divided up on as many pages as needed automatically. If the cursor reaches the end of a page, the next page is shown automatically until the last page is reached. Also if the cursor reaches the topmost line, the previous page is shown automatically if it is not already the first page.

For the output on the screen the table elements are modified. All the modifications are made on a copy of the original table data.

• If an element is not defined the value from the option undef is assigned to that element.
• Each character tabulation ("\t") is replaces with a space.
• Vertical tabulations ("\v+") are squashed to two spaces.
• Code points from the ranges of "control", "surrogate" and "noncharacter" are removed.
• If the option squash_spaces is enabled leading and trailing spaces are removed and multiple consecutive spaces are squashed to a single space.
• If an element looks like a number it is right-justified, else it is left-justified.

If the terminal is too narrow to print the table, the columns are adjusted to the available width automatically.

• First, if the option trunc_fract_first is enabled and if there are numbers that have a fraction, the fraction is truncated up to two decimal places.
• Then columns wider than min_col_width are trimmed. See option "min_col_width".
• If it is still required to lower the row width all columns are trimmed until they fit into the terminal.

new

The "new" method returns a "Term::TablePrint" object. As an argument it can be passed a reference to a hash which holds the options - the available options are listed in "OPTIONS".

    my $tp = Term::TablePrint->new( \%options );

print_table

The "print_table" method prints the table passed with the first argument.

    $tp->print_table( $array_ref, \%options );

The first argument is a reference to an array of arrays. The first array of these arrays holds the column names. The following arrays are the table rows where the elements are the field values.

As a second and optional argument a hash reference can be passed which holds the options - the available options are listed in "OPTIONS".

print_table

The "print_table" subroutine prints the table passed with the first argument.

    print_table( $array_ref, \%options );

The subroutine "print_table" takes the same arguments as the method "print_table".

OPTIONS

binary_filter

How to print arbitrary binary data:

0 - print the binary data as it is

1 - "BNRY" is printed instead of the binary data

2 - the binary data is printed in hexadecimal format

If the substring of the first 100 characters of the data matches the repexp "/[\x00-\x08\x0B-\x0C\x0E-\x1F]/", the data is considered arbitrary binary data.

Printing unfiltered arbitrary binary data could break the output.

Default: 0

codepage_mapping

This option has only meaning if the operating system is MSWin32.

If the OS is MSWin32, Win32::Console::ANSI is used. By default "Win32::Console::ANSI" converts the characters from Windows code page to DOS code page (the so-called ANSI to OEM conversion). This conversation is disabled by default in "Term::Choose" but one can enable it by setting this option.

Setting this option to 1 enables the codepage mapping offered by Win32::Console::ANSI.

0 - disable automatic codepage mapping

1 - keep automatic codepage mapping

Default: 0

color

Enable the support for ANSI SGR escape sequences.

0 - off (default)

1 - enabled except for the current selected row

2 - enabled

Colors are reset to normal after the end of each table field.

Numbers with added escape sequences are aligned to the left.

Default: 0

decimal_separator

Set the decimal separator. Numbers with a decimal separator are formatted as number if this option is set to the right value.

Allowed values: a character with a print width of 1. If an invalid values is passed, decimal_separator falls back to the default value.

Default: . (dot)

footer

If set (string), footer is added in the bottom line to the page number. It is up to the user to add leading and trailing separators.

If a footer string is passed with this option, the option page is automatically set to 2.

Default: undef

info

Expects as its value a string. The info text is printed above the prompt string.

Default: undef

max_rows

Set the maximum number of used table rows. The used table rows are kept in memory.

max_rows does not include the header row: max_rows set to 3 would print the header row plus 3 table rows.

To disable the automatic limit, do not set "max_rows" or set "max_rows" to "undef". Setting "max_rows" to 0 could mean in a future release to limit the output to 0 data rows.

If the number of table rows is higher than max_rows, the last row of the output tells that the limit has been reached.

Default: 0

max_width_exp

Set a maximum width of the expanded table row output. (See option "table_expand").

min_col_width

The columns with a width below or equal min_col_width are only trimmed, if it is still required to lower the row width despite all columns wider than min_col_width have been trimmed to min_col_width.

Default: 30

mouse

Set the mouse mode (see option "mouse" in "OPTIONS" in Term::Choose).

Default: 0

pad_row_edges

Add a space at the beginning and end of each row.

0 - off (default)

1 - enabled

progress_bar

Set the progress bar threshold. If the number of fields (rows x columns) is higher than the threshold, a progress bar is shown while preparing the data for the output.

Default: 40_000

prompt

String displayed above the table.

search

Set the behavior of "Ctrl-F".

0 - off

1 - case-insensitive search

2 - case-sensitive search

When "Ctrl-F" is pressed and a regexp is entered, the regexp is appended to the end of the footer.

Default: 1

squash_spaces

If squash_spaces is enabled, consecutive spaces are squashed to one space and leading and trailing spaces are removed.

Default: 0

tab_width

Set the number of spaces between columns.

Default: 2

table_expand

If table_expand is enabled and "Enter" is pressed, the selected table row prints with each column on a new line. Pressing "Enter" again closes this view. The next "Enter" key press will automatically jump the cursor to the first row. If the cursor has automatically jumped to the first row, pressing "Enter" will close the table instead of expanding the first row. Pressing any key other than "Enter" resets these special behaviors.

If table_expand is set to 0, the cursor jumps to the to first row (if not already there) when "Enter" is pressed.

0 - off

1 - on

Default: 1

trunc_fract_first

If the terminal width is not wide enough and this option is enabled, the first step to reduce the width of the columns is to truncate the fraction part of numbers to 2 decimal places.

undef

Set the string that will be shown on the screen instead of an undefined field.

Default: "" (empty string)

Perl version

Requires Perl version 5.16.0 or greater.

Decoded strings

"print_table" expects decoded strings.

Encoding layer for STDOUT

For a correct output it is required to set an encoding layer for "STDOUT" matching the terminal's character set.

Monospaced font

It is required a terminal that uses a monospaced font which supports the printed characters.