/ 
Term-TablePrint-0.007
River stage one • 1 direct dependent • 1 total dependent
/ Term::TablePrint

NAME

Term::TablePrint - Print a table to the terminal.

VERSION

Version 0.007

SYNOPSIS

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

DESCRIPTION

print_table prints a table to STDOUT or to STDERR if STDOUT is redirected.

print_table 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 "USAGE".

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 the Return key, each column of that row is output in its one 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

s/^\p{Space}+//;
s/\p{Space}+\z//;

and spaces are squashed to a single white-space.

s/\p{Space}+/ /g;

In addition, characters of the Unicode property Other are removed.

s/\p{C}//g;

In Term::TablePrint the utf8 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.

METHODS

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

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

SUBROUTINES

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

USAGE

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-B) to go back one page, the PageDown key (or Ctrl-F) to go forward one page.

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

  • the Return key to close the table or to print the highlighted row if table_expand is enabled.

With the option table_expand disabled:

- if the cursor is on the table head Return closes the table.

- if the cursor is not on the table head the cursor jumps to the table head if Return is pressed.

With the option table_expand enabled:

- selecting the head of the table closes the table.

- if a row is selected, each column of that row is output in its one line preceded by the column name. Another Return closes 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.

- if the width of the window is changed the user can rewrite the screen by choosing a row.

OPTIONS

Defaults may change in a future release.

header_row DEPRECATED

This option is deprecated and will be removed. Use the option add_header instead.

If the default value is kept print_table expects the first row as a header row.

If set to 0 print_table adds a header row - the columns are numbered starting with 1.

Default: 1

add_header

If set to 1 print_table adds a header row - the columns are numbered starting with 1.

Default: 0

choose_columns

If 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 users confirms with the -ok- menu entry.

Default: 0

tab_width

Set the number of spaces between columns.

Default: 2

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 have been trimmed to min_col_width.

Default: 30

undef

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

Default: "" (empty string)

max_rows

Set the maximum number of printed table rows.

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.

Default: 50_000

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: 20_000

table_expand

table_expand set to 1 enables printing the chosen table row by pressing the Return key.

If set to 0 the cursor jumps to the to header row (if not already there) when Return pressed.

Default: 1

mouse

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

Default: 0

binary_filter

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

Default: 0

ERROR HANDLING

Carp

print_table warns

  • if an unknown option name is passed.

Croak

print_table dies

  • with an invalid number of arguments.

  • if an invalid argument is passed.

  • if an invalid option value is passed.

REQUIREMENTS

Perl version

Requires Perl version 5.10.1 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.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Term::TablePrint

AUTHOR

Matthäus Kiem <cuer2s@gmail.com>

CREDITS

Thanks to the Perl-Community.de and the people form stackoverflow for the help.

LICENSE AND COPYRIGHT

Copyright 2012-2014 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.