NAME

Text::Table::Any - Generate text table using one of several backends

VERSION

This document describes version 0.111 of Text::Table::Any (from Perl distribution Text-Table-Any), released on 2022-01-23.

SYNOPSIS

 use Text::Table::Any qw/generate_table/;

 my $rows = [
     # first element is header row
     ['Distribution', 'Author', 'First Version', 'Latest Version', 'Abstract'],

     # subsequent elements are data rows
     ['ACME-Dzil-Test-daemon', 'DAEMON', '0.001', '0.001', 'Module abstract placeholder text'],
     ['ACME-Dzil-Test-daemon2', 'DAEMON', '0.001', '0.001', 'Module abstract placeholder text'],
     ['Acme-CPANModules-ShellCompleters', 'PERLANCAR', '0.001', '0.001', 'Modules that provide shell tab completion for other commands/scripts'],
     ['Acme-CPANModules-WorkingWithURL', 'PERLANCAR', '0.001', '0.001', 'Working with URL'],
 ];

 print generate_table(rows => $rows);

will render the table using the default backend Text::Table::Sprintf and print something like:

 +----------------------------------+-----------+---------------+----------------+----------------------------------------------------------------------+
 | Distribution                     | Author    | First Version | Latest Version | Abstract                                                             |
 +----------------------------------+-----------+---------------+----------------+----------------------------------------------------------------------+
 | ACME-Dzil-Test-daemon            | DAEMON    | 0.001         | 0.001          | Module abstract placeholder text                                     |
 | ACME-Dzil-Test-daemon2           | DAEMON    | 0.001         | 0.001          | Module abstract placeholder text                                     |
 | Acme-CPANModules-ShellCompleters | PERLANCAR | 0.001         | 0.001          | Modules that provide shell tab completion for other commands/scripts |
 | Acme-CPANModules-WorkingWithURL  | PERLANCAR | 0.001         | 0.001          | Working with URL                                                     |
 +----------------------------------+-----------+---------------+----------------+----------------------------------------------------------------------+

To pick another backend:

 print generate_table(
     rows => $rows,
     backend => "Text::Table::Org",
 );

The result is something like:

 | Distribution                     | Author    | First Version | Latest Version | Abstract                                                             |
 |----------------------------------+-----------+---------------+----------------+----------------------------------------------------------------------|
 | ACME-Dzil-Test-daemon            | DAEMON    | 0.001         | 0.001          | Module abstract placeholder text                                     |
 | ACME-Dzil-Test-daemon2           | DAEMON    | 0.001         | 0.001          | Module abstract placeholder text                                     |
 | Acme-CPANModules-ShellCompleters | PERLANCAR | 0.001         | 0.001          | Modules that provide shell tab completion for other commands/scripts |
 | Acme-CPANModules-WorkingWithURL  | PERLANCAR | 0.001         | 0.001          | Working with URL                                                     |

To specify some other options:

 print generate_table(
     rows => $rows,
     header_row => 0,   # default is true
     separate_row => 1, # default is false
     caption => "Some of the new distributions released in Jan 2022",
     backend => "Text::Table::Org",
 );

The result is something like:

 #+CAPTION: Some of the new distributions released in Jan 2022
 | Distribution                     | Author    | First Version | Latest Version | Abstract                                                             |
 |----------------------------------+-----------+---------------+----------------+----------------------------------------------------------------------|
 | ACME-Dzil-Test-daemon            | DAEMON    | 0.001         | 0.001          | Module abstract placeholder text                                     |
 |----------------------------------+-----------+---------------+----------------+----------------------------------------------------------------------|
 | ACME-Dzil-Test-daemon2           | DAEMON    | 0.001         | 0.001          | Module abstract placeholder text                                     |
 |----------------------------------+-----------+---------------+----------------+----------------------------------------------------------------------|
 | Acme-CPANModules-ShellCompleters | PERLANCAR | 0.001         | 0.001          | Modules that provide shell tab completion for other commands/scripts |
 |----------------------------------+-----------+---------------+----------------+----------------------------------------------------------------------|
 | Acme-CPANModules-WorkingWithURL  | PERLANCAR | 0.001         | 0.001          | Working with URL                                                     |

To pass backend-specific options:

 print generate_table(
     rows => $rows,
     backend => "Text::Table::More",
     backend_opts => {
         border_style => 'ASCII::SingleLineDoubleAfterHeader',
         align => 'right',
         row_attrs => [
             [0, {align=>'middle'}],
         ],
     },
 );

The result is something like:

 .----------------------------------+-----------+---------------+----------------+----------------------------------------------------------------------.
 |           Distribution           |  Author   | First Version | Latest Version |                               Abstract                               |
 +==================================+===========+===============+================+======================================================================+
 |            ACME-Dzil-Test-daemon |    DAEMON |         0.001 |          0.001 |                                     Module abstract placeholder text |
 |           ACME-Dzil-Test-daemon2 |    DAEMON |         0.001 |          0.001 |                                     Module abstract placeholder text |
 | Acme-CPANModules-ShellCompleters | PERLANCAR |         0.001 |          0.001 | Modules that provide shell tab completion for other commands/scripts |
 |  Acme-CPANModules-WorkingWithURL | PERLANCAR |         0.001 |          0.001 |                                                     Working with URL |
 `----------------------------------+-----------+---------------+----------------+----------------------------------------------------------------------'

DESCRIPTION

This module provides a single function, "generate_table", which formats a two-dimensional array of data as text table, using one of several available backends. The interface is modelled after Text::Table::Tiny, but Text::Table::Sprintf is the default backend and although Text::Table::Tiny is among the supported backends, it is not required by this module.

DIFFERENCES WITH TEXT::TABLE::TINY

'top_and_tail' option from Text::Table::Tiny is not supported
Probably won't be supported. You can pass this option to Text::Table::Tiny backend via "backend_opts" option.
'align' option from Text::Table::Tiny is not supported
Will be supported in the future.
'style' option from Text::Table::Tiny is not supported
Won't be supported because this is specific to Text::Table::Tiny. If you want custom border styles, here are some alternative backends you can use: Text::Table::TinyBorderStyle, Text::Table::More, Text::UnicodeBox::Table.
'indent' option from Text::Table::Tiny is not supported
Probably won't be supported. You can indent a multiline string in Perl using something like:
```
 $rendered_table =~ s/^/  /mg; # indent each line with two spaces
    
```
'compact' option from Text::Table::Tiny is not supported
May be supported in the future.

VARIABLES

@BACKENDS

List of supported backends.

%BACKEND_FEATURES

List of features supported by each backend. Hash key is backend name, e.g. "Text::Table::Sprintf". Hash value is a hashref containing feature name as hashref key and a boolean value or other value as hashref value to describe the support of that feature by that backend.

FUNCTIONS

table

An old name for "generate_table" function ("generate_table()" was not available in Text::Table::Tiny < 0.04). This name is not available for export.

generate_table

Exportable.

Usage:

 table(%params) => str

Except for the "backend" parameter, the parameters will mostly be passed to the backend, sometimes slightly modified if necessary to achieve the desired effect. If a parameter is not supported by a backend, then it will not be passed to the backend.

Known parameters:

•: backend
Optional. Str, default "Text::Table::Sprintf". Pick a backend module. Supported backends:

Term::Table
Term::TablePrint
Text::ANSITable
Text::ASCIITable
Text::FormatTable
Text::MarkdownTable
Text::Table
Text::Table::ASV
Text::Table::CSV
Text::Table::HTML
Text::Table::HTML::DataTables
Text::Table::LTSV
Text::Table::Manifold
Text::Table::More
Text::Table::Org
Text::Table::Paragraph
Text::Table::Sprintf
Text::Table::TSV
Text::Table::TickitWidget
Text::Table::Tiny
Text::Table::TinyBorderStyle
Text::Table::TinyColor
Text::Table::TinyColorWide
Text::Table::TinyWide
Text::Table::XLSX
Text::TabularDisplay
Text::UnicodeBox::Table

Support matrix for each backend:

 +-------------------------------+--------------+------------------------------------------------------------------------------------------------+---------+------------+------+---------------+
 | backend                       | backend_opts | backend_opts_note                                                                              | caption | header_row | rows | separate_rows |
 +-------------------------------+--------------+------------------------------------------------------------------------------------------------+---------+------------+------+---------------+
 | Term::Table                   |              |                                                                                                | 0       | 1          | 1    | 0             |
 | Term::TablePrint              |              |                                                                                                | 0       | 1          | 1    | 0             |
 | Text::ANSITable               |              |                                                                                                | 0       | 1          | 1    | 1             |
 | Text::ASCIITable              |              |                                                                                                | 0       | 1          | 1    | 0             |
 | Text::FormatTable             |              |                                                                                                | 0       | 0          | 1    | 0             |
 | Text::MarkdownTable           |              |                                                                                                | 0       | 1          | 1    | 0             |
 | Text::Table                   |              |                                                                                                | 0       | 0          | 1    | 0             |
 | Text::Table::ASV              | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 0             |
 | Text::Table::CSV              | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 0             |
 | Text::Table::HTML             | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 1       | 1          | 1    | 0             |
 | Text::Table::HTML::DataTables | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 1       | 1          | 1    | 0             |
 | Text::Table::LTSV             | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 0          | 1    | 0             |
 | Text::Table::Manifold         |              |                                                                                                | 0       | 1          | 1    | 0             |
 | Text::Table::More             | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 1             |
 | Text::Table::Org              | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 1             |
 | Text::Table::Paragraph        | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 0             |
 | Text::Table::Sprintf          | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 1             |
 | Text::Table::TSV              | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 0          | 1    | 0             |
 | Text::Table::TickitWidget     | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 0             |
 | Text::Table::Tiny             | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 1             |
 | Text::Table::TinyBorderStyle  | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 1             |
 | Text::Table::TinyColor        | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 1             |
 | Text::Table::TinyColorWide    | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 1             |
 | Text::Table::TinyWide         | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 1             |
 | Text::Table::XLSX             | 1            | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0       | 1          | 1    | 0             |
 | Text::TabularDisplay          |              |                                                                                                | 0       | 0          | 1    | 0             |
 | Text::UnicodeBox::Table       |              |                                                                                                | 0       | 1          | 1    | 0             |
 +-------------------------------+--------------+------------------------------------------------------------------------------------------------+---------+------------+------+---------------+

rows
Required. Aoaos (array of array-of-scalars). Each element in the array is a row of data, where each row is an array reference.
header_row
Optional. Bool, default is true. If given a true value, the first row in the data will be interpreted as a header row, and separated visually from the rest of the table (e.g. with a ruled line). But some backends won't display differently.
separate_rows
Boolean. Optional. Default is false. If set to true, will draw a separator line after each data row.

Not all backends support this.
caption
Optional. Str. Caption of the table.
backend_opts
Optional. Hashref. Pass backend-specific options to the backend module. Not all backend modules support this, but all backend modules that have interface following "Text::Table::Tiny" should support this. Also note that as the list of common options is expanded, a previously backend-specific option might be available later as a common option.

backends

Return list of supported backends. You can also get the list from the "@BACKENDS" package variable.

HOMEPAGE

Please visit the project's homepage at <https://metacpan.org/release/Text-Table-Any>.

SOURCE

Source repository is at <https://github.com/perlancar/perl-Text-Table-Any>.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

 % prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

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

BUGS

Please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Public/Dist/Display.html?Name=Text-Table-Any>

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.