1NAME
2 Text::TabularDisplay - Display text in formatted table output
3
4SYNOPSIS
5 use Text::TabularDisplay;
6
7 my $table = Text::TabularDisplay->new(@columns);
8 $table->add(@row)
9 while (@row = $sth->fetchrow);
10 print $table->render;
11
12 +----+--------------+
13 | id | name |
14 +----+--------------+
15 | 1 | Tom |
16 | 2 | Dick |
17 | 3 | Barry |
18 | | (aka Bazza) |
19 | 4 | Harry |
20 +----+--------------+
21
22DESCRIPTION
23 Text::TabularDisplay simplifies displaying textual data in a table. The
24 output is identical to the columnar display of query results in the
25 mysql text monitor. For example, this data:
26
27 1, "Tom Jones", "(666) 555-1212"
28 2, "Barnaby Jones", "(666) 555-1213"
29 3, "Bridget Jones", "(666) 555-1214"
30
31 Used like so:
32
33 my $t = Text::TabularDisplay->new(qw(id name phone));
34 $t->add(1, "Tom Jones", "(666) 555-1212");
35 $t->add(2, "Barnaby Jones", "(666) 555-1213");
36 $t->add(3, "Bridget Jones", "(666) 555-1214");
37 print $t->render;
38
39 Produces:
40
41 +----+---------------+----------------+
42 | id | name | phone |
43 +----+---------------+----------------+
44 | 1 | Tom Jones | (666) 555-1212 |
45 | 2 | Barnaby Jones | (666) 555-1213 |
46 | 3 | Bridget Jones | (666) 555-1214 |
47 +----+---------------+----------------+
48
49METHODS
50 Text::TabularDisplay has four primary methods: new(), columns(), add(),
51 and render(). new() creates a new Text::TabularDisplay instance;
52 columns() sets the column headers in the output table; add() adds data
53 to the instance; and render() returns a formatted string representation
54 of the instance.
55
56 There are also a few auxiliary convenience methods: clone(), items(),
57 reset(), populate(), and paginate().
58
59 new A Text::TabularDisplay instance can be created with column names
60 passed as constructor args, so these two calls produce similar
61 objects:
62
63 my $t1 = Text::TabularDisplay->new;
64 $t1->columns(qw< one two >);
65
66 my $t2 = Text::TabularDisplay->new(qw< one two >);
67
68 Calling new() on a Text::TabularDisplay instance returns a clone of
69 the object. See "clone" in Text::TabularDisplay.
70
71 columns
72 Gets or sets the column names for an instance. This method is called
73 automatically by the constructor with any parameters that are passed
74 to the constructor (if any are passed).
75
76 When called in scalar context, columns() returns the *number of
77 columns in the instance*, rather than the columns themselves. In
78 list context, copies of the columns names are returned; the names of
79 the columns cannot be modified this way.
80
81 add Takes a list of items and appends it to the list of items to be
82 displayed. add() can also take a reference to an array, so that
83 large arrays don't need to be copied.
84
85 As elements are processed, add() maintains the width of each column
86 so that the resulting table has the correct dimensions.
87
88 add() returns $self, so that calls to add() can be chained:
89
90 $t->add(@one)->add(@two)->add(@three);
91
92 render
93 render() does most of the actual work. It returns a string
94 containing the data added via add(), formatted as a table, with a
95 header containing the column names.
96
97 render() does not change the state of the object; it can be called
98 multiple times, with identical output (including identical running
99 time: the output of render is not cached).
100
101 If there are no columns defined, then the output table does not
102 contains a row of column names. Compare these two sequences:
103
104 my $t = Text::TabularDisplay->new;
105 $t->add(qw< 1 2 3 4 >);
106 $t->add(qw< 5 6 7 8 >);
107 print $t->render;
108
109 $t->columns(qw< one two three four >);
110 print $t->render;
111
112 # Example 1 output
113 +---+---+---+---+
114 | 1 | 2 | 3 | 4 |
115 | 5 | 6 | 7 | 8 |
116 +---+---+---+---+
117
118 # Example 2 output
119 +-----+-----+-------+------+
120 | one | two | three | four |
121 +-----+-----+-------+------+
122 | 1 | 2 | 3 | 4 |
123 | 5 | 6 | 7 | 8 |
124 +-----+-----+-------+------+
125
126 render() takes optional $start and $end arguments; these indicate
127 the start and end *indexes* for the data to be rendered. This can be
128 used for paging and the like:
129
130 $t->add(1, 2, 3)->add(4, 5, 6)->add(7, 8, 9)->add(10, 11, 12);
131 print $t->render(0, 1), "\n";
132 print $t->render(2, 3), "\n";
133
134 Produces:
135
136 +-------+--------+-------+
137 | First | Second | Third |
138 +-------+--------+-------+
139 | 1 | 2 | 3 |
140 | 4 | 5 | 6 |
141 +-------+--------+-------+
142
143 +-------+--------+-------+
144 | First | Second | Third |
145 +-------+--------+-------+
146 | 7 | 8 | 9 |
147 | 10 | 11 | 12 |
148 +-------+--------+-------+
149
150 As an aside, note the chaining of calls to add().
151
152 The elements in the table are padded such that there is the same
153 number of items in each row, including the header. Thus:
154
155 $t->columns(qw< One Two >);
156 print $t->render;
157
158 +-----+-----+----+
159 | One | Two | |
160 +-----+-----+----+
161 | 1 | 2 | 3 |
162 | 4 | 5 | 6 |
163 | 7 | 8 | 9 |
164 | 10 | 11 | 12 |
165 +-----+-----+----+
166
167 And:
168
169 $t->columns(qw< One Two Three Four>);
170 print $t->render;
171
172 +-----+-----+-------+------+
173 | One | Two | Three | Four |
174 +-----+-----+-------+------+
175 | 1 | 2 | 3 | |
176 | 4 | 5 | 6 | |
177 | 7 | 8 | 9 | |
178 | 10 | 11 | 12 | |
179 +-----+-----+-------+------+
180
181OTHER METHODS
182 clone()
183 The clone() method returns an identical copy of a
184 Text::TabularDisplay instance, completely separate from the cloned
185 instance.
186
187 items()
188 The items() method returns the number of elements currently stored
189 in the data structure:
190
191 printf "There are %d elements in \$t.\n", $t->items;
192
193 reset()
194 Reset deletes the data from the instance, including columns. If
195 passed arguments, it passes them to columns(), just like new().
196
197 populate()
198 populate() as a special case of add(); populate() expects a
199 reference to an array of references to arrays, such as returned by
200 DBI's selectall_arrayref method:
201
202 $sql = "SELECT " . join(", ", @c) . " FROM mytable";
203 $t->columns(@c);
204 $t->populate($dbh->selectall_arrayref($sql));
205
206 This is for convenience only; the implementation maps this to
207 multiple calls to add().
208
209NOTES / ISSUES
210 Text::TabularDisplay assumes it is handling strings, and does stringy
211 things with the data, like length() and sprintf(). Non-character data
212 can be passed in, of course, but will be treated as strings; this may
213 have ramifications for objects that implement overloading.
214
215 The biggest issue, though, is that this module duplicates a some of the
216 functionality of Data::ShowTable. Of course, Data::ShowTable is a large,
217 complex monolithic tool that does a lot of things, while
218 Text::TabularDisplay is small and fast.
219
220AUTHOR
221 darren chamberlain <darren@cpan.org>
222
223CREDITS
224 The following people have contributed patches, suggestions, tests,
225 feedback, or good karma:
226
227 David N. Blank-Edelman
228 Eric Cholet
229 Ken Youens-Clark
230 Michael Fowler
231 Paul Cameron
232 Prakash Kailasa
233 Slaven Rezic
234 Harlan Lieberman-Berg
235 Patrick Kuijvenhoven
236 Miko O'Sullivan
237
238VERSION
239 This documentation describes "Text::TabularDisplay" version 1.37.
240
241