NAME
    Text::Table::More - Generate text table with simple interface and many
    options

VERSION
    This document describes version 0.025 of Text::Table::More (from Perl
    distribution Text-Table-More), released on 2022-03-27.

SYNOPSIS
     #!perl
 
     use 5.010001;
     use strict;
     use warnings;
 
     use Text::Table::More qw/generate_table/;
 
     my $rows = [
         # header row
         ["Year",
          "Comedy",
          "Drama",
          "Variety",
          "Lead Comedy Actor",
          "Lead Drama Actor",
          "Lead Comedy Actress",
          "Lead Drama Actress"],
 
         # first data row
         [1962,
          "The Bob Newhart Show (NBC)",
          {text=>"The Defenders (CBS)", rowspan=>3}, # each cell can be hashref to specify text (content) as well as attributes
          "The Garry Moore Show (CBS)",
          {text=>"E. G. Marshall, The Defenders (CBS)", rowspan=>2, colspan=>2},
          {text=>"Shirley Booth, Hazel (NBC)", rowspan=>2, colspan=>2}],
 
         # second data row
         [1963,
          {text=>"The Dick Van Dyke Show (CBS)", rowspan=>2},
          "The Andy Williams Show (NBC)"],
 
         # third data row
         [1964,
          "The Danny Kaye Show (CBS)",
          {text=>"Dick Van Dyke, The Dick Van Dyke Show (CBS)", colspan=>2},
          {text=>"Mary Tyler Moore, The Dick Van Dyke Show (CBS)", colspan=>2}],
 
         # fourth data row
         [1965,
          {text=>"four winners (Outstanding Program Achievements in Entertainment)", colspan=>3},
          {text=>"five winners (Outstanding Program Achievements in Entertainment)", colspan=>4}],
 
         # fifth data row
         [1966,
          "The Dick Van Dyke Show (CBS)",
          "The Fugitive (ABC)",
          "The Andy Williams Show (NBC)",
          "Dick Van Dyke, The Dick Van Dyke Show (CBS)",
          "Bill Cosby, I Spy (CBS)",
          "Mary Tyler Moore, The Dick Van Dyke Show (CBS)",
          "Barbara Stanwyck, The Big Valley (CBS)"],
     ];
 
     binmode STDOUT, "utf8";
     print generate_table(
         rows => $rows,      # required
         header_row => 1,    # optional, default 0
         separate_rows => 1, # optional, default 0
         border_style => $ARGV[0] // 'ASCII::SingleLineDoubleAfterHeader', # optional, this is module name in BorderStyle::* namespace, without the prefix
         #align => 'left',   # optional, default 'left'. can be left/middle/right.
         #valign => 'top',   # optional, default 'top'. can be top/middle/bottom.
         #color => 1,        # optional, default 0. turn on support for cell content that contain ANSI color codes.
         #wide_char => 1,    # optional, default 0. turn on support for wide Unicode characters.
 
         row_attrs => [      # optional, specify per-row attributes
             # rownum (0-based int), attributes (hashref)
             [0, {align=>'middle', bottom_border=>1}],
         ],
 
         col_attrs => [      # optional, per-column attributes
             # colnum (0-based int), attributes (hashref)
             [2, {valign=>'middle'}],
         ],
 
         #cell_attrs => [    # optional, per-cell attributes
         #    # rownum (0-based int), colnum (0-based int), attributes (hashref)
         #    [1, 2, {rowspan=>3}],
         #    [1, 4, {rowspan=>2, colspan=>2}],
         #    [1, 5, {rowspan=>2, colspan=>2}],
         #    [2, 1, {rowspan=>2}],
         #    [3, 2, {colspan=>2}],
         #    [3, 3, {colspan=>2}],
         #    [4, 1, {colspan=>3}],
         #    [4, 2, {colspan=>4}],
         #],
 
     );

    will output something like:

     .------+------------------------------+----------------------+------------------------------+---------------------------------------------+-------------------------+------------------------------------------------+----------------------------------------.
     | Year |            Comedy            |        Drama         |           Variety            |              Lead Comedy Actor              |    Lead Drama Actor     |              Lead Comedy Actress               |           Lead Drama Actress           |
     +======+==============================+======================+==============================+=============================================+=========================+================================================+========================================+
     | 1962 | The Bob Newhart Show (NBC)   |                      | The Garry Moore Show (CBS)   | E. G. Marshall, The Defenders (CBS)                                   | Shirley Booth, Hazel (NBC)                                                              |
     +------+------------------------------+                      +------------------------------+                                                                       |                                                                                         |
     | 1963 | The Dick Van Dyke Show (CBS) | The Defenders (CBS)  | The Andy Williams Show (NBC) |                                                                       |                                                                                         |
     +------+                              |                      +------------------------------+---------------------------------------------|-------------------------+------------------------------------------------|----------------------------------------+
     | 1964 |                              |                      | The Danny Kaye Show (CBS)    | Dick Van Dyke, The Dick Van Dyke Show (CBS)                           | Mary Tyler Moore, The Dick Van Dyke Show (CBS)                                          |
     +------+------------------------------+----------------------+------------------------------+---------------------------------------------|-------------------------+------------------------------------------------|----------------------------------------+
     | 1965 | four winners (Outstanding Program Achievements in Entertainment)                   | five winners (Outstanding Program Achievements in Entertainment)                                                                                                |
     +------+------------------------------+----------------------+------------------------------+---------------------------------------------+-------------------------+------------------------------------------------+----------------------------------------+
     | 1966 | The Dick Van Dyke Show (CBS) | The Fugitive (ABC)   | The Andy Williams Show (NBC) | Dick Van Dyke, The Dick Van Dyke Show (CBS) | Bill Cosby, I Spy (CBS) | Mary Tyler Moore, The Dick Van Dyke Show (CBS) | Barbara Stanwyck, The Big Valley (CBS) |
     `------+------------------------------+----------------------+------------------------------+---------------------------------------------+-------------------------+------------------------------------------------+----------------------------------------'

    If you set the "border_style" argument to "UTF8::SingleLineBoldHeader":

     print generate_table(
         rows => $rows,
         border_style => "UTF8::SingleLineBoldHeader",
         ...
     );

    then the output will be something like:

     ┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
     ┃ Year ┃            Comedy            ┃        Drama         ┃           Variety            ┃              Lead Comedy Actor              ┃    Lead Drama Actor     ┃              Lead Comedy Actress               ┃           Lead Drama Actress           ┃
     ┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
     │ 1962 │ The Bob Newhart Show (NBC)   │                      │ The Garry Moore Show (CBS)   │ E. G. Marshall, The Defenders (CBS)                                   │ Shirley Booth, Hazel (NBC)                                                              │
     ├──────┼──────────────────────────────┤                      ├──────────────────────────────┤                                                                       │                                                                                         │
     │ 1963 │ The Dick Van Dyke Show (CBS) │ The Defenders (CBS)  │ The Andy Williams Show (NBC) │                                                                       │                                                                                         │
     ├──────┤                              │                      ├──────────────────────────────┼─────────────────────────────────────────────│─────────────────────────┼────────────────────────────────────────────────│────────────────────────────────────────┤
     │ 1964 │                              │                      │ The Danny Kaye Show (CBS)    │ Dick Van Dyke, The Dick Van Dyke Show (CBS)                           │ Mary Tyler Moore, The Dick Van Dyke Show (CBS)                                          │
     ├──────┼──────────────────────────────┴──────────────────────┴──────────────────────────────┼─────────────────────────────────────────────│─────────────────────────┴────────────────────────────────────────────────│────────────────────────────────────────┤
     │ 1965 │ four winners (Outstanding Program Achievements in Entertainment)                   │ five winners (Outstanding Program Achievements in Entertainment)                                                                                                │
     ├──────┼──────────────────────────────┬──────────────────────┬──────────────────────────────┼─────────────────────────────────────────────┬─────────────────────────┬────────────────────────────────────────────────┬────────────────────────────────────────┤
     │ 1966 │ The Dick Van Dyke Show (CBS) │ The Fugitive (ABC)   │ The Andy Williams Show (NBC) │ Dick Van Dyke, The Dick Van Dyke Show (CBS) │ Bill Cosby, I Spy (CBS) │ Mary Tyler Moore, The Dick Van Dyke Show (CBS) │ Barbara Stanwyck, The Big Valley (CBS) │
     └──────┴──────────────────────────────┴──────────────────────┴──────────────────────────────┴─────────────────────────────────────────────┴─────────────────────────┴────────────────────────────────────────────────┴────────────────────────────────────────┘

DESCRIPTION
    Text::Table::More is yet another text table rendering module. This
    module uses the simple interface of Text::Table::Tiny with support for
    more formatting options like column/row spans, border style,
    per-row/column/cell align/valign/pad/vpad/hpad, and so on. At the time
    of this writing, Text::Table::More is the only text table module on CPAN
    that supports rowspans/colspans.

    Keywords: rowspan, colspan.

DECLARED FEATURES
    Features declared by this module:

  From feature set PerlTrove
    Features from feature set PerlTrove declared by this module:

    *   Development Status

        Value: "4 - Beta".

    *   Environment

        Value: "Console".

    *   Intended Audience

        Value: ["Developers"].

    *   License

        Value: "OSI Approved :: Artistic License".

    *   Programming Language

        Value: "Perl".

    *   Topic

        Value: ["Software Development :: Libraries :: Perl
        Modules","Utilities"].

  From feature set TextTable
    Features from feature set TextTable declared by this module:

    *   can_align_cell_containing_color_code

        Value: yes.

    *   can_align_cell_containing_newline

        Value: yes.

    *   can_align_cell_containing_wide_character

        Value: yes.

    *   can_color

        Can produce colored table.

        Value: no.

    *   can_color_theme

        Allow choosing colors from a named set of palettes.

        Value: no.

    *   can_colspan

        Value: yes.

    *   can_customize_border

        Let user customize border character in some way, e.g. selecting from
        several available borders, disable border.

        Value: yes.

    *   can_halign

        Provide a way for user to specify horizontal alignment
        (left/middle/right) of cells.

        Value: yes.

    *   can_halign_individual_cell

        Provide a way for user to specify different horizontal alignment
        (left/middle/right) for individual cells.

        Value: yes.

    *   can_halign_individual_column

        Provide a way for user to specify different horizontal alignment
        (left/middle/right) for individual columns.

        Value: yes.

    *   can_halign_individual_row

        Provide a way for user to specify different horizontal alignment
        (left/middle/right) for individual rows.

        Value: yes.

    *   can_hpad

        Provide a way for user to specify horizontal padding of cells.

        Value: yes.

    *   can_hpad_individual_cell

        Provide a way for user to specify different horizontal padding of
        individual cells.

        Value: yes.

    *   can_hpad_individual_column

        Provide a way for user to specify different horizontal padding of
        individual columns.

        Value: yes.

    *   can_hpad_individual_row

        Provide a way for user to specify different horizontal padding of
        individual rows.

        Value: yes.

    *   can_rowspan

        Value: yes.

    *   can_set_cell_height

        Allow setting height of rows.

        Value: no.

    *   can_set_cell_height_of_individual_row

        Allow setting height of individual rows.

        Value: no.

    *   can_set_cell_width

        Allow setting height of rows.

        Value: no.

    *   can_set_cell_width_of_individual_column

        Allow setting height of individual rows.

        Value: no.

    *   can_use_box_character

        Can use terminal box-drawing character when drawing border.

        Value: yes.

    *   can_valign

        Provide a way for user to specify vertical alignment
        (top/middle/bottom) of cells.

        Value: yes.

    *   can_valign_individual_cell

        Provide a way for user to specify different vertical alignment
        (top/middle/bottom) for individual cells.

        Value: yes.

    *   can_valign_individual_column

        Provide a way for user to specify different vertical alignment
        (top/middle/bottom) for individual columns.

        Value: yes.

    *   can_valign_individual_row

        Provide a way for user to specify different vertical alignment
        (top/middle/bottom) for individual rows.

        Value: yes.

    *   can_vpad

        Provide a way for user to specify vertical padding of cells.

        Value: yes.

    *   can_vpad_individual_cell

        Provide a way for user to specify different vertical padding of
        individual cells.

        Value: yes.

    *   can_vpad_individual_column

        Provide a way for user to specify different vertical padding of
        individual columns.

        Value: yes.

    *   can_vpad_individual_row

        Provide a way for user to specify different vertical padding of
        individual rows.

        Value: yes.

    *   speed

        Subjective speed rating, relative to other text table modules.

        Value: "slow".

    For more details on module features, see Module::Features.

PER-ROW ATTRIBUTES
    *   align

        String. Value is either "left", "middle", "right". Specify text
        alignment of cells. Override table argument, but is overridden by
        per-column or per-cell attribute of the same name.

    *   valign

        String. Value is either "top", "middle", "bottom". Specify vertical
        text alignment of cells. Override table argument, but is overridden
        by per-column or per-cell attribute of the same name.

    *   bottom_border

        Boolean.

    *   top_border

        Boolean.

    *   lpad

        Integer.

    *   rpad

        Integer.

    *   hpad

        Integer.

    *   tpad

        Integer.

    *   bpad

        Integer.

    *   vpad

        Integer.

PER-COLUMN ATTRIBUTES
    *   align

        String. Value is either "left", "middle", "right". Specify text
        alignment of cells. Override table argument and per-row attribute of
        the same name, but is overridden by per-cell attribute of the same
        name.

    *   valign

        String. Value is either "top", "middle", "bottom". Specify vertical
        text alignment of cells. Override table argument and per-row
        attribute of the same name, but is overridden by per-cell attribute
        of the same name.

    *   lpad

        Integer.

    *   rpad

        Integer.

    *   hpad

        Integer.

    *   tpad

        Integer.

    *   bpad

        Integer.

    *   vpad

        Integer.

PER-CELL ATTRIBUTES
    *   align

        String. Value is either "left", "middle", "right". Override table
        argument, per-row attribute, and per-column attribute of the same
        name.

    *   valign

        String. Value is either "top", "middle", "bottom". Specify vertical
        text alignment of cells. Override table argument, per-row attribute,
        and per-column attribute of the same name.

    *   colspan

        Positive integer. Default 1.

    *   rowspan

        Positive integer. Default 1.

    *   bottom_border.

        Boolean. Currently the attribute of he leftmost cell is used.

    *   top_border.

        Boolean. Currently the attribute of he leftmost cell is used.

    *   lpad

        Integer.

    *   rpad

        Integer.

    *   hpad

        Integer.

    *   tpad

        Integer.

    *   bpad

        Integer.

    *   vpad

        Integer.

    *   pad_char

        String.

FUNCTIONS
  generate_table
    Usage:

     my $table_str = generate_table(%args);

    Arguments:

    *   rows

        Array of arrayrefs (of strings or hashrefs). Required. Each array
        element is a row of cells. A cell can be a string like "foo"
        specifying only the text (equivalent to "{text=>"foo"}") or a
        hashref which allows you to specify a cell's text ("text") as well
        as attributes like "rowspan" (int, >= 1), "colspan" (int, >= 1),
        etc. See "PER-CELL ATTRIBUTES" for the list of known per-cell
        attributes.

        Currently, "top_border" and "bottom_border" needs to be specified
        for the first column of a row and will take effect for the whole
        row.

        Alternatively, you can also specify cell attributes using
        "cell_attrs" argument.

    *   header_row

        Int. Optional. Default 0. Number of rows that are header. Note that
        in Text::Table::Tiny, this option is a boolean. We use integer to
        support multirow header.

    *   border_style

        Str. Optional. Uses default from the environment variable
        "PERL_TEXT_TABLE_MORE_BORDER_STYLE", or environment variable
        "BORDER_STYLE", or "ASCII::SingleLineDoubleAfterHeader". This is
        Perl module under the BorderStyle namespace, without the namespace
        prefix. To see how a border style looks like, you can use the CLI
        show-border-style from App::BorderStyleUtils.

    *   align

        String. Value is either "left", "middle", "right". Specify
        horizontal text alignment of cells. Overriden by overridden by
        per-row, per-column, or per-cell attribute of the same name.

    *   valign

        String. Value is either "top", "middle", "bottom". Specify vertical
        text alignment of cells. Overriden by overridden by per-row,
        per-column, or per-cell attribute of the same name.

    *   row_attrs

        Array of records. Optional. Specify per-row attributes. Each record
        is a 2-element arrayref: "[$row_idx, \%attrs]". $row_idx is
        zero-based. See "PER-ROW ATTRIBUTES" for the list of known
        attributes.

    *   col_attrs

        Array of records. Optional. Specify per-column attributes. Each
        record is a 2-element arrayref: "[$col_idx, \%attrs]". $col_idx is
        zero-based. See "PER-COLUMN ATTRIBUTES" for the list of known
        attributes.

    *   cell_attrs

        Array of records. Optional. Specify per-cell attributes. Each record
        is a 3-element arrayref: "[$row_idx, $col_idx, \%attrs]". $row_idx
        and $col_idx are zero-based. See "PER-CELL ATTRIBUTES" for the list
        of known attributes.

        Alternatively, you can specify a cell's attribute in the "rows"
        argument directly, by specifying a cell as hashref.

    *   lpad

        Integer. Optional. Set number of padding characters to add at the
        left side of table cells. Overrides "hpad". Overridden by
        per-row/per-column/per-cell padding attributes. See also "rpad".

    *   rpad

        Integer. Optional. Set number of padding characters to add at the
        right side of table cells. Overrides "hpad". Overridden by
        per-row/per-column/per-cell padding attributes. See also "rpad".

    *   hpad

        Integer. Optional. Set number of padding characters to add at the
        left and right sides of table cells. Overridden by "lpad" for left
        side, and "rpad" for right side. Overridden by
        per-row/per-column/per-cell padding attributes. See also "vpad".

        Default is 1.

    *   tpad

        Integer. Optional. Set number of padding lines to add at the top
        side of table cells. Overrides "vpad". Overridden by
        per-row/per-column/per-cell padding attributes. See also "bpad".

    *   bpad

        Integer. Optional. Set number of padding lines to add at the bottom
        side of table cells. Overrides "vpad". Overridden by
        per-row/per-column/per-cell padding attributes. See also "tpad".

    *   vpad

        Integer. Optional. Set number of padding lines to add at the top and
        bottom sides of table cells. Overridden by "tpad" for top side, and
        "bpad" for bottom side. Overridden by per-row/per-column/per-cell
        padding attributes. See also "hpad".

        Default is 0.

    *   pad_char

        String. Optional. Must be one character long. Default is " " (space
        character).

    *   separate_rows

        Boolean. Optional. Default 0. If set to true, will add a separator
        between data rows. Equivalent to setting "bottom_border" or
        "top_border" attribute to true for each row.

    *   wide_char

        Boolean. Optional. Default false. Turn on wide character support.
        Cells that contain wide Unicode characters will still be properly
        aligned. Note that this requires optional prereq
        Text::WideChar::Util or Text::ANSI::WideUtil.

    *   color

        Boolean. Optional. Default false. Turn on color support. Cells that
        contain ANSI color codes will still be properly aligned. Note that
        this requires optional prereq Text::ANSI::Util or
        Text::ANSI::WideUtil.

FAQ
  Can I have multiple header rows?
    Yes, by setting "header_row" option to 2 or whatever number of header
    rows you have. See example script multirow-header.pl in this
    distribution.

ENVIRONMENT
  PERL_TEXT_TABLE_MORE_BORDER_STYLE
    String. Used to set the default for the "border_style" option. Has
    higher precedence than "BORDER_STYLE".

  BORDER_STYLE
    String. Used to set the default for the "border_style" option. Has lower
    precedence than "PERL_TEXT_TABLE_MORE_BORDER_STYLE".

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

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

SEE ALSO
    Text::ANSITable also offers lots of formatting options, but currently
    lacks support for rowspan/colspan. It also uses an OO interface and has
    features I never use: hiding rows and selecting display columns
    different from declared columns. I currently plan to actively develop
    Text::Table::More instead of Text::ANSITable, but we'll see.

    Acme::CPANModules::TextTable contains a comparison and benchmark for
    modules that generate text table.

    HTML <TABLE> element,
    <https://www.w3.org/TR/2014/REC-html5-20141028/tabular-data.html>,
    <https://www.w3.org/html/wiki/Elements/table>

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, 2021 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-More>

    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.

