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

FreeBSD Manual Pages

  
 
  

home | help
TabularDisplay(3)     User Contributed Perl Documentation    TabularDisplay(3)

NAME
       Text::TabularDisplay - Display text in formatted	table output

SYNOPSIS
	   use Text::TabularDisplay;

	   my $table = Text::TabularDisplay->new(@columns);
	   $table->add(@row)
	       while (@row = $sth->fetchrow);
	   print $table->render;

	   +----+--------------+
	   | id	| name	       |
	   +----+--------------+
	   | 1	| Tom	       |
	   | 2	| Dick	       |
	   | 3	| Barry	       |
	   |	|  (aka	Bazza) |
	   | 4	| Harry	       |
	   +----+--------------+

DESCRIPTION
       Text::TabularDisplay simplifies displaying textual data in a table.
       The output is identical to the columnar display of query	results	in the
       mysql text monitor.  For	example, this data:

	   1, "Tom Jones", "(666) 555-1212"
	   2, "Barnaby Jones", "(666) 555-1213"
	   3, "Bridget Jones", "(666) 555-1214"

       Used like so:

	   my $t = Text::TabularDisplay->new(qw(id name	phone));
	   $t->add(1, "Tom Jones", "(666) 555-1212");
	   $t->add(2, "Barnaby Jones", "(666) 555-1213");
	   $t->add(3, "Bridget Jones", "(666) 555-1214");
	   print $t->render;

       Produces:

	   +----+---------------+----------------+
	   | id	| name		| phone		 |
	   +----+---------------+----------------+
	   | 1	| Tom Jones	| (666)	555-1212 |
	   | 2	| Barnaby Jones	| (666)	555-1213 |
	   | 3	| Bridget Jones	| (666)	555-1214 |
	   +----+---------------+----------------+

METHODS
       Text::TabularDisplay has	four primary methods: new(), columns(),	add(),
       and render().  new() creates a new Text::TabularDisplay instance;
       columns() sets the column headers in the	output table; add() adds data
       to the instance;	and render() returns a formatted string	representation
       of the instance.

       There are also a	few auxiliary convenience methods: clone(), items(),
       reset(),	populate(), and	paginate().

       new A Text::TabularDisplay instance can be created with column names
	   passed as constructor args, so these	two calls produce similar
	   objects:

	       my $t1 =	Text::TabularDisplay->new;
	       $t1->columns(qw<	one two	>);

	       my $t2 =	Text::TabularDisplay->new(qw< one two >);

	   Calling new() on a Text::TabularDisplay instance returns a clone of
	   the object.	See "clone" in Text::TabularDisplay.

       columns
	   Gets	or sets	the column names for an	instance.  This	method is
	   called automatically	by the constructor with	any parameters that
	   are passed to the constructor (if any are passed).

	   When	called in scalar context, columns() returns the	number of
	   columns in the instance, rather than	the columns themselves.	 In
	   list	context, copies	of the columns names are returned; the names
	   of the columns cannot be modified this way.

       add Takes a list	of items and appends it	to the list of items to	be
	   displayed.  add() can also take a reference to an array, so that
	   large arrays	don't need to be copied.

	   As elements are processed, add() maintains the width	of each	column
	   so that the resulting table has the correct dimensions.

	   add() returns $self,	so that	calls to add() can be chained:

	       $t->add(@one)->add(@two)->add(@three);

       render
	   render() does most of the actual work. It returns a string
	   containing the data added via add(),	formatted as a table, with a
	   header containing the column	names.

	   render() does not change the	state of the object; it	can be called
	   multiple times, with	identical output (including identical running
	   time: the output of render is not cached).

	   If there are	no columns defined, then the output table does not
	   contains a row of column names.  Compare these two sequences:

	       my $t = Text::TabularDisplay->new;
	       $t->add(qw< 1 2 3 4 >);
	       $t->add(qw< 5 6 7 8 >);
	       print $t->render;

	       $t->columns(qw< one two three four >);
	       print $t->render;

	       # Example 1 output
	       +---+---+---+---+
	       | 1 | 2 | 3 | 4 |
	       | 5 | 6 | 7 | 8 |
	       +---+---+---+---+

	       # Example 2 output
	       +-----+-----+-------+------+
	       | one | two | three | four |
	       +-----+-----+-------+------+
	       | 1   | 2   | 3	   | 4	  |
	       | 5   | 6   | 7	   | 8	  |
	       +-----+-----+-------+------+

	   render() takes optional $start and $end arguments; these indicate
	   the start and end indexes for the data to be	rendered.  This	can be
	   used	for paging and the like:

	       $t->add(1, 2, 3)->add(4,	5, 6)->add(7, 8, 9)->add(10, 11, 12);
	       print $t->render(0, 1), "\n";
	       print $t->render(2, 3), "\n";

	   Produces:

	       +-------+--------+-------+
	       | First | Second	| Third	|
	       +-------+--------+-------+
	       | 1     | 2	| 3	|
	       | 4     | 5	| 6	|
	       +-------+--------+-------+

	       +-------+--------+-------+
	       | First | Second	| Third	|
	       +-------+--------+-------+
	       | 7     | 8	| 9	|
	       | 10    | 11	| 12	|
	       +-------+--------+-------+

	   As an aside,	note the chaining of calls to add().

	   The elements	in the table are padded	such that there	is the same
	   number of items in each row,	including the header.  Thus:

	       $t->columns(qw< One Two >);
	       print $t->render;

	       +-----+-----+----+
	       | One | Two |	|
	       +-----+-----+----+
	       | 1   | 2   | 3	|
	       | 4   | 5   | 6	|
	       | 7   | 8   | 9	|
	       | 10  | 11  | 12	|
	       +-----+-----+----+

	   And:

	       $t->columns(qw< One Two Three Four>);
	       print $t->render;

	       +-----+-----+-------+------+
	       | One | Two | Three | Four |
	       +-----+-----+-------+------+
	       | 1   | 2   | 3	   |	  |
	       | 4   | 5   | 6	   |	  |
	       | 7   | 8   | 9	   |	  |
	       | 10  | 11  | 12	   |	  |
	       +-----+-----+-------+------+

OTHER METHODS
       clone()
	   The clone() method returns an identical copy	of a
	   Text::TabularDisplay	instance, completely separate from the cloned
	   instance.

       items()
	   The items() method returns the number of elements currently stored
	   in the data structure:

	       printf "There are %d elements in	\$t.\n", $t->items;

       reset()
	   Reset deletes the data from the instance, including columns.	 If
	   passed arguments, it	passes them to columns(), just like new().

       populate()
	   populate() as a special case	of add(); populate() expects a
	   reference to	an array of references to arrays, such as returned by
	   DBI's selectall_arrayref method:

	       $sql = "SELECT "	. join(", ", @c) . " FROM mytable";
	       $t->columns(@c);
	       $t->populate($dbh->selectall_arrayref($sql));

	   This	is for convenience only; the implementation maps this to
	   multiple calls to add().

NOTES /	ISSUES
       Text::TabularDisplay assumes it is handling strings, and	does stringy
       things with the data, like length() and sprintf().  Non-character data
       can be passed in, of course, but	will be	treated	as strings; this may
       have ramifications for objects that implement overloading.

       The biggest issue, though, is that this module duplicates a some	of the
       functionality of	Data::ShowTable.  Of course, Data::ShowTable is	a
       large, complex monolithic tool that does	a lot of things, while
       Text::TabularDisplay is small and fast.

AUTHOR
       darren chamberlain <darren@cpan.org>

CREDITS
       The following people have contributed patches, suggestions, tests,
       feedback, or good karma:

	   David N. Blank-Edelman
	   Eric	Cholet
	   Ken Youens-Clark
	   Michael Fowler
	   Paul	Cameron
	   Prakash Kailasa
	   Slaven Rezic
	   Harlan Lieberman-Berg
	   Patrick Kuijvenhoven
	   Miko	O'Sullivan

VERSION
       This documentation describes "Text::TabularDisplay" version 1.38.

perl v5.24.1			  2014-07-07		     TabularDisplay(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | OTHER METHODS | NOTES / ISSUES | AUTHOR | CREDITS | VERSION

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

home | help