NAME

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

VERSION

This document describes version 0.017 of Text::Table::More (from Perl distribution Text-Table-More), released on 2021-08-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

This module uses the simple interface of Text::Table::Tiny (0.04) with support for more formatting options like column/row spans, border style, per-row/column/cell align/valign.

Keywords: rowspan, colspan.

DECLARED FEATURES

Features declared by this module:

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: no.
can_hpad_individual_cell

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

Value: no.
can_hpad_individual_column

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

Value: no.
can_hpad_individual_row

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

Value: no.
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: no.
can_vpad_individual_cell

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

Value: no.
can_vpad_individual_column

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

Value: no.
can_vpad_individual_row

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

Value: no.
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.

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.

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.

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

Boolean. Optional. Default 0. Whether to treat the first row as the header row, which means draw a separator line between it and the rest.
border_style

Str. Optional. Default to 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.
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.

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.

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

To install Text::Table::More, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Text::Table::More

CPAN shell

perl -MCPAN -e shell
install Text::Table::More

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

DECLARED FEATURES

From feature set TextTable

PER-ROW ATTRIBUTES

align

valign

bottom_border

top_border

PER-COLUMN ATTRIBUTES

align

valign

PER-CELL ATTRIBUTES

align

valign

colspan

rowspan

bottom_border.

top_border.

FUNCTIONS

generate_table

HOMEPAGE

SOURCE

SEE ALSO

AUTHOR

CONTRIBUTING

COPYRIGHT AND LICENSE

BUGS

Module Install Instructions