NAME

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

SYNOPSIS

 use Text::Table::Tiny 0.04 qw/ generate_table /;

 my $rows = [
   [qw/ Pokemon     Type     Count /],
   [qw/ Abra        Psychic      5 /],
   [qw/ Ekans       Poison     123 /],
   [qw/ Feraligatr  Water     5678 /],
 ];

 print generate_table(rows => $rows, header_row => 1), "\n";

DESCRIPTION

This module provides a single function, generate_table, which formats a two-dimensional array of data as a text table. There are a number of options for adjusting the output format, but the intention is that the default option is good enough for most uses.

The example shown in the SYNOPSIS generates the following table:

 +------------+---------+-------+
 | Pokemon    | Type    | Count |
 +------------+---------+-------+
 | Abra       | Psychic | 5     |
 | Ekans      | Poison  | 123   |
 | Feraligatr | Water   | 5678  |
 +------------+---------+-------+

NOTE: the interface changed with version 0.04, so if you use the generate_table() function illustrated above, then you need to require at least version 0.04 of this module, as shown in the SYNOPSIS.

generate_table()

The generate_table function understands a number of arguments, which are passed as a hash. The only required argument is rows.

• rows

  Takes an array reference which should contain one or more rows of data, where each row is an array reference.

• header_row

  If given a true value, the first row in the data will be interpreted as a header row, and separated from the rest of the table with a ruled line.

• separate_rows

  If given a true value, a separator line will be drawn between every row in the table, and a thicker line will be used for the header separator.

• top_and_tail

  If given a true value, then the top and bottom border lines will be skipped. This reduces the vertical height of the generated table.

• align

  This takes an array ref with one entry per column, to specify the alignment of that column. Legal values are 'l', 'c', and 'r'. You can also specify a single alignment for all columns. ANSI escape codes are handled.

• style

  Specifies the format of the output table. The default is 'classic', but other options are 'boxrule' and 'norule'.

  If you use the boxrule style, you'll probably need to run binmode(STDOUT, ':utf8').

• compact

  If set to a true value then we omit the single space padding on either side of every column.

EXAMPLES

If you just pass the data and no other options:

 generate_table(rows => $rows);

You get minimal ruling:

 +------------+---------+-------+
 | Pokemon    | Type    | Count |
 | Abra       | Psychic | 5     |
 | Ekans      | Poison  | 123   |
 | Feraligatr | Water   | 5678  |
 +------------+---------+-------+

If you want a separate header, set the header_row option to a true value, as shown in the SYNOPSIS.

To take up fewer lines, you can miss out the top and bottom rules, by setting top_and_tail to a true value:

 generate_table(rows => $rows, header_row => 1, top_and_tail => 1);

This will generate the following:

 | Pokemon    | Type    | Count |
 +------------+---------+-------+
 | Abra       | Psychic | 5     |
 | Ekans      | Poison  | 123   |
 | Feraligatr | Water   | 5678  |

If you want a more stylish looking table, set the style parameter to 'boxrule':

 binmode(STDOUT,':utf8');
 generate_table(rows => $rows, header_row => 1, style => 'boxrule');

This uses the ANSI box rule characters. Note that you will need to ensure UTF output.

 ┌────────────┬─────────┬───────┐
 │ Pokemon    │ Type    │ Count │
 ├────────────┼─────────┼───────┤
 │ Abra       │ Psychic │ 5     │
 │ Ekans      │ Poison  │ 123   │
 │ Feraligatr │ Water   │ 5678  │
 └────────────┴─────────┴───────┘

You might want to right-align numeric values:

 generate_table(rows => $rows, header_row => 1, style => 'boxrule', align => [qw/ l l r /]);

The align parameter can either take an arrayref, or a string with an alignment to apply to all columns:

 ┌────────────┬─────────┬───────┐
 │ Pokemon    │ Type    │ Count │
 ├────────────┼─────────┼───────┤
 │ Abra       │ Psychic │     5 │
 │ Ekans      │ Poison  │   123 │
 │ Feraligatr │ Water   │  5678 │
 └────────────┴─────────┴───────┘

If you're using the boxrule style, you might feel you can remove the padding on either side of every column, done by setting compact to a true value:

 ┌──────────┬───────┬─────┐
 │Pokemon   │Type   │Count│
 ├──────────┼───────┼─────┤
 │Abra      │Psychic│    5│
 │Ekans     │Poison │  123│
 │Feraligatr│Water  │ 5678│
 └──────────┴───────┴─────┘
 

If you just want columnar output, use the norule style:

 generate_table( rows => $rows, style => 'norule', header_row => 1, align => [qw/ l l r/]);

which results in:

  Pokemon      Type      Count
  
  Abra         Psychic       5
  Ekans        Poison      123
  Feraligatr   Water      5678
   

Note that everywhere you saw a line on the previous tables, there will be a space character in this version. So you may want to combine the top_and_tail option, to suppress the extra blank lines before and after the body of the table.

SEE ALSO

My blog post where I described changes to formatting; this has more examples.

There are many modules for formatting text tables on CPAN. A good number of them are listed in the See Also section of the documentation for Text::Table::Manifold.

REPOSITORY

https://github.com/neilb/Text-Table-Tiny

AUTHOR

Neil Bowers <neilb@cpan.org>

The original version was written by Creighton Higgins <chiggins@chiggins.com>, but the module was entirely rewritten for 0.05_01.

COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by Neil Bowers.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Text::Table::Tiny

perl -MCPAN -e shell
install Text::Table::Tiny