- ERROR HANDLING
- SEE ALSO
- LICENSE AND COPYRIGHT
Term::TablePrint - Print a table to the terminal and browse it interactively.
my $table = [ [ 'id', 'name' ], [ 1, 'Ruth' ], [ 2, 'John' ], [ 3, 'Mark' ], [ 4, 'Nena' ], ]; use Term::TablePrint qw( print_table ); print_table( $table ); # or OO style: use Term::TablePrint; my $pt = Term::TablePrint->new(); $pt->print_table( $table );
print_table shows a table and lets the user interactively browse it. It provides a cursor which highlights the row on which it is located. The user can scroll through the table with the different cursor keys - see "KEYS".
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 one.
If the terminal is too narrow to print the table, the columns are adjusted to the available width automatically.
If the option table_expand is enabled and a row is selected with Return, each column of that row is output in its own line preceded by the column name. This might be useful if the columns were cut due to the too low terminal width.
To get a proper output
print_table uses the
columns method from Unicode::GCString to calculate the string length.
The following modifications are made (at a copy of the original data) before the output.
Leading and trailing spaces are removed from the array elements
and spaces are squashed to a single white-space.
In addition, characters of the Unicode property
Other are removed.
warnings are disabled.
no warnings 'utf8';
The elements in a column are right-justified if one or more elements of that column do not look like a number, else they are left-justified.
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 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 subroutine prints the table passed with the first argument.
print_table( $array_ref, [ \%options ] );
print_table takes the same arguments as the method "print_table".
Keys to move around:
ArrowDownkey (or the
jkey) to move down and the
ArrowUpkey (or the
kkey) to move up.
Ctrl-B) to go back one page, the
Ctrl-F) to go forward one page.
Ctrl-A) to jump to the first row of the table, the
Ctrl-E) to jump to the last row of the table.
With keep_header disabled the
Return key closes the table if the cursor is on the header row.
If keep_header is enabled and table_expand is set to
Return key closes the table if the cursor is on the first row.
If keep_header and table_expand are enabled and the cursor is on the first row, pressing
Return three times in succession closes the table. If table_expand is set to
1 and the cursor is auto-jumped to the first row, it is required only one
Return 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
with the option table_expand enabled each column of the selected row is output in its own line preceded by the column name if
Returnis pressed. Another
Returncloses this output and goes back to the table output. If a row is selected twice in succession, the pointer jumps to the head of the table or to the first row if keep_header is enabled.
If the size of the window is changed, the screen is rewritten as soon as the user presses a key.
If the option choose_columns is enabled, the
SpaceBar key (or the right mouse key) can be used to select columns - see option "choose_columns".
Defaults may change in a future release.
String displayed above the table.
If add_header is set to 1,
print_table adds a header row - the columns are numbered starting with 1.
If binary_filter is set to 1, "BNRY" is printed instead of arbitrary binary data.
If the data matches the repexp
/[\x00-\x08\x0B-\x0C\x0E-\x1F]/, it is considered arbitrary binary data.
Printing arbitrary binary data could break the output.
If choose_columns is set to 1, the user can choose which columns to print. The columns can be marked with the
SpaceBar. The list of marked columns including the highlighted column are printed as soon as
Return is pressed.
If choose_columns is set to 2, it is possible to change the order of the columns. Columns can be added (with the
SpaceBar and the
Return key) until the user confirms with the -ok- menu entry.
If keep_header is set to 1, the table header is shown on top of each page.
If keep_header is set to 0, the table header is shown on top of the first page.
Set the maximum number of used table rows. The used table rows are kept in memory.
To disable the automatic limit set max_rows to 0.
If the number of table rows is equal to or higher than max_rows, the last row of the output says "REACHED LIMIT" or "=LIMIT=" if "REACHED LIMIT" doesn't fit in the row.
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.
Set the mouse mode (see option
mouse in "OPTIONS" in Term::Choose).
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.
Set the number of spaces between columns.
If the option table_expand is set to
Return is pressed, the selected table row is printed with each column in its own line. Exception: if table_expand is set to
1 and the cursor auto-jumped to the first row, the first row will not be expanded.
If table_expand is set to 0, the cursor jumps to the to first row (if not already there) when
Return is pressed.
Set the string that will be shown on the screen instead of an undefined field.
Default: "" (empty string)
if an unknown option name is passed.
if an invalid number of arguments is passed.
if an invalid argument is passed.
if an invalid option value is passed.
if the first argument refers to an empty array.
Requires Perl version 5.8.3 or greater.
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.
It is required a terminal that uses a monospaced font which supports the printed characters.
You can find documentation for this module with the perldoc command.
Matthäus Kiem <firstname.lastname@example.org>
LICENSE AND COPYRIGHT
Copyright 2013-2016 Matthäus Kiem.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For details, see the full text of the licenses in the file LICENSE.