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 • separate_rows
70 If given a true value, a separator line will be drawn between every
72 row in the table, and a thicker line will be used for the header
73 separator.
74 • top_and_tail
76 If given a true value, then the top and bottom border lines will be
78 skipped. This reduces the vertical height of the generated table.
79 Added in 0.04.
81 • align
83 This takes an array ref with one entry per column, to specify the
85 alignment of that column. Legal values are 'l', 'c', and 'r'. You
86 can also specify a single alignment for all columns. ANSI escape
87 codes are handled.
88 Added in 1.00.
90 • style
92 Specifies the format of the output table. The default is
94 'classic', but other options are 'boxrule' and 'norule'.
95 If you use the "boxrule" style, you'll probably need to run
97 "binmode(STDOUT, ':utf8')".
98 Added in 1.00.
100 • indent
102 Specify an indent that should be prefixed to every line of the
104 generated table. This can either be a string of spaces, or an
105 integer giving the number of spaces wanted.
106 Added in 1.00.
108 • compact
110 If set to a true value then we omit the single space padding on
112 either side of every column.
113 Added in 1.00.
115 EXAMPLES
117 If you just pass the data and no other options:
118 generate_table(rows => $rows);
120 You get minimal ruling:
122 +------------+---------+-------+
124 | Pokemon | Type | Count |
125 | Abra | Psychic | 5 |
126 | Ekans | Poison | 123 |
127 | Feraligatr | Water | 5678 |
128 +------------+---------+-------+
129 If you want a separate header, set the header_row option to a true
131 value, as shown in the SYNOPSIS.
132 To take up fewer lines, you can miss out the top and bottom rules, by
134 setting "top_and_tail" to a true value:
135 generate_table(rows => $rows, header_row => 1, top_and_tail => 1);
137 This will generate the following:
139 | Pokemon | Type | Count |
141 +------------+---------+-------+
142 | Abra | Psychic | 5 |
143 | Ekans | Poison | 123 |
144 | Feraligatr | Water | 5678 |
145 If you want a more stylish looking table, set the "style" parameter to
147 'boxrule':
148 binmode(STDOUT,':utf8');
150 generate_table(rows => $rows, header_row => 1, style => 'boxrule');
151 This uses the ANSI box rule characters. Note that you will need to
153 ensure UTF output.
154 ┌────────────┬─────────┬───────┐
156 │ Pokemon │ Type │ Count │
157 ├────────────┼─────────┼───────┤
158 │ Abra │ Psychic │ 5 │
159 │ Ekans │ Poison │ 123 │
160 │ Feraligatr │ Water │ 5678 │
161 └────────────┴─────────┴───────┘
162 You might want to right-align numeric values:
164 generate_table( ... , align => [qw/ l l r /] );
166 The "align" parameter can either take an arrayref, or a string with an
168 alignment to apply to all columns:
169 ┌────────────┬─────────┬───────┐
171 │ Pokemon │ Type │ Count │
172 ├────────────┼─────────┼───────┤
173 │ Abra │ Psychic │ 5 │
174 │ Ekans │ Poison │ 123 │
175 │ Feraligatr │ Water │ 5678 │
176 └────────────┴─────────┴───────┘
177 If you're using the boxrule style, you might feel you can remove the
179 padding on either side of every column, done by setting "compact" to a
180 true value:
181 ┌──────────┬───────┬─────┐
183 │Pokemon │Type │Count│
184 ├──────────┼───────┼─────┤
185 │Abra │Psychic│ 5│
186 │Ekans │Poison │ 123│
187 │Feraligatr│Water │ 5678│
188 └──────────┴───────┴─────┘
189 You can also ask for a rule between each row, in which case the header
191 rule becomes stronger. This works best when combined with the boxrule
192 style:
193 generate_table( ... , separate_rows => 1 );
195 Which results in the following:
197 ┌────────────┬─────────┬───────┐
199 │ Pokemon │ Type │ Count │
200 ╞════════════╪═════════╪═══════╡
201 │ Abra │ Psychic │ 5 │
202 ├────────────┼─────────┼───────┤
203 │ Ekans │ Poison │ 123 │
204 ├────────────┼─────────┼───────┤
205 │ Feraligatr │ Water │ 5678 │
206 └────────────┴─────────┴───────┘
207 You can use this with the other styles, but I'm not sure you'd want to.
209 If you just want columnar output, use the "norule" style:
211 generate_table( ... , style => 'norule' );
213 which results in:
215 Pokemon Type Count
217 Abra Psychic 5
219 Ekans Poison 123
220 Feraligatr Water 5678
221 Note that everywhere you saw a line on the previous tables, there will
223 be a space character in this version. So you may want to combine the
224 "top_and_tail" option, to suppress the extra blank lines before and
225 after the body of the table.
226
228 My blog post <http://neilb.org/2019/08/06/text-table-tiny-changes.html>
229 where I described changes to formatting; this has more examples.
230 There are many modules for formatting text tables on CPAN. A good
232 number of them are listed in the See Also
233 <https://metacpan.org/pod/Text::Table::Manifold#See-Also> section of
234 the documentation for Text::Table::Manifold.
235
237 <https://github.com/neilb/Text-Table-Tiny>
238
240 Neil Bowers <neilb@cpan.org>
241 The original version was written by Creighton Higgins
243 <chiggins@chiggins.com>, but the module was entirely rewritten for
244 0.05_01.
245
247 This software is copyright (c) 2020 by Neil Bowers.
248 This is free software; you can redistribute it and/or modify it under
250 the same terms as the Perl 5 programming language system itself.
251perl v5.34.0 2022-01-21 Text::Table::Tiny(3)