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

NAME

6       Text::Table::Tiny - generate simple text tables from 2D arrays
7

SYNOPSIS

9        use Text::Table::Tiny 1.02 qw/ generate_table /;
10
11        my $rows = [
12          [qw/ Pokemon     Type     Count /],
13          [qw/ Abra        Psychic      5 /],
14          [qw/ Ekans       Poison     123 /],
15          [qw/ Feraligatr  Water     5678 /],
16        ];
17
18        print generate_table(rows => $rows, header_row => 1), "\n";
19

DESCRIPTION

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
25       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
28       The example shown in the SYNOPSIS generates the following table:
29
30        +------------+---------+-------+
31        | Pokemon    | Type    | Count |
32        +------------+---------+-------+
33        | Abra       | Psychic | 5     |
34        | Ekans      | Poison  | 123   |
35        | Feraligatr | Water   | 5678  |
36        +------------+---------+-------+
37
38       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
42       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
46       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
49   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
55       If you pass an unknown argument, "generate_table" will die with an
56       error message.
57
58       •   rows
59
60           Takes an array reference which should contain one or more rows of
61           data, where each row is an array reference.
62
63       •   header_row
64
65           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
69       •   separate_rows
70
71           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
75       •   top_and_tail
76
77           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
80           Added in 0.04.
81
82       •   align
83
84           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
89           Added in 1.00.
90
91       •   style
92
93           Specifies the format of the output table.  The default is
94           'classic', but other options are 'boxrule' and 'norule'.
95
96           If you use the "boxrule" style, you'll probably need to run
97           "binmode(STDOUT, ':utf8')".
98
99           Added in 1.00.
100
101       •   indent
102
103           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
107           Added in 1.00.
108
109       •   compact
110
111           If set to a true value then we omit the single space padding on
112           either side of every column.
113
114           Added in 1.00.
115
116   EXAMPLES
117       If you just pass the data and no other options:
118
119        generate_table(rows => $rows);
120
121       You get minimal ruling:
122
123        +------------+---------+-------+
124        | Pokemon    | Type    | Count |
125        | Abra       | Psychic | 5     |
126        | Ekans      | Poison  | 123   |
127        | Feraligatr | Water   | 5678  |
128        +------------+---------+-------+
129
130       If you want a separate header, set the header_row option to a true
131       value, as shown in the SYNOPSIS.
132
133       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
136        generate_table(rows => $rows, header_row => 1, top_and_tail => 1);
137
138       This will generate the following:
139
140        | Pokemon    | Type    | Count |
141        +------------+---------+-------+
142        | Abra       | Psychic | 5     |
143        | Ekans      | Poison  | 123   |
144        | Feraligatr | Water   | 5678  |
145
146       If you want a more stylish looking table, set the "style" parameter to
147       'boxrule':
148
149        binmode(STDOUT,':utf8');
150        generate_table(rows => $rows, header_row => 1, style => 'boxrule');
151
152       This uses the ANSI box rule characters.  Note that you will need to
153       ensure UTF output.
154
155        ┌────────────┬─────────┬───────┐
156        │ Pokemon    │ Type    │ Count │
157        ├────────────┼─────────┼───────┤
158        │ Abra       │ Psychic │ 5     │
159        │ Ekans      │ Poison  │ 123   │
160        │ Feraligatr │ Water   │ 5678  │
161        └────────────┴─────────┴───────┘
162
163       You might want to right-align numeric values:
164
165        generate_table( ... , align => [qw/ l l r /] );
166
167       The "align" parameter can either take an arrayref, or a string with an
168       alignment to apply to all columns:
169
170        ┌────────────┬─────────┬───────┐
171        │ Pokemon    │ Type    │ Count │
172        ├────────────┼─────────┼───────┤
173        │ Abra       │ Psychic │     5 │
174        │ Ekans      │ Poison  │   123 │
175        │ Feraligatr │ Water   │  5678 │
176        └────────────┴─────────┴───────┘
177
178       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
182        ┌──────────┬───────┬─────┐
183        │Pokemon   │Type   │Count│
184        ├──────────┼───────┼─────┤
185        │Abra      │Psychic│    5│
186        │Ekans     │Poison │  123│
187        │Feraligatr│Water  │ 5678│
188        └──────────┴───────┴─────┘
189
190       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
194        generate_table( ... , separate_rows => 1 );
195
196       Which results in the following:
197
198        ┌────────────┬─────────┬───────┐
199        │ Pokemon    │ Type    │ Count │
200        ╞════════════╪═════════╪═══════╡
201        │ Abra       │ Psychic │     5 │
202        ├────────────┼─────────┼───────┤
203        │ Ekans      │ Poison  │   123 │
204        ├────────────┼─────────┼───────┤
205        │ Feraligatr │ Water   │  5678 │
206        └────────────┴─────────┴───────┘
207
208       You can use this with the other styles, but I'm not sure you'd want to.
209
210       If you just want columnar output, use the "norule" style:
211
212        generate_table( ... , style => 'norule' );
213
214       which results in:
215
216         Pokemon      Type      Count
217
218         Abra         Psychic       5
219         Ekans        Poison      123
220         Feraligatr   Water      5678
221
222       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

SEE ALSO

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

REPOSITORY

237       <https://github.com/neilb/Text-Table-Tiny>
238

AUTHOR

240       Neil Bowers <neilb@cpan.org>
241
242       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
249       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.
251
252
253
254perl v5.32.1                      2021-01-27              Text::Table::Tiny(3)
Impressum