Text::Table::Any - Generate text table using one of several backends
This document describes version 0.117 of Text::Table::Any (from Perl distribution Text-Table-Any), released on 2023-11-11.
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_rows => 1, # default is false caption => "Some of the new distributions released in Jan 2022", backend => "Text::Table::Org", );
#+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'}], ], }, );
.----------------------------------+-----------+---------------+----------------+----------------------------------------------------------------------. | 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 | `----------------------------------+-----------+---------------+----------------+----------------------------------------------------------------------'
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.
generate_table
'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.
'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::ANSITable, 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.
List of supported backends.
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.
Text::Table::Sprintf
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.
backend
Known parameters:
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::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 | align | align_note | backend_opts | backend_opts_note | caption | header_row | rows | separate_rows | +-------------------------------+-------+--------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+---------+------------+------+---------------+ | Term::Table | 0 | | | | 0 | 1 | 1 | 0 | | Term::TablePrint | 0 | | | | 0 | 1 | 1 | 0 | | Text::ANSITable | 1 | | | | 0 | 1 | 1 | 1 | | Text::ASCIITable | 1 | | | | 0 | 1 | 1 | 0 | | Text::FormatTable | 1 | c(enter) alignment is not supported, will fallback to l(eft) | | | 0 | 0 | 1 | 0 | | Text::MarkdownTable | 0 | | | | 0 | 1 | 1 | 0 | | Text::Table | 1 | | | | 0 | 0 | 1 | 0 | | Text::Table::ASV | 0 | | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 1 | 1 | 0 | | Text::Table::CSV | 0 | | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 1 | 1 | 0 | | Text::Table::HTML | 0 | TODO, backend does not support yet, parameter already passed | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 1 | 1 | 1 | 0 | | Text::Table::HTML::DataTables | 0 | TODO, backend does not support yet, parameter already passed | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 1 | 1 | 1 | 0 | | Text::Table::LTSV | 0 | | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 0 | 1 | 0 | | Text::Table::Manifold | 1 | | | | 0 | 1 | 1 | 0 | | Text::Table::More | 1 | | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 1 | 1 | 1 | | Text::Table::Org | 0 | | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 1 | 1 | 1 | 1 | | Text::Table::Paragraph | 0 | | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 1 | 1 | 0 | | Text::Table::Sprintf | 0 | | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 1 | 1 | 1 | | Text::Table::TSV | 0 | | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 0 | 1 | 0 | | Text::Table::TickitWidget | 0 | | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 1 | 1 | 0 | | Text::Table::Tiny | 1 | | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 1 | 1 | 1 | | Text::Table::TinyBorderStyle | 0 | TODO, backend does not support yet, parameter already passed | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 1 | 1 | 1 | | Text::Table::TinyColor | 0 | TODO, backend does not support yet, parameter already passed | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 1 | 1 | 1 | | Text::Table::TinyColorWide | 0 | TODO, backend does not support yet, parameter already passed | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 1 | 1 | 1 | | Text::Table::TinyWide | 0 | TODO, backend does not support yet, parameter already passed | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 1 | 1 | 1 | | Text::Table::XLSX | 0 | | 1 | Backend-specific options (backend_opts) will be passed to table() or generate_table() directly | 0 | 1 | 1 | 0 | | Text::TabularDisplay | 0 | | | | 0 | 0 | 1 | 0 | | Text::UnicodeBox::Table | 0 | TODO: backend supports left/right | | | 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.
align
Optional. Array of Str or Str.
This takes an array ref with one entry per column, to specify the alignment of that column. Legal values are 'l', 'c', and 'r' (for left, center, and right, respectively). You can also specify a single alignment for all columns.
Not all backends support this. For example, Text::Table::Sprintf prior to 0.007 does not support this at all. Starting from 0.007, only support left and right alignment.
Note that some backends like Text::ANSITable and Text::Table::More support per-row or per-cell or even conditional alignment. Some backends like Text::ASCIITable and Text::Table can also align beyond just l(eft), c(enter), r(right), e.g. justify or align on a decimal point. To do more fine-grained alignment setting, you can use the backend_opts parameter.
justify
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.
Return list of supported backends. You can also get the list from the "@BACKENDS" package variable.
Please visit the project's homepage at https://metacpan.org/release/Text-Table-Any.
Source repository is at https://github.com/perlancar/perl-Text-Table-Any.
Acme::CPANModules::TextTable
perlancar <perlancar@cpan.org>
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, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.
This software is copyright (c) 2023, 2022, 2021, 2020, 2019, 2018, 2017, 2016, 2015 by perlancar <perlancar@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
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.
To install Text::Table::Any, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::Table::Any
CPAN shell
perl -MCPAN -e shell install Text::Table::Any
For more information on module installation, please visit the detailed CPAN module installation guide.