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

VERSION
    This document describes version 0.116 of Text::Table::Any (from Perl
    distribution Text-Table-Any), released on 2023-11-11.

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

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

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

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

COPYRIGHT AND LICENSE
    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.

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.

