Help language development. Donate to The Perl Foundation

Term::TablePrint cpan:KUERBIS last updated on 2018-08-24

Term-TablePrint-1.3.1/

Build Status

NAME

Term::TablePrint - Print a table to the terminal and browse it interactively.

SYNOPSIS

    use Term::TablePrint :print-table;


    my @table = ( [ 'id', 'name' ],
                  [    1, 'Ruth' ],
                  [    2, 'John' ],
                  [    3, 'Mark' ],
                  [    4, 'Nena' ], );


    # Functional style:

    print-table( @table );


    # or OO style:

    my $pt = Term::TablePrint.new();

    $pt.print-table( @table, :mouse(1), :choose-columns(1) );

DESCRIPTION

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.

Before the output modifications are made (at a copy of the original data). Leading and trailing whitespaces are removed and spaces are squashed to a single white-space. In addition, characters of the Unicode property Other are removed.

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.

USAGE

KEYS

Keys to move around:

With format set to 0 the Return key closes the table if the cursor is on the header row.

If format is enabled (set to 1 or 2) and table-expand is set to 0, the Return key closes the table if the cursor is on the first row.

If format 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:

If the width of the window is changed and the option table-expand is enabled, the user can rewrite the screen by choosing a row.

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.

CONSTRUCTOR

The constructor method new can be called with named arguments. For the valid options see #OPTIONS. Setting the options in new overwrites the default values for the instance.

Additionally to the options mentioned below one can set the option win. The opton win expects as its value a WINDOW object - the return value of NCurses initscr.

If set, print-table uses this global window instead of creating its own without calling endwin to restores the terminal before returning.

ROUTINES

print-table prints the table passed with the first argument.

print-table( @table, *%options );

The first argument is an list 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.

The following arguments set the options (key-values pairs).

OPTIONS

Defaults may change in future releases.

prompt

String displayed above the table.

choose-columns

If choose-columns is set to 1, the user can choose which columns to print. Columns can be added (with the SpaceBar and the Return key) until the user confirms with the -ok- menu entry.

Default: 0

keep-header

If keep-header is set to 0, the table header is shown on top of the first page.

    .----------------------------.    .----------------------------.    .----------------------------.
    |col1   col2     col3   col3 |    |.....  .......  .....  .....|    |.....  .......  .....  .....|
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |.....  .......  .....  .....|
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |                            |
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |                            |
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |                            |
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |                            |
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |                            |
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |                            |
    | 1/3                        |    | 2/3                        |    | 3/3                        |
    '----------------------------'    '----------------------------'    '----------------------------'

If keep-header is set to 1, the table header is shown on top of each page.

    .----------------------------.    .----------------------------.    .----------------------------.
    |col1   col2     col3   col3 |    |col1   col2     col3   col4 |    |col1   col2     col3   col4 |
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |.....  .......  .....  .....|
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |.....  .......  .....  .....|
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |.....  .......  .....  .....|
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |                            |
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |                            |
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |                            |
    |.....  .......  .....  .....|    |.....  .......  .....  .....|    |                            |
    | 1/3                        |    | 2/3                        |    | 3/3                        |
    '----------------------------'    '----------------------------'    '----------------------------'

Default: 1

grid

If grid is set to 1 lines separate the columns from each other and the header from the body.

    .----------------------------.
    |col1 | col2   | col3 | col3 |
    |-----|--------|------|------|
    |.... | ...... | .... | .... |
    |.... | ...... | .... | .... |
    |.... | ...... | .... | .... |
    |.... | ...... | .... | .... |
    |.... | ...... | .... | .... |
    |.... | ...... | .... | .... |
    |.... | ...... | .... | .... |
    |.... | ...... | .... | .... |
    '----------------------------'

If set to 0 the table is shown with no grid.

    .----------------------------.
    |col1  col2     col3   col3  |
    |....  .......  .....  ..... |
    |....  .......  .....  ..... |
    |....  .......  .....  ..... |
    |....  .......  .....  ..... |
    |....  .......  .....  ..... |
    |....  .......  .....  ..... |
    |....  .......  .....  ..... |
    |....  .......  .....  ..... |
    |                            |
    '----------------------------'

Default: 0

max-rows

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 "MAX_ROWS": $limit or =LIMIT= $limit if the previous doesn't fit in the row.

Default: 50_000

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 Term::Choose).

Default: 0

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. Setting the value to 0 disables the progress bar.

Default: 10_000

tab-width

Set the number of spaces between columns. If format is set to 2 and tab-width is even, the spaces between the columns are tab-width + 1 print columns.

Default: 2

table-expand

If the option table-expand is set to 1 or 2 and 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.

    .----------------------------.        .----------------------------.
    |col1 | col2   | col3 | col3 |        |                            |
    |-----|--------|------|------|        |col1 : ..........           |
    |.... | ...... | .... | .... |        |                            |
    |.... | ...... | .... | .... |        |col2 : .....................|
   >|.... | ...... | .... | .... |        |       ..........           |
    |.... | ...... | .... | .... |        |                            |
    |.... | ...... | .... | .... |        |col3 : .......              |
    |.... | ...... | .... | .... |        |                            |
    |.... | ...... | .... | .... |        |col4 : .............        |
    |.... | ...... | .... | .... |        |                            |
    '----------------------------'        '----------------------------'

If table-expand is set to 0, the cursor jumps to the to first row (if not already there) when Return is pressed.

Default: 1

undef

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

Default: "" (empty string)

ENVIRONMET VARIABLES

multithreading

Term::TablePrint uses multithreading when preparing the list for the output; the number of threads to use can be set with the environment variable TC_NUM_THREADS. To find out the setting of "number of treads" see Term::Choose/ENVIRONMET.

head2 libncurses

The location of the used ncurses library can be specified by setting the environment variable PERL6_NCURSES_LIB. This will overwrite the autodetected ncurses library location.

REQUIREMENTS

libncurses

Requires libncursesw to be installed. If the list elements contain wide characters, it is required an approprirate ncurses library else wide character will break the output.

Monospaced font

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

CREDITS

Thanks to the people from Perl-Community.de, from stackoverflow and from #perl6 on irc.freenode.net for the help.

AUTHOR

Matthäus Kiem cuer2s@gmail.com

LICENSE AND COPYRIGHT

Copyright 2016-2018 Matthäus Kiem.

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.