1Text::Table(3)        User Contributed Perl Documentation       Text::Table(3)
2
3
4

NAME

6       Text::Table - Organize Data in Tables
7

VERSION

9       version 1.133
10

SYNOPSIS

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
24       This prints a table from the given title and data like this:
25
26         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
33       Note that two-line titles work, and that the planet names are aligned
34       differently than the numbers.
35

DESCRIPTION

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
45   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
52   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
57       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
63       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
67       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
72       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
78   Status Information
79       The width (in characters), height (in lines), number of columns, and
80       similar data about the table is available.
81
82   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
88       Data can contain colorizing escape sequences (as provided by
89       "Term::AnsiColor") without upsetting the alignment.
90
91   Table Output
92       The output area of a table is divided in the title and the body.
93
94       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
98       The body contains the data lines, aligned column-wise as specified, and
99       left-aligned with the column title.
100
101       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
107       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
111       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
122             |
123         ----+---
124             |
125
126   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

SPECIFICATIONS

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
140       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
149           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
155           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
162       Columns as Hashes
163           The format is
164
165               {
166                   title   => $title,
167                   align   => $align,
168                   sample  => $sample,
169                   align_title => $align_title,
170                   align_title_lines => $align_title_lines,
171               }
172
173           $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
180           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
185           "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
190           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
195       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
200           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
205       Separators as Hashes
206           The hash representation of a separator has the format
207
208               {
209                   is_sep => 1,
210                   title  => $title,
211                   body   => $body,
212               }
213
214           $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
219           The value of "is_sep" must be set to a true value, this is the
220           distinguishing feature of a separator.
221
222   Alignment
223       The original documentation to Text::Aligner contains all the details on
224       alignment specification, but here is the rundown:
225
226       The possible alignment specifications are left, right, center, num and
227       point (which are synonyms), and auto.  The first three explain
228       themselves.
229
230       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
240       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
246       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
252       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
256   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
261       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
267       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

PUBLIC METHODS

276   Table Creation
277       new()
278               my $tb = Text::Table->new( $column, ... );
279
280           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
287           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
292       select()
293               my $sub = $tb->select( $column, ...);
294
295           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
301           As with "new()", separators can be interspersed among the column
302           indices and will be used between the columns of the new table.
303
304           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
317   Status Information
318       n_cols()
319               $tb->n_cols
320
321           returns the number of columns in the table.
322
323       width()
324               $tb->width
325
326           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
332       height()
333               $tb->height
334
335           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
339       table_height()
340           Same as "$table->height()".
341
342       title_height()
343               $tb->title_height
344
345           returns the number of title lines in a table.
346
347       body_height()
348               $tb->body_height
349
350           returns the number of lines in the table body.
351
352       colrange()
353               $tb->colrange( $i)
354
355           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
360   Data Loading
361       add()
362               $tb->add( $col1, ..., $colN)
363
364           adds a data line to the table, returns the table.
365
366           $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
370           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
376           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
379       load()
380               $tb->load( $line, ...)
381
382           loads the data lines given into the table, returns the table.
383
384           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
390       clear()
391               $tb->clear;
392
393           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
397   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
403       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
407           In array context, the lines are returned separately, in scalar
408           context they are joined together in a single string.
409
410               my @lines = $tb->table;
411               my $line  = $tb->table( $line_number);
412               my @lines = $tb->table( $line_number, $n);
413
414           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
424       stringify()
425           Returns a string representation of the table. This method is called
426           for stringification by overload.
427
428               my @table_strings = map { $_->stringify() } @tables;
429
430       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
436       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
442       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
450           Returns a rule for the table.
451
452           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
466           "rule()" uses the column separators for the title section if there
467           is a difference.
468
469           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
476       body_rule()
477           "body_rule()" works like <rule()>, except the rule is generated
478           using the column separators for the table body.
479
480   Warning Control
481       warnings()
482               Text::Table->warnings();
483               Text::Table->warnings( 'on');
484               Text::Table->warnings( 'off'):
485               Text::Table->warnings( 'fatal'):
486
487           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

VERSION

495       This document pertains to Text::Table version 1.127
496

BUGS

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

AUTHOR

503   MAINTAINER
504       Shlomi Fish, <http://www.shlomifish.org/> - CPAN ID: "SHLOMIF".
505
506   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
517       (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
521       The full text of the license can be found in the LICENSE file included
522       with this module.
523

SEE ALSO

525       Text::Aligner, perl(1) .
526

AUTHOR

528       Shlomi Fish <shlomif@cpan.org>
529
531       This software is Copyright (c) 2002 by Anno Siegel and others.
532
533       This is free software, licensed under:
534
535         The ISC License
536

BUGS

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
542       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

SUPPORT

546   Perldoc
547       You can find documentation for this module with the perldoc command.
548
549         perldoc Text::Table
550
551   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
556       ·   MetaCPAN
557
558           A modern, open-source CPAN search engine, useful to view POD in
559           HTML format.
560
561           <http://metacpan.org/release/Text-Table>
562
563       ·   Search CPAN
564
565           The default CPAN search engine, useful to view POD in HTML format.
566
567           <http://search.cpan.org/dist/Text-Table>
568
569       ·   RT: CPAN's Bug Tracker
570
571           The RT ( Request Tracker ) website is the default bug/issue
572           tracking system for CPAN.
573
574           <https://rt.cpan.org/Public/Dist/Display.html?Name=Text-Table>
575
576       ·   AnnoCPAN
577
578           The AnnoCPAN is a website that allows community annotations of Perl
579           module documentation.
580
581           <http://annocpan.org/dist/Text-Table>
582
583       ·   CPAN Ratings
584
585           The CPAN Ratings is a website that allows community ratings and
586           reviews of Perl modules.
587
588           <http://cpanratings.perl.org/d/Text-Table>
589
590       ·   CPAN Forum
591
592           The CPAN Forum is a web forum for discussing Perl modules.
593
594           <http://cpanforum.com/dist/Text-Table>
595
596       ·   CPANTS
597
598           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
599           of a distribution.
600
601           <http://cpants.cpanauthors.org/dist/Text-Table>
602
603       ·   CPAN Testers
604
605           The CPAN Testers is a network of smokers who run automated tests on
606           uploaded CPAN distributions.
607
608           <http://www.cpantesters.org/distro/T/Text-Table>
609
610       ·   CPAN Testers Matrix
611
612           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
616           <http://matrix.cpantesters.org/?dist=Text-Table>
617
618       ·   CPAN Testers Dependencies
619
620           The CPAN Testers Dependencies is a website that shows a chart of
621           the test results of all dependencies for a distribution.
622
623           <http://deps.cpantesters.org/?module=Text::Table>
624
625   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
631   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
637       <https://github.com/shlomif/Text-Table>
638
639         git clone ssh://git@github.com:shlomif/Text-Table.git
640
641
642
643perl v5.28.1                      2019-02-02                    Text::Table(3)
Impressum