1Text::Table(3) User Contributed Perl Documentation Text::Table(3)
2
6 Text::Table - Organize Data in Tables
7
9 use Text::Table;
10 my $tb = Text::Table->new(
11 "Planet", "Radius\nkm", "Density\ng/cm^3"
12 );
13 $tb->load(
14 [ "Mercury", 2360, 3.7 ],
15 [ "Venus", 6110, 5.1 ],
16 [ "Earth", 6378, 5.52 ],
17 [ "Jupiter", 71030, 1.3 ],
18 );
19 print $tb;
20 This prints a table from the given title and data like this:
22 Planet Radius Density
24 km g/cm^3
25 Mercury 2360 3.7
26 Venus 6110 5.1
27 Earth 6378 5.52
28 Jupiter 71030 1.3
29 Note that two-line titles work, and that the planet names are aligned
31 differently than the numbers.
32
34 Organization of data in table form is a time-honored and useful method
35 of data representation. While columns of data are trivially generated
36 by computer through formatted output, even simple tasks like keeping
37 titles aligned with the data columns are not trivial, and the one-shot
38 solutions one comes up with tend to be particularly hard to maintain.
39 Text::Table allows you to create and maintain tables that adapt to
40 alignment requirements as you use them.
41 Overview
43 The process is simple: you create a table (a Text::Table object) by
44 describing the columns the table is going to have. Then you load lines
45 of data into the table, and finally print the resulting output lines.
46 Alignment of data and column titles is handled dynamically in
47 dependence on the data present.
48 Table Creation
50 In the simplest case, if all you want is a number of (untitled)
51 columns, you create an unspecified table and start adding data to it.
52 The number of columns is taken fronm the first line of data.
53 To specify a table you specify its columns. A column description can
55 contain a title and alignment requirements for the data, both optional.
56 Additionally, you can specify how the title is aligned with the body of
57 a column, and how the lines of a multiline title are aligned among
58 themselves.
59 The columns are collected in the table in the order they are given. On
61 data entry, each column corresponds to one data item, and in column
62 selection columns are indexed left to right, starting from 0.
63 Each title can be a multiline string which will be blank-filled to the
65 length of the longest partial line. The largest number of title lines
66 in a column determines how many title lines the table has as a whole,
67 including the case that no column has any titles.
68 On output, Columns are separated by a single blank. You can control
70 what goes between columns by specifying separators between (or before,
71 or after) columns. Separators don't contain any data and don't count
72 in column indexing. They also don't accumulate: in a sequence of only
73 separators and no columns, only the last one counts.
74 Status Information
76 The width (in characters), height (in lines), number of columns, and
77 similar data about the table is available.
78 Data Loading
80 Table data is entered line-wise, each time specifying data entries for
81 all table columns. A bulk loader for many lines at once is also
82 available. You can clear the data from the table for re-use (though
83 you will more likely just create another table).
84 Table Output
86 The output area of a table is divided in the title and the body.
87 The title contains the combined titles from the table columns, if any.
89 Its content never changes with a given table, but it may be spread out
90 differently on the page through alignment with the data.
91 The body contains the data lines, aligned column-wise as specified, and
93 left-aligned with the column title.
94 Each of these is arranged like a Perl array (counting from 0) and can
96 be accessed in portions by specifying a first line and the number of
97 following lines. Also like an array, giving a negative first line
98 counts from the end of the area. The whole table, the title followed
99 by the body, can also be accessed in this manner.
100 The subdivisions are there so you can repeat the title (or parts of it)
102 along with parts of the body on output, whether for screen paging or
103 printout.
104 A rule line is also available, which is the horizontal counterpart to
106 the separator columns you specify with the table. It is basically a
107 table line as it would appear if all data entries in the line were
108 empty, that is, a blank line except for where the column separators
109 have non-blank entries. If you print it between data lines, it will
110 not disrupt the vertical separator structure as a plain blank line
111 would. You can also request a solid rule consisting of any character,
112 and even one with the non-blank column separators replaced by a
113 character of your choice. This way you can get the popular
114 representation of line-crossings like so:
115 |
117 ----+---
118 |
119 Warning Control
121 On table creation, some parameters are checked and warnings issued if
122 you allow warnings. You can also turn warnings into fatal errors.
123
125 Column Specification
126 Each column specification is a single scalar. Columns can be either
127 proper data columns or column separators. Both can be specified either
128 as (possibly multi-line) strings, or in a more explicit form as hash-
129 refs. In the string form, proper columns are given as plain strings,
130 and separators are given as scalar references to strings. In hash
131 form, separators have a true value in the field "is_sep" while proper
132 columns don't have this field.
133 Columns as strings
135 A column is given as a column title (any number of lines),
136 optionally followed by alignment requirements. Alignment
137 requirements start with a line that begins with an ampersamd "&".
138 However, only the last such line counts as such, so if you have
139 title lines that begin with "&", just append an ampersand on a line
140 by itself as a dummy alignment section if you don't have one
141 anyway.
142 What follows the ampersand on its line is the alignment style (like
144 left, right, ... as described in "Alignment"), you want for the
145 data in this column. If nothing follows, the general default auto
146 is used. If you specify an invalid alignment style, it falls back
147 to left alignment.
148 The lines that follow can contain sample data for this column.
150 These are considered for alignment in the column, but never
151 actually appear in the output. The effect is to guarantee a
152 minimum width for the column even if the current data doesn't
153 require it. This helps dampen the oscillations in the appearance
154 of dynamically aligned tables.
155 Columns as Hashes
157 The format is
158 {
160 title => $title,
161 align => $align,
162 sample => $sample,
163 align_title => $align_title,
164 align_title_lines => $align_title_lines,
165 }
166 $title contains the title lines and $sample the sample data. Both
168 can be given as a string or as an array-ref to the list of lines.
169 $align contains the alignment style (without a leading ampersand),
170 usually as a string. You can also give a regular expression here,
171 which specifies regex alignment. A regex can only be specified in
172 the hash form of a colunm specification.
173 In hash form you can also specify how the title of a column is
175 aligned with its body. To do this, you specify the keyword
176 "align_title" with "left", "right" or "center". Other alignment
177 specifications are not valid here. The default is "left".
178 "align_title" also specifies how the lines of a multiline title are
180 aligned among themselves. If you want a different alignment, you
181 can specify it with the key "align_title_lines". Again, only
182 "left", "right" or "center" are allowed.
183 Do not put other keys than those mentioned above (title, align,
185 align_title, align_title_lines, and sample) into a hash that
186 specifies a column. Most would be ignored, but some would confuse
187 the interpreter (in particular, is_sep has to be avoided).
188 Separators as strings
190 A separator must be given as a reference to a string (often a
191 literal, like "\' | '"), any string that is given directly
192 describes a column.
193 It is usually just a (short) string that will be printed between
195 table columns on all table lines instead of the default single
196 blank. If you specify two separators (on two lines), the first one
197 will be used in the title and the other in the body of the table.
198 Separators as Hashes
200 The hash representation of a separator has the format
201 {
203 is_sep => 1,
204 title => $title,
205 body => $body,
206 }
207 $title is the separator to be used in the title area and $body the
209 one for the body. If only one is given, the other is used for
210 both. If none is given, a blank is used. If one is shorter than
211 the other, it is blank filled on the right.
212 The value of "is_sep" must be set to a true value, this is the
214 distinguishing feature of a separator.
215 Alignment
217 The original documentation to Text::Aligner contains all the details on
218 alignment specification, but here is the rundown:
219 The possible alignment specifications are left, right, center, num and
221 point (which are synonyms), and auto. The first three explain
222 themselves.
223 num (and point) align the decimal point in the data, which is assumed
225 to the right if none is present. Strings that aren't numbers are
226 treated the same way, that is, they appear aligned with the integers
227 unless they contain a ".". Instead of the decimal point ".", you can
228 also specify any other string in the form num(,), for instance. The
229 string in parentheses is aligned in the data. The synonym point for
230 num may be more appropriate in contexts that deal with arbitrary
231 strings, as in point(=>) (which might be used to align certain bits of
232 Perl code).
233 regex alignment is a more sophisticated form of point alignment. If
235 you specify a regular expression, as delivered by "qr//", the start of
236 the match is used as the alignment point. If the regex contains
237 capturing parentheses, the last submatch counts. [The usefulness of
238 this feature is under consideration.]
239 auto alignment combines numeric alignment with left alignment. Data
241 items that look like numbers, and those that don't, form two virtual
242 columns and are aligned accordingly: "num" for numbers and "left" for
243 other strings. These columns are left-aligned with each other (i.e.
244 the narrower one is blank-filled) to form the final alignment.
245 This way, a column that happens to have only numbers in the data gets
247 num alignment, a column with no numbers appears left-aligned, and mixed
248 data is presented in a reasonable way.
249 Column Selection
251 Besides creating tables from scratch, they can be created by selecting
252 columns from an existing table. Tables created this way contain the
253 data from the columns they were built from.
254 This is done by specifying the columns to select by their index (where
256 negative indices count backward from the last column). The same column
257 can be selected more than once and the sequence of columns can be
258 arbitrarily changed. Separators don't travel with columns, but can be
259 specified between the columns at selection time.
260 You can make the selection of one or more columns dependent on the data
262 content of one of them. If you specify some of the columns in angle
263 brackets [...], the whole group is only included in the selection if
264 the first column in the group contains any data that evaluates to
265 boolean true. That way you can de-select parts of a table if it
266 contains no interesting data. Any column separators given in brackets
267 are selected or deselected along with the rest of it.
268
270 Table Creation
271 new()
272 my $tb = Text::Table->new( $column, ... );
273 creates a table with the columns specified. A column can be proper
275 column which contains and displays data, or a separator which tells
276 how to fill the space between columns. The format of the
277 parameters is described under "Column Specification". Specifying an
278 invalid alignment for a column results in a warning if these are
279 allowed.
280 If no columns are specified, the number of columns is taken from
282 the first line of data added to the table. The effect is as if you
283 had specified "Text::Table->new( ( '') x $n)", where $n is the
284 number of columns.
285 select()
287 my $sub = $tb->select( $column, ...);
288 creates a table from the listed columns of the table $tb, including
290 the data. Columns are specified as integer indices which refer to
291 the data columns of $tb. Columns can be repeated and specified in
292 any order. Negative indices count from the last column. If an
293 invalid index is specified, a warning is issued, if allowed.
294 As with "new()", separators can be interspersed among the column
296 indices and will be used between the columns of the new table.
297 If you enclose some of the arguments (column indices or separators)
299 in angle brackets "[...]" (technically, you specify them inside an
300 arrayref), they form a group for conditional selection. The group
301 is only included in the resulting table if the first actual column
302 inside the group contains any data that evaluate to a boolean true.
303 This way you can exclude groups of columns that wouldn't contribute
304 anything interesting. Note that separators are selected and de-
305 selected with their group. That way, more than one separator can
306 appear between adjacent columns. They don't add up, but only the
307 rightmost separator is used. A group that contains only separators
308 is never selected. [Another feature whose usefulness is under
309 consideration.]
310 Status Information
312 n_cols()
313 $tb->n_cols
314 returns the number of columns in the table.
316 width()
318 $tb->width
319 returns the width (in characters) of the table. All table lines
321 have this length (not counting a final "\n" in the line), as well
322 as the separator lines returned by $tb->rule() and $b->body_rule().
323 The width of a table can potentially be influenced by any data item
324 in it.
325 height()
327 $tb->height
328 returns the total number of lines in a table, including title lines
330 and body lines. For orthogonality, the synonym table_height() also
331 exists.
332 title_height()
334 $tb->title_height
335 returns the number of title lines in a table.
337 body_height()
339 $tb->body_height
340 returns the number of lines in the table body.
342 colrange()
344 $tb->colrange( $i)
345 returns the start position and width of the $i-th column (counting
347 from 0) of the table. If $i is negative, counts from the end of
348 the table. If $i is larger than the greatest column index, an
349 imaginary column of width 0 is assumed right of the table.
350 Data Loading
352 add()
353 $tb->add( $col1, ..., $colN)
354 adds a data line to the table, returns the table.
356 $col1, ..., $colN are scalars that correspond to the table columns.
358 Undefined entries are converted to '', and extra data beyond the
359 number of table columns is ignored.
360 Data entries can be multi-line strings. The partial strings all go
362 into the same column. The corresponding fields of other columns
363 remain empty unless there is another multi-line entry in that
364 column that fills the fieds. Adding a line with multi-line entries
365 is equivalent to adding multiple lines.
366 Every call to "add()" increases the body height of the table by the
368 number of effective lines, one in the absence of multiline entries.
369 load()
371 $tb->load( $line, ...)
372 loads the data lines given into the table, returns the table.
374 Every argument to "load()" represents a data line to be added to
376 the table. The line can be given as an array(ref) containing the
377 data items, or as a string, which is split on whitespace to
378 retrieve the data. If an undefined argument is given, it is
379 treated as an empty line.
380 clear()
382 $tb->clear;
383 deletes all data from the table and resets it to the state after
385 creation. Returns the table. The body height of a table is 0
386 after "clear()".
387 Table Output
389 The three methods "table()", "title()", and "body()" are very similar.
390 They access different parts of the printable output lines of a table
391 with similar methods. The details are described with the "table()"
392 method.
393 table()
395 The "table()" method returns lines from the entire table, starting
396 with the first title line and ending with the last body line.
397 In array context, the lines are returned separately, in scalar
399 context they are joined together in a single string.
400 my @lines = $tb->table;
402 my $line = $tb->table( $line_number);
403 my @lines = $tb->table( $line_number, $n);
404 The first call returns all the lines in the table. The second call
406 returns one line given by $line_number. The third call returns $n
407 lines, starting with $line_number. If $line_number is negative, it
408 counts from the end of the array. Unlike the "select()" method,
409 "table()" (and its sister methods "title()" and "body()") is
410 protected against large negative line numbers, it truncates the
411 range described by $line_number and $n to the existing lines. If
412 $n is 0 or negative, no lines are returned (an empty string in
413 scalar context).
414 title()
416 Returns lines from the title area of a table, where the column
417 titles are rendered. Parameters and response to context are as
418 with "table()", but no lines are returned from outside the title
419 area.
420 body()
422 Returns lines from the body area of a table, that is the part where
423 the data content is rendered, so that $tb->body( 0) is the first
424 data line. Parameters and response to context are as with
425 "table()".
426 rule()
428 $tb->rule;
429 $tb->rule( $char);
430 $tb->rule( $char, $char1);
431 Returns a rule for the table.
433 A rule is a line of table width that can be used between table
435 lines to provide visual horizontal divisions, much like column
436 separators provide vertical visual divisions. In its basic form
437 (returned by the first call) it looks like a table line with no
438 data, hence a blank line except for the non-blank parts of any
439 column-separators. If one character is specified (the second
440 call), it replaces the blanks in the first form, but non-blank
441 column separators are retained. If a second character is
442 specified, it replaces the non-blank parts of the separators. So
443 specifying the same character twice gives a solid line of table
444 width. Another useful combo is "$tb-<rule( '-', '+')", together
445 with separators that contain a single nonblank "|", for a popular
446 representation of line crossings.
447 "rule()" uses the column separators for the title section if there
449 is a difference.
450 body_rule()
452 "body_rule()" works like <rule()>, except the rule is generated
453 using the column separators for the table body.
454 Warning Control
456 warnings()
457 Text::Table->warnings();
458 Text::Table->warnings( 'on');
459 Text::Table->warnings( 'off'):
460 Text::Table->warnings( 'fatal'):
461 The "warnings()" method is used to control the appearance of
463 warning messages while tables are manipulated. When Text::Table
464 starts, warnings are disabled. The default action of "warnings()"
465 is to turn warnings on. The other possible arguments are self-
466 explanatory. "warnings()" can also be called as an object method
467 ("$tb->warnings( ...)").
468
470 This document pertains to Text::Table version 1.107
471
473 o auto alignment doesn't support alternative characters for the
474 decimal point. This is actually a bug in the underlying
475 Text::Aligner by the same author.
476
478 Anno Siegel
479 CPAN ID: ANNO
480 siegel@zrz.tu-berlin.de
481 http://www.tu-berlin.de/~siegel
482
484 Copyright (c) 2002 Anno Siegel. All rights reserved. This program is
485 free software; you can redistribute it and/or modify it under the same
486 terms as Perl itself.
487 The full text of the license can be found in the LICENSE file included
489 with this module.
490
492 Text::Aligner, perl(1).
493perl v5.12.0 2008-05-11 Text::Table(3)