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

SEE ALSO
    Acme::CPANModules::TextTable

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 software is copyright (c) 2022, 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.

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.

