Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Term::TablePrint(3)   User Contributed Perl Documentation  Term::TablePrint(3)

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

VERSION
       Version 0.123

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

       The following modifications are made (at	a copy of the original data)
       to the table elements before the	output.

       Tab characters ("\t") are replaces with a space.

       Vertical	spaces ("\v") are squashed to two spaces

       Control characters, code	points of the surrogate	ranges and non-
       characters are removed.

       If the option squash_spaces is enabled leading and trailing spaces are
       removed from the	array elements and spaces are squashed to a single
       space.

       If an element looks like	a number it is left-justified, else it is
       right-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 ] );

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

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

USAGE
   KEYS
       Keys to move around:

       o   the "ArrowDown" key (or the "j" key)	to move	down and  the
	   "ArrowUp" key (or the "k" key) to move up.

       o   the "PageUp"	key (or	"Ctrl-B") to go	back one page, the "PageDown"
	   key (or "Ctrl-F") to	go forward one page.

       o   the "Insert"	key to go back 25 pages, the "Delete" key to go
	   forward 25 pages.

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

       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 0, the "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:

       o   with	the option table_expand	disabled the cursor jumps to the table
	   head	if "Return" is pressed.

       o   with	the option table_expand	enabled	each column of the selected
	   row is output in its	own line preceded by the column	name if
	   "Return" is pressed.	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 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".

   OPTIONS
       Defaults	may change in a	future release.

       prompt

       String displayed	above the table.

       binary_filter

       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.

       Default:	0

       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.

       Confirming without any selected columns selects all columns.

       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)

       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

       Setting color to	1 enables the support for color	and text formatting
       escape sequences	except for the current selected	element. If set	to 2,
       also for	the current selected element the color support is enabled
       (inverted colors).

       Default:	0

       grid

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

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

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

       grid set	to 2 is	like grid set to 1 plus	a separator line on top	of the
       header row.

       Default:	1

       keep-header

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

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

       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

       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 tells that the limit has been reached.

       Default:	200_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 "OPTIONS" 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.

       Default:	40_000

       tab_width

       Set the number of spaces	between	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.

       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

       table_name

       If set (string),	table_name is added in the bottom line.

       undef

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

       Default:	"" (empty string)

ERROR HANDLING
       "print_table" dies

       o   if an invalid number	of arguments is	passed.

       o   if an invalid argument is passed.

       o   if an unknown option	name is	passed.

       o   if an invalid option	value is passed.

REQUIREMENTS
   Perl	version
       Requires	Perl version 5.8.3 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

SEE ALSO
       App::DBBrowser

CREDITS
       Thanks to the Perl-Community.de <http://www.perl-community.de> and the
       people form stackoverflow <http://stackoverflow.com> for	the help.

AUTHOR
       MatthAxus Kiem <cuer2s@gmail.com>

LICENSE	AND COPYRIGHT
       Copyright 2013-2020 MatthAxus 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.

perl v5.32.1			  2020-10-25		   Term::TablePrint(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | SUBROUTINES | USAGE | ERROR HANDLING | REQUIREMENTS | SUPPORT | SEE ALSO | CREDITS | AUTHOR | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Term::TablePrint&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help