1Text::Table(3) User Contributed Perl Documentation Text::Table(3)
2
6 Text::Table - Organize Data in Tables
7
9 version 1.133
10
12 use Text::Table;
13 my $tb = Text::Table->new(
14 "Planet", "Radius\nkm", "Density\ng/cm^3"
15 );
16 $tb->load(
17 [ "Mercury", 2360, 3.7 ],
18 [ "Venus", 6110, 5.1 ],
19 [ "Earth", 6378, 5.52 ],
20 [ "Jupiter", 71030, 1.3 ],
21 );
22 print $tb;
23 This prints a table from the given title and data like this:
25 Planet Radius Density
27 km g/cm^3
28 Mercury 2360 3.7
29 Venus 6110 5.1
30 Earth 6378 5.52
31 Jupiter 71030 1.3
32 Note that two-line titles work, and that the planet names are aligned
34 differently than the numbers.
35
37 Organization of data in table form is a time-honored and useful method
38 of data representation. While columns of data are trivially generated
39 by computer through formatted output, even simple tasks like keeping
40 titles aligned with the data columns are not trivial, and the one-shot
41 solutions one comes up with tend to be particularly hard to maintain.
42 Text::Table allows you to create and maintain tables that adapt to
43 alignment requirements as you use them.
44 Overview
46 The process is simple: you create a table (a Text::Table object) by
47 describing the columns the table is going to have. Then you load lines
48 of data into the table, and finally print the resulting output lines.
49 Alignment of data and column titles is handled dynamically in
50 dependence on the data present.
51 Table Creation
53 In the simplest case, if all you want is a number of (untitled)
54 columns, you create an unspecified table and start adding data to it.
55 The number of columns is taken from the first line of data.
56 To specify a table you specify its columns. A column description can
58 contain a title and alignment requirements for the data, both optional.
59 Additionally, you can specify how the title is aligned with the body of
60 a column, and how the lines of a multiline title are aligned among
61 themselves.
62 The columns are collected in the table in the order they are given. On
64 data entry, each column corresponds to one data item, and in column
65 selection columns are indexed left to right, starting from 0.
66 Each title can be a multiline string which will be blank-filled to the
68 length of the longest partial line. The largest number of title lines
69 in a column determines how many title lines the table has as a whole,
70 including the case that no column has any titles.
71 On output, columns are separated by a single blank. You can control
73 what goes between columns by specifying separators between (or before,
74 or after) columns. Separators don't contain any data and don't count
75 in column indexing. They also don't accumulate: in a sequence of only
76 separators and no columns, only the last one counts.
77 Status Information
79 The width (in characters), height (in lines), number of columns, and
80 similar data about the table is available.
81 Data Loading
83 Table data is entered line-wise, each time specifying data entries for
84 all table columns. A bulk loader for many lines at once is also
85 available. You can clear the data from the table for re-use (though
86 you will more likely just create another table).
87 Data can contain colorizing escape sequences (as provided by
89 "Term::AnsiColor") without upsetting the alignment.
90 Table Output
92 The output area of a table is divided in the title and the body.
93 The title contains the combined titles from the table columns, if any.
95 Its content never changes with a given table, but it may be spread out
96 differently on the page through alignment with the data.
97 The body contains the data lines, aligned column-wise as specified, and
99 left-aligned with the column title.
100 Each of these is arranged like a Perl array (counting from 0) and can
102 be accessed in portions by specifying a first line and the number of
103 following lines. Also like an array, giving a negative first line
104 counts from the end of the area. The whole table, the title followed
105 by the body, can also be accessed in this manner.
106 The subdivisions are there so you can repeat the title (or parts of it)
108 along with parts of the body on output, whether for screen paging or
109 printout.
110 A rule line is also available, which is the horizontal counterpart to
112 the separator columns you specify with the table. It is basically a
113 table line as it would appear if all data entries in the line were
114 empty, that is, a blank line except for where the column separators
115 have non-blank entries. If you print it between data lines, it will
116 not disrupt the vertical separator structure as a plain blank line
117 would. You can also request a solid rule consisting of any character,
118 and even one with the non-blank column separators replaced by a
119 character of your choice. This way you can get the popular
120 representation of line-crossings like so:
121 |
123 ----+---
124 |
125 Warning Control
127 On table creation, some parameters are checked and warnings issued if
128 you allow warnings. You can also turn warnings into fatal errors.
129
131 Column Specification
132 Each column specification is a single scalar. Columns can be either
133 proper data columns or column separators. Both can be specified either
134 as (possibly multi-line) strings, or in a more explicit form as hash-
135 refs. In the string form, proper columns are given as plain strings,
136 and separators are given as scalar references to strings. In hash
137 form, separators have a true value in the field "is_sep" while proper
138 columns don't have this field.
139 Columns as strings
141 A column is given as a column title (any number of lines),
142 optionally followed by alignment requirements. Alignment
143 requirements start with a line that begins with an ampersand "&".
144 However, only the last such line counts as such, so if you have
145 title lines that begin with "&", just append an ampersand on a line
146 by itself as a dummy alignment section if you don't have one
147 anyway.
148 What follows the ampersand on its line is the alignment style (like
150 left, right, ... as described in "Alignment"), you want for the
151 data in this column. If nothing follows, the general default auto
152 is used. If you specify an invalid alignment style, it falls back
153 to left alignment.
154 The lines that follow can contain sample data for this column.
156 These are considered for alignment in the column, but never
157 actually appear in the output. The effect is to guarantee a
158 minimum width for the column even if the current data doesn't
159 require it. This helps dampen the oscillations in the appearance
160 of dynamically aligned tables.
161 Columns as Hashes
163 The format is
164 {
166 title => $title,
167 align => $align,
168 sample => $sample,
169 align_title => $align_title,
170 align_title_lines => $align_title_lines,
171 }
172 $title contains the title lines and $sample the sample data. Both
174 can be given as a string or as an array-ref to the list of lines.
175 $align contains the alignment style (without a leading ampersand),
176 usually as a string. You can also give a regular expression here,
177 which specifies regex alignment. A regex can only be specified in
178 the hash form of a column specification.
179 In hash form you can also specify how the title of a column is
181 aligned with its body. To do this, you specify the keyword
182 "align_title" with "left", "right" or "center". Other alignment
183 specifications are not valid here. The default is "left".
184 "align_title" also specifies how the lines of a multiline title are
186 aligned among themselves. If you want a different alignment, you
187 can specify it with the key "align_title_lines". Again, only
188 "left", "right" or "center" are allowed.
189 Do not put other keys than those mentioned above (title, align,
191 align_title, align_title_lines, and sample) into a hash that
192 specifies a column. Most would be ignored, but some would confuse
193 the interpreter (in particular, is_sep has to be avoided).
194 Separators as strings
196 A separator must be given as a reference to a string (often a
197 literal, like "\' | '"), any string that is given directly
198 describes a column.
199 It is usually just a (short) string that will be printed between
201 table columns on all table lines instead of the default single
202 blank. If you specify two separators (on two lines), the first one
203 will be used in the title and the other in the body of the table.
204 Separators as Hashes
206 The hash representation of a separator has the format
207 {
209 is_sep => 1,
210 title => $title,
211 body => $body,
212 }
213 $title is the separator to be used in the title area and $body the
215 one for the body. If only one is given, it will be used for both.
216 If none is given, a blank is used. If one is shorter than the
217 other, it is blank filled on the right.
218 The value of "is_sep" must be set to a true value, this is the
220 distinguishing feature of a separator.
221 Alignment
223 The original documentation to Text::Aligner contains all the details on
224 alignment specification, but here is the rundown:
225 The possible alignment specifications are left, right, center, num and
227 point (which are synonyms), and auto. The first three explain
228 themselves.
229 num (and point) align the decimal point in the data, which is assumed
231 to the right if none is present. Strings that aren't numbers are
232 treated the same way, that is, they appear aligned with the integers
233 unless they contain a ".". Instead of the decimal point ".", you can
234 also specify any other string in the form num(,), for instance. The
235 string in parentheses is aligned in the data. The synonym point for
236 num may be more appropriate in contexts that deal with arbitrary
237 strings, as in point(=>) (which might be used to align certain bits of
238 Perl code).
239 regex alignment is a more sophisticated form of point alignment. If
241 you specify a regular expression, as delivered by "qr//", the start of
242 the match is used as the alignment point. If the regex contains
243 capturing parentheses, the last submatch counts. [The usefulness of
244 this feature is under consideration.]
245 auto alignment combines numeric alignment with left alignment. Data
247 items that look like numbers, and those that don't, form two virtual
248 columns and are aligned accordingly: "num" for numbers and "left" for
249 other strings. These columns are left-aligned with each other (i.e.
250 the narrower one is blank-filled) to form the final alignment.
251 This way, a column that happens to have only numbers in the data gets
253 num alignment, a column with no numbers appears left-aligned, and mixed
254 data is presented in a reasonable way.
255 Column Selection
257 Besides creating tables from scratch, they can be created by selecting
258 columns from an existing table. Tables created this way contain the
259 data from the columns they were built from.
260 This is done by specifying the columns to select by their index (where
262 negative indices count backward from the last column). The same column
263 can be selected more than once and the sequence of columns can be
264 arbitrarily changed. Separators don't travel with columns, but can be
265 specified between the columns at selection time.
266 You can make the selection of one or more columns dependent on the data
268 content of one of them. If you specify some of the columns in angle
269 brackets [...], the whole group is only included in the selection if
270 the first column in the group contains any data that evaluates to
271 boolean true. That way you can de-select parts of a table if it
272 contains no interesting data. Any column separators given in brackets
273 are selected or deselected along with the rest of it.
274
276 Table Creation
277 new()
278 my $tb = Text::Table->new( $column, ... );
279 creates a table with the columns specified. A column can be proper
281 column which contains and displays data, or a separator which tells
282 how to fill the space between columns. The format of the
283 parameters is described under "Column Specification". Specifying an
284 invalid alignment for a column results in a warning if these are
285 allowed.
286 If no columns are specified, the number of columns is taken from
288 the first line of data added to the table. The effect is as if you
289 had specified "Text::Table->new( ( '') x $n)", where $n is the
290 number of columns.
291 select()
293 my $sub = $tb->select( $column, ...);
294 creates a table from the listed columns of the table $tb, including
296 the data. Columns are specified as integer indices which refer to
297 the data columns of $tb. Columns can be repeated and specified in
298 any order. Negative indices count from the last column. If an
299 invalid index is specified, a warning is issued, if allowed.
300 As with "new()", separators can be interspersed among the column
302 indices and will be used between the columns of the new table.
303 If you enclose some of the arguments (column indices or separators)
305 in angle brackets "[...]" (technically, you specify them inside an
306 arrayref), they form a group for conditional selection. The group
307 is only included in the resulting table if the first actual column
308 inside the group contains any data that evaluate to a boolean true.
309 This way you can exclude groups of columns that wouldn't contribute
310 anything interesting. Note that separators are selected and de-
311 selected with their group. That way, more than one separator can
312 appear between adjacent columns. They don't add up, but only the
313 rightmost separator is used. A group that contains only separators
314 is never selected. [Another feature whose usefulness is under
315 consideration.]
316 Status Information
318 n_cols()
319 $tb->n_cols
320 returns the number of columns in the table.
322 width()
324 $tb->width
325 returns the width (in characters) of the table. All table lines
327 have this length (not counting a final "\n" in the line), as well
328 as the separator lines returned by $tb->rule() and $b->body_rule().
329 The width of a table can potentially be influenced by any data item
330 in it.
331 height()
333 $tb->height
334 returns the total number of lines in a table, including title lines
336 and body lines. For orthogonality, the synonym table_height() also
337 exists.
338 table_height()
340 Same as "$table->height()".
341 title_height()
343 $tb->title_height
344 returns the number of title lines in a table.
346 body_height()
348 $tb->body_height
349 returns the number of lines in the table body.
351 colrange()
353 $tb->colrange( $i)
354 returns the start position and width of the $i-th column (counting
356 from 0) of the table. If $i is negative, counts from the end of
357 the table. If $i is larger than the greatest column index, an
358 imaginary column of width 0 is assumed right of the table.
359 Data Loading
361 add()
362 $tb->add( $col1, ..., $colN)
363 adds a data line to the table, returns the table.
365 $col1, ..., $colN are scalars that correspond to the table columns.
367 Undefined entries are converted to '', and extra data beyond the
368 number of table columns is ignored.
369 Data entries can be multi-line strings. The partial strings all go
371 into the same column. The corresponding fields of other columns
372 remain empty unless there is another multi-line entry in that
373 column that fills the fields. Adding a line with multi-line
374 entries is equivalent to adding multiple lines.
375 Every call to "add()" increases the body height of the table by the
377 number of effective lines, one in the absence of multiline entries.
378 load()
380 $tb->load( $line, ...)
381 loads the data lines given into the table, returns the table.
383 Every argument to "load()" represents a data line to be added to
385 the table. The line can be given as an array(ref) containing the
386 data items, or as a string, which is split on whitespace to
387 retrieve the data. If an undefined argument is given, it is
388 treated as an empty line.
389 clear()
391 $tb->clear;
392 deletes all data from the table and resets it to the state after
394 creation. Returns the table. The body height of a table is 0
395 after "clear()".
396 Table Output
398 The three methods "table()", "title()", and "body()" are very similar.
399 They access different parts of the printable output lines of a table
400 with similar methods. The details are described with the "table()"
401 method.
402 table()
404 The "table()" method returns lines from the entire table, starting
405 with the first title line and ending with the last body line.
406 In array context, the lines are returned separately, in scalar
408 context they are joined together in a single string.
409 my @lines = $tb->table;
411 my $line = $tb->table( $line_number);
412 my @lines = $tb->table( $line_number, $n);
413 The first call returns all the lines in the table. The second call
415 returns one line given by $line_number. The third call returns $n
416 lines, starting with $line_number. If $line_number is negative, it
417 counts from the end of the array. Unlike the "select()" method,
418 "table()" (and its sister methods "title()" and "body()") is
419 protected against large negative line numbers, it truncates the
420 range described by $line_number and $n to the existing lines. If
421 $n is 0 or negative, no lines are returned (an empty string in
422 scalar context).
423 stringify()
425 Returns a string representation of the table. This method is called
426 for stringification by overload.
427 my @table_strings = map { $_->stringify() } @tables;
429 title()
431 Returns lines from the title area of a table, where the column
432 titles are rendered. Parameters and response to context are as
433 with "table()", but no lines are returned from outside the title
434 area.
435 body()
437 Returns lines from the body area of a table, that is the part where
438 the data content is rendered, so that $tb->body( 0) is the first
439 data line. Parameters and response to context are as with
440 "table()".
441 rule()
443 $tb->rule;
444 $tb->rule( $char);
445 $tb->rule( $char, $char1);
446 $tb->rule( sub { my ($index, $len) = @_; },
447 sub { my ($index, $len) = @_; },
448 );
449 Returns a rule for the table.
451 A rule is a line of table width that can be used between table
453 lines to provide visual horizontal divisions, much like column
454 separators provide vertical visual divisions. In its basic form
455 (returned by the first call) it looks like a table line with no
456 data, hence a blank line except for the non-blank parts of any
457 column-separators. If one character is specified (the second
458 call), it replaces the blanks in the first form, but non-blank
459 column separators are retained. If a second character is
460 specified, it replaces the non-blank parts of the separators. So
461 specifying the same character twice gives a solid line of table
462 width. Another useful combo is "$tb->rule( '-', '+')", together
463 with separators that contain a single nonblank "|", for a popular
464 representation of line crossings.
465 "rule()" uses the column separators for the title section if there
467 is a difference.
468 If callbacks are specified instead of the characters, then they
470 receive the index of the section of the rule they need to render
471 and its desired length in characters, and should return the string
472 to put there. The indexes given are 0 based (where 0 is either the
473 left column separator or the leftmost cell) and the strings will be
474 trimmed or extended in the replacement.
475 body_rule()
477 "body_rule()" works like <rule()>, except the rule is generated
478 using the column separators for the table body.
479 Warning Control
481 warnings()
482 Text::Table->warnings();
483 Text::Table->warnings( 'on');
484 Text::Table->warnings( 'off'):
485 Text::Table->warnings( 'fatal'):
486 The "warnings()" method is used to control the appearance of
488 warning messages while tables are manipulated. When Text::Table
489 starts, warnings are disabled. The default action of "warnings()"
490 is to turn warnings on. The other possible arguments are self-
491 explanatory. "warnings()" can also be called as an object method
492 ("$tb->warnings( ...)").
493
495 This document pertains to Text::Table version 1.127
496
498 o auto alignment doesn't support alternative characters for the
499 decimal point. This is actually a bug in the underlying
500 Text::Aligner by the same author.
501
503 MAINTAINER
504 Shlomi Fish, <http://www.shlomifish.org/> - CPAN ID: "SHLOMIF".
505 ORIGINAL AUTHOR
507 Anno Siegel
508 CPAN ID: ANNO
509 siegel@zrz.tu-berlin.de
510 http://www.tu-berlin.de/~siegel
511
513 Copyright (c) 2002 Anno Siegel. All rights reserved. This program is
514 free software; you can redistribute it and/or modify it under the terms
515 of the ISC license.
516 (This program had been licensed under the same terms as Perl itself up
518 to version 1.118 released on 2011, and was relicensed by permission of
519 its originator).
520 The full text of the license can be found in the LICENSE file included
522 with this module.
523
525 Text::Aligner, perl(1) .
526
528 Shlomi Fish <shlomif@cpan.org>
529
531 This software is Copyright (c) 2002 by Anno Siegel and others.
532 This is free software, licensed under:
534 The ISC License
536
538 Please report any bugs or feature requests on the bugtracker website
539 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Text-Table> or by email to
540 bug-text-table@rt.cpan.org <mailto:bug-text-table@rt.cpan.org>.
541 When submitting a bug or request, please include a test-file or a patch
543 to an existing test-file that illustrates the bug or desired feature.
544
546 Perldoc
547 You can find documentation for this module with the perldoc command.
548 perldoc Text::Table
550 Websites
552 The following websites have more information about this module, and may
553 be of help to you. As always, in addition to those websites please use
554 your favorite search engine to discover more resources.
555 · MetaCPAN
557 A modern, open-source CPAN search engine, useful to view POD in
559 HTML format.
560 <http://metacpan.org/release/Text-Table>
562 · Search CPAN
564 The default CPAN search engine, useful to view POD in HTML format.
566 <http://search.cpan.org/dist/Text-Table>
568 · RT: CPAN's Bug Tracker
570 The RT ( Request Tracker ) website is the default bug/issue
572 tracking system for CPAN.
573 <https://rt.cpan.org/Public/Dist/Display.html?Name=Text-Table>
575 · AnnoCPAN
577 The AnnoCPAN is a website that allows community annotations of Perl
579 module documentation.
580 <http://annocpan.org/dist/Text-Table>
582 · CPAN Ratings
584 The CPAN Ratings is a website that allows community ratings and
586 reviews of Perl modules.
587 <http://cpanratings.perl.org/d/Text-Table>
589 · CPAN Forum
591 The CPAN Forum is a web forum for discussing Perl modules.
593 <http://cpanforum.com/dist/Text-Table>
595 · CPANTS
597 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
599 of a distribution.
600 <http://cpants.cpanauthors.org/dist/Text-Table>
602 · CPAN Testers
604 The CPAN Testers is a network of smokers who run automated tests on
606 uploaded CPAN distributions.
607 <http://www.cpantesters.org/distro/T/Text-Table>
609 · CPAN Testers Matrix
611 The CPAN Testers Matrix is a website that provides a visual
613 overview of the test results for a distribution on various
614 Perls/platforms.
615 <http://matrix.cpantesters.org/?dist=Text-Table>
617 · CPAN Testers Dependencies
619 The CPAN Testers Dependencies is a website that shows a chart of
621 the test results of all dependencies for a distribution.
622 <http://deps.cpantesters.org/?module=Text::Table>
624 Bugs / Feature Requests
626 Please report any bugs or feature requests by email to "bug-text-table
627 at rt.cpan.org", or through the web interface at
628 <https://rt.cpan.org/Public/Bug/Report.html?Queue=Text-Table>. You will
629 be automatically notified of any progress on the request by the system.
630 Source Code
632 The code is open to the world, and available for you to hack on. Please
633 feel free to browse it and play with it, or whatever. If you want to
634 contribute patches, please send me a diff or prod me to pull from your
635 repository :)
636 <https://github.com/shlomif/Text-Table>
638 git clone ssh://git@github.com:shlomif/Text-Table.git
640perl v5.30.1 2020-01-30 Text::Table(3)