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

NAME

6       Term::Table - Format a header and rows into a table
7

DESCRIPTION

9       This is used by some failing tests to provide diagnostics about what
10       has gone wrong. This module is able to generic format rows of data into
11       tables.
12

SYNOPSIS

14           use Term::Table;
15
16           my $table = Term::Table->new(
17               max_width      => 80,    # defaults to terminal size
18               pad            => 4,     # Extra padding between table and max-width (defaults to 4)
19               allow_overflow => 0,     # default is 0, when off an exception will be thrown if the table is too big
20               collapse       => 1,     # do not show empty columns
21
22               header => ['name', 'age', 'hair color'],
23               rows   => [
24                   ['Fred Flinstone',  2000000, 'black'],
25                   ['Wilma Flinstone', 1999995, 'red'],
26                   ...
27               ],
28           );
29
30           say $_ for $table->render;
31
32       This prints a table like this:
33
34           +-----------------+---------+------------+
35           | name            | age     | hair color |
36           +-----------------+---------+------------+
37           | Fred Flinstone  | 2000000 | black      |
38           | Wilma Flinstone | 1999995 | red        |
39           | ...             | ...     | ...        |
40           +-----------------+---------+------------+
41

INTERFACE

43           use Term::Table;
44           my $table = Term::Table->new(...);
45
46   OPTIONS
47       header => [ ... ]
48           If you want a header specify it here. This takes an arrayref with
49           each columns heading.
50
51       rows => [ [...], [...], ... ]
52           This should be an arrayref containing an arrayref per row.
53
54       collapse => $bool
55           Use this if you want to hide empty columns, that is any column that
56           has no data in any row. Having a header for the column will not
57           effect collapse.
58
59       max_width => $num
60           Set the maximum width of the table, the table may not be this big,
61           but it will be no bigger. If none is specified it will attempt to
62           find the width of your terminal and use that, otherwise it falls
63           back to the terminal width or 80.
64
65       pad => $num
66           Defaults to 4, extra padding for row width calculations. Default is
67           for legacy support. Set this to 0 to turn padding off.
68
69       allow_overflow => $bool
70           Defaults to 0. If this is off then an exception will be thrown if
71           the table cannot be made to fit inside the max-width. If this is
72           set to 1 then the table will be rendered anyway, larger than max-
73           width, if it is not possible to stay within the max-width. In other
74           words this turns max-width from a hard-limit to a soft
75           recommendation.
76
77       sanitize => $bool
78           This will sanitize all the data in the table such that newlines,
79           control characters, and all whitespace except for ASCII 20 ' ' are
80           replaced with escape sequences. This prevents newlines, tabs, and
81           similar whitespace from disrupting the table.
82
83           Note: newlines are marked as '\n', but a newline is also inserted
84           into the data so that it typically displays in a way that is useful
85           to humans.
86
87           Example:
88
89               my $field = "foo\nbar\nbaz\n";
90
91               print join "\n" => table(
92                   sanitize => 1,
93                   rows => [
94                       [$field,      'col2'     ],
95                       ['row2 col1', 'row2 col2']
96                   ]
97               );
98
99           Prints:
100
101               +-----------------+-----------+
102               | foo\n           | col2      |
103               | bar\n           |           |
104               | baz\n           |           |
105               |                 |           |
106               | row2 col1       | row2 col2 |
107               +-----------------+-----------+
108
109           So it marks the newlines by inserting the escape sequence, but it
110           also shows the data across as many lines as it would normally
111           display.
112
113       mark_tail => $bool
114           This will replace the last whitespace character of any trailing
115           whitespace with its escape sequence. This makes it easier to notice
116           trailing whitespace when comparing values.
117
118       show_header => $bool
119           Set this to false to hide the header. This defaults to true if the
120           header is set, false if no header is provided.
121
122       auto_columns => $bool
123           Set this to true to automatically add columns that are not named in
124           the header.  This defaults to false if a header is provided, and
125           defaults to true when there is no header.
126
127       no_collapse => [ $col_num_a, $col_num_b, ... ]
128       no_collapse => [ $col_name_a, $col_name_b, ... ]
129       no_collapse => { $col_num_a => 1, $col_num_b => 1, ... }
130       no_collapse => { $col_name_a => 1, $col_name_b => 1, ... }
131           Specify (by number and/or name) columns that should not be removed
132           when empty.  The 'name' form only works when a header is specified.
133           There is currently no protection to insure that names you specify
134           are actually in the header, invalid names are ignored, patches to
135           fix this will be happily accepted.
136

NOTE ON UNICODE/WIDE CHARACTERS

138       Some unicode characters, such as "婧" ("U+5A67") are wider than others.
139       These will render just fine if you "use utf8;" as necessary, and
140       Unicode::GCString is installed, however if the module is not installed
141       there will be anomalies in the table:
142
143           +-----+-----+---+
144           | a   | b   | c |
145           +-----+-----+---+
146           | 婧 | x   | y |
147           | x   | y   | z |
148           | x   | 婧 | z |
149           +-----+-----+---+
150

SOURCE

152       The source code repository for Term-Table can be found at
153       http://github.com/exodist/Term-Table/.
154

MAINTAINERS

156       Chad Granum <exodist@cpan.org>
157

AUTHORS

159       Chad Granum <exodist@cpan.org>
160
162       Copyright 2016 Chad Granum <exodist@cpan.org>.
163
164       This program is free software; you can redistribute it and/or modify it
165       under the same terms as Perl itself.
166
167       See http://dev.perl.org/licenses/
168
169
170
171perl v5.30.1                      2020-01-30                    Term::Table(3)
Impressum