1TabularDisplay(3)     User Contributed Perl Documentation    TabularDisplay(3)
2
3
4

NAME

6       Text::TabularDisplay - Display text in formatted table output
7

SYNOPSIS

9           use Text::TabularDisplay;
10
11           my $table = Text::TabularDisplay->new(@columns);
12           $table->add(@row)
13               while (@row = $sth->fetchrow);
14           print $table->render;
15
16           +----+--------------+
17           | id | name         |
18           +----+--------------+
19           | 1  | Tom          |
20           | 2  | Dick         |
21           | 3  | Barry        |
22           |    |  (aka Bazza) |
23           | 4  | Harry        |
24           +----+--------------+
25

DESCRIPTION

27       Text::TabularDisplay simplifies displaying textual data in a table.
28       The output is identical to the columnar display of query results in the
29       mysql text monitor.  For example, this data:
30
31           1, "Tom Jones", "(666) 555-1212"
32           2, "Barnaby Jones", "(666) 555-1213"
33           3, "Bridget Jones", "(666) 555-1214"
34
35       Used like so:
36
37           my $t = Text::TabularDisplay->new(qw(id name phone));
38           $t->add(1, "Tom Jones", "(666) 555-1212");
39           $t->add(2, "Barnaby Jones", "(666) 555-1213");
40           $t->add(3, "Bridget Jones", "(666) 555-1214");
41           print $t->render;
42
43       Produces:
44
45           +----+---------------+----------------+
46           | id | name          | phone          |
47           +----+---------------+----------------+
48           | 1  | Tom Jones     | (666) 555-1212 |
49           | 2  | Barnaby Jones | (666) 555-1213 |
50           | 3  | Bridget Jones | (666) 555-1214 |
51           +----+---------------+----------------+
52

METHODS

54       Text::TabularDisplay has four primary methods: new(), columns(), add(),
55       and render().  new() creates a new Text::TabularDisplay instance;
56       columns() sets the column headers in the output table; add() adds data
57       to the instance; and render() returns a formatted string representation
58       of the instance.
59
60       There are also a few auxiliary convenience methods: clone(), items(),
61       reset(), populate(), and paginate().
62
63       new A Text::TabularDisplay instance can be created with column names
64           passed as constructor args, so these two calls produce similar
65           objects:
66
67               my $t1 = Text::TabularDisplay->new;
68               $t1->columns(qw< one two >);
69
70               my $t2 = Text::TabularDisplay->new(qw< one two >);
71
72           Calling new() on a Text::TabularDisplay instance returns a clone of
73           the object.  See "clone" in Text::TabularDisplay.
74
75       columns
76           Gets or sets the column names for an instance.  This method is
77           called automatically by the constructor with any parameters that
78           are passed to the constructor (if any are passed).
79
80           When called in scalar context, columns() returns the number of
81           columns in the instance, rather than the columns themselves.  In
82           list context, copies of the columns names are returned; the names
83           of the columns cannot be modified this way.
84
85       add Takes a list of items and appends it to the list of items to be
86           displayed.  add() can also take a reference to an array, so that
87           large arrays don't need to be copied.
88
89           As elements are processed, add() maintains the width of each column
90           so that the resulting table has the correct dimensions.
91
92           add() returns $self, so that calls to add() can be chained:
93
94               $t->add(@one)->add(@two)->add(@three);
95
96       render
97           render() does most of the actual work. It returns a string
98           containing the data added via add(), formatted as a table, with a
99           header containing the column names.
100
101           render() does not change the state of the object; it can be called
102           multiple times, with identical output (including identical running
103           time: the output of render is not cached).
104
105           If there are no columns defined, then the output table does not
106           contains a row of column names.  Compare these two sequences:
107
108               my $t = Text::TabularDisplay->new;
109               $t->add(qw< 1 2 3 4 >);
110               $t->add(qw< 5 6 7 8 >);
111               print $t->render;
112
113               $t->columns(qw< one two three four >);
114               print $t->render;
115
116               # Example 1 output
117               +---+---+---+---+
118               | 1 | 2 | 3 | 4 |
119               | 5 | 6 | 7 | 8 |
120               +---+---+---+---+
121
122               # Example 2 output
123               +-----+-----+-------+------+
124               | one | two | three | four |
125               +-----+-----+-------+------+
126               | 1   | 2   | 3     | 4    |
127               | 5   | 6   | 7     | 8    |
128               +-----+-----+-------+------+
129
130           render() takes optional $start and $end arguments; these indicate
131           the start and end indexes for the data to be rendered.  This can be
132           used for paging and the like:
133
134               $t->add(1, 2, 3)->add(4, 5, 6)->add(7, 8, 9)->add(10, 11, 12);
135               print $t->render(0, 1), "\n";
136               print $t->render(2, 3), "\n";
137
138           Produces:
139
140               +-------+--------+-------+
141               | First | Second | Third |
142               +-------+--------+-------+
143               | 1     | 2      | 3     |
144               | 4     | 5      | 6     |
145               +-------+--------+-------+
146
147               +-------+--------+-------+
148               | First | Second | Third |
149               +-------+--------+-------+
150               | 7     | 8      | 9     |
151               | 10    | 11     | 12    |
152               +-------+--------+-------+
153
154           As an aside, note the chaining of calls to add().
155
156           The elements in the table are padded such that there is the same
157           number of items in each row, including the header.  Thus:
158
159               $t->columns(qw< One Two >);
160               print $t->render;
161
162               +-----+-----+----+
163               | One | Two |    |
164               +-----+-----+----+
165               | 1   | 2   | 3  |
166               | 4   | 5   | 6  |
167               | 7   | 8   | 9  |
168               | 10  | 11  | 12 |
169               +-----+-----+----+
170
171           And:
172
173               $t->columns(qw< One Two Three Four>);
174               print $t->render;
175
176               +-----+-----+-------+------+
177               | One | Two | Three | Four |
178               +-----+-----+-------+------+
179               | 1   | 2   | 3     |      |
180               | 4   | 5   | 6     |      |
181               | 7   | 8   | 9     |      |
182               | 10  | 11  | 12    |      |
183               +-----+-----+-------+------+
184

OTHER METHODS

186       clone()
187           The clone() method returns an identical copy of a
188           Text::TabularDisplay instance, completely separate from the cloned
189           instance.
190
191       items()
192           The items() method returns the number of elements currently stored
193           in the data structure:
194
195               printf "There are %d elements in \$t.\n", $t->items;
196
197       reset()
198           Reset deletes the data from the instance, including columns.  If
199           passed arguments, it passes them to columns(), just like new().
200
201       populate()
202           populate() as a special case of add(); populate() expects a
203           reference to an array of references to arrays, such as returned by
204           DBI's selectall_arrayref method:
205
206               $sql = "SELECT " . join(", ", @c) . " FROM mytable";
207               $t->columns(@c);
208               $t->populate($dbh->selectall_arrayref($sql));
209
210           This is for convenience only; the implementation maps this to
211           multiple calls to add().
212

NOTES / ISSUES

214       Text::TabularDisplay assumes it is handling strings, and does stringy
215       things with the data, like length() and sprintf().  Non-character data
216       can be passed in, of course, but will be treated as strings; this may
217       have ramifications for objects that implement overloading.
218
219       The biggest issue, though, is that this module duplicates a some of the
220       functionality of Data::ShowTable.  Of course, Data::ShowTable is a
221       large, complex monolithic tool that does a lot of things, while
222       Text::TabularDisplay is small and fast.
223

AUTHOR

225       darren chamberlain <darren@cpan.org>
226

CREDITS

228       The following people have contributed patches, suggestions, tests,
229       feedback, or good karma:
230
231           David N. Blank-Edelman
232           Eric Cholet
233           Ken Youens-Clark
234           Michael Fowler
235           Paul Cameron
236           Prakash Kailasa
237           Slaven Rezic
238           Harlan Lieberman-Berg
239           Patrick Kuijvenhoven
240           Miko O'Sullivan
241

VERSION

243       This documentation describes "Text::TabularDisplay" version 1.38.
244
245
246
247perl v5.36.0                      2023-01-20                 TabularDisplay(3)
Impressum