1Text::Table::Tiny(3) User Contributed Perl Documentation Text::Table::Tiny(3)
2
6 Text::Table::Tiny - generate simple text tables from 2D arrays
7
9 use Text::Table::Tiny 1.02 qw/ generate_table /;
10 my $rows = [
12 [qw/ Pokemon Type Count /],
13 [qw/ Abra Psychic 5 /],
14 [qw/ Ekans Poison 123 /],
15 [qw/ Feraligatr Water 5678 /],
16 ];
17 print generate_table(rows => $rows, header_row => 1), "\n";
19
21 This module provides a single function, "generate_table", which formats
22 a two-dimensional array of data as a text table. It handles text that
23 includes ANSI escape codes and wide Unicode characters.
24 There are a number of options for adjusting the output format, but the
26 intention is that the default option is good enough for most uses.
27 The example shown in the SYNOPSIS generates the following table:
29 +------------+---------+-------+
31 | Pokemon | Type | Count |
32 +------------+---------+-------+
33 | Abra | Psychic | 5 |
34 | Ekans | Poison | 123 |
35 | Feraligatr | Water | 5678 |
36 +------------+---------+-------+
37 Support for wide characters was added in 1.02, so if you need that, you
39 should specify that as your minimum required version, as per the
40 SYNOPSIS.
41 The interface changed with version 0.04, so if you use the
43 "generate_table()" function illustrated above, then you need to require
44 at least version 0.04 of this module.
45 Some of the options described below were added in version 1.00, so your
47 best bet is to require at least version 1.00.
48 generate_table()
50 The "generate_table" function understands a number of arguments, which
51 are passed as a hash. The only required argument is rows. Where
52 arguments were not supported in the original release, the first
53 supporting version is noted.
54 If you pass an unknown argument, "generate_table" will die with an
56 error message.
57 • rows
59 Takes an array reference which should contain one or more rows of
61 data, where each row is an array reference.
62 • header_row
64 If given a true value, the first row in the data will be
66 interpreted as a header row, and separated from the rest of the
67 table with a ruled line.
68 • header
70 Takes an array reference which has the header row to use for the
72 table. You can't use this option together with "header_row".
73 Added in 1.03
75 • separate_rows
77 If given a true value, a separator line will be drawn between every
79 row in the table, and a thicker line will be used for the header
80 separator.
81 • top_and_tail
83 If given a true value, then the top and bottom border lines will be
85 skipped. This reduces the vertical height of the generated table.
86 Added in 0.04.
88 • align
90 This takes an array ref with one entry per column, to specify the
92 alignment of that column. Legal values are 'l', 'c', and 'r'. You
93 can also specify a single alignment for all columns. ANSI escape
94 codes are handled.
95 Added in 1.00.
97 • style
99 Specifies the format of the output table. The default is
101 'classic', but other options are 'boxrule' and 'norule'.
102 If you use the "boxrule" style, you'll probably need to run
104 "binmode(STDOUT, ':utf8')".
105 Added in 1.00.
107 • indent
109 Specify an indent that should be prefixed to every line of the
111 generated table. This can either be a string of spaces, or an
112 integer giving the number of spaces wanted.
113 Added in 1.00.
115 • compact
117 If set to a true value then we omit the single space padding on
119 either side of every column.
120 Added in 1.00.
122 EXAMPLES
124 If you just pass the data and no other options:
125 generate_table(rows => $rows);
127 You get minimal ruling:
129 +------------+---------+-------+
131 | Pokemon | Type | Count |
132 | Abra | Psychic | 5 |
133 | Ekans | Poison | 123 |
134 | Feraligatr | Water | 5678 |
135 +------------+---------+-------+
136 If you want a separate header, set the header_row option to a true
138 value, as shown in the SYNOPSIS.
139 To take up fewer lines, you can miss out the top and bottom rules, by
141 setting "top_and_tail" to a true value:
142 generate_table(rows => $rows, header_row => 1, top_and_tail => 1);
144 This will generate the following:
146 | Pokemon | Type | Count |
148 +------------+---------+-------+
149 | Abra | Psychic | 5 |
150 | Ekans | Poison | 123 |
151 | Feraligatr | Water | 5678 |
152 If you want a more stylish looking table, set the "style" parameter to
154 'boxrule':
155 binmode(STDOUT,':utf8');
157 generate_table(rows => $rows, header_row => 1, style => 'boxrule');
158 This uses the ANSI box rule characters. Note that you will need to
160 ensure UTF output.
161 ┌────────────┬─────────┬───────┐
163 │ Pokemon │ Type │ Count │
164 ├────────────┼─────────┼───────┤
165 │ Abra │ Psychic │ 5 │
166 │ Ekans │ Poison │ 123 │
167 │ Feraligatr │ Water │ 5678 │
168 └────────────┴─────────┴───────┘
169 You might want to right-align numeric values:
171 generate_table( ... , align => [qw/ l l r /] );
173 The "align" parameter can either take an arrayref, or a string with an
175 alignment to apply to all columns:
176 ┌────────────┬─────────┬───────┐
178 │ Pokemon │ Type │ Count │
179 ├────────────┼─────────┼───────┤
180 │ Abra │ Psychic │ 5 │
181 │ Ekans │ Poison │ 123 │
182 │ Feraligatr │ Water │ 5678 │
183 └────────────┴─────────┴───────┘
184 If you're using the boxrule style, you might feel you can remove the
186 padding on either side of every column, done by setting "compact" to a
187 true value:
188 ┌──────────┬───────┬─────┐
190 │Pokemon │Type │Count│
191 ├──────────┼───────┼─────┤
192 │Abra │Psychic│ 5│
193 │Ekans │Poison │ 123│
194 │Feraligatr│Water │ 5678│
195 └──────────┴───────┴─────┘
196 You can also ask for a rule between each row, in which case the header
198 rule becomes stronger. This works best when combined with the boxrule
199 style:
200 generate_table( ... , separate_rows => 1 );
202 Which results in the following:
204 ┌────────────┬─────────┬───────┐
206 │ Pokemon │ Type │ Count │
207 ╞════════════╪═════════╪═══════╡
208 │ Abra │ Psychic │ 5 │
209 ├────────────┼─────────┼───────┤
210 │ Ekans │ Poison │ 123 │
211 ├────────────┼─────────┼───────┤
212 │ Feraligatr │ Water │ 5678 │
213 └────────────┴─────────┴───────┘
214 You can use this with the other styles, but I'm not sure you'd want to.
216 If you just want columnar output, use the "norule" style:
218 generate_table( ... , style => 'norule' );
220 which results in:
222 Pokemon Type Count
224 Abra Psychic 5
226 Ekans Poison 123
227 Feraligatr Water 5678
228 Note that everywhere you saw a line on the previous tables, there will
230 be a space character in this version. So you may want to combine the
231 "top_and_tail" option, to suppress the extra blank lines before and
232 after the body of the table.
233
235 My blog post <http://neilb.org/2019/08/06/text-table-tiny-changes.html>
236 where I described changes to formatting; this has more examples.
237 There are many modules for formatting text tables on CPAN. A good
239 number of them are listed in the See Also
240 <https://metacpan.org/pod/Text::Table::Manifold#See-Also> section of
241 the documentation for Text::Table::Manifold.
242
244 <https://github.com/neilb/Text-Table-Tiny>
245
247 Neil Bowers <neilb@cpan.org>
248 The original version was written by Creighton Higgins
250 <chiggins@chiggins.com>, but the module was entirely rewritten for
251 0.05_01.
252
254 This software is copyright (c) 2020 by Neil Bowers.
255 This is free software; you can redistribute it and/or modify it under
257 the same terms as the Perl 5 programming language system itself.
258perl v5.36.0 2022-07-22 Text::Table::Tiny(3)