NAME

Text::Table::Span - Text::Table::Tiny + support for column/row spans

VERSION

This document describes version 0.008 of Text::Table::Span (from Perl distribution Text-Table-Span), released on 2021-02-20.

SYNOPSIS

You can either specify column & row spans in the cells themselves, using hashrefs:

use Text::Table::Span 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},
     "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)"],
];
print generate_table(
    rows => $rows,
    header_row => 1,
    separate_rows => 1,
    #border_style => 'ASCII::SingleLineDoubleAfterHeader', # module in BorderStyle::* namespace, without the prefix. default is ASCII::SingleLineDoubleAfterHeader
);

Or, you can also use the cell_attrs option:

use Text::Table::Span 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)",
     "The Defenders (CBS)",,
     "The Garry Moore Show (CBS)",
     "E. G. Marshall, The Defenders (CBS)",
     "Shirley Booth, Hazel (NBC)"],

    # second data row
    [1963,
     "The Dick Van Dyke Show (CBS)",
     "The Andy Williams Show (NBC)"],

    # third data row
    [1964,
     "The Danny Kaye Show (CBS)"],

    # fourth data row
    [1965,
     "four winners (Outstanding Program Achievements in Entertainment)",
     "five winners (Outstanding Program Achievements in Entertainment)"],

    # 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)"],
];
print generate_table(
    rows => $rows,
    header_row => 1,
    separate_rows => 1,
    #border_style => 'ASCII::SingleLineDoubleAfterHeader', # module in BorderStyle::* namespace, without the prefix. default is ASCII::SingleLineDoubleAfterHeader
    cell_attrs => [
        # 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 Defenders (CBS) | The Garry Moore Show (CBS)   | E. G. Marshall                                  | Shirley Booth                                       |
+------+------------------------------+                     +------------------------------+ The Defenders (CBS)                             | Hazel (NBC)                                         |
| 1963 | The Dick Van Dyke Show (CBS) |                     | The Andy Williams Show (NBC) |                                                 |                                                     |
+------+                              |                     +------------------------------+-------------------------------------------------+-----------------------------------------------------+
| 1964 |                              |                     | The Danny Kaye Show (CBS)    | Dick Van Dyke                                   | Mary Tyler Moore                                    |
|      |                              |                     |                              | The Dick Van Dyke Show (CBS)                    | The Dick Van Dyke Show (CBS)                        |
+------+------------------------------+---------------------+------------------------------+-------------------------------------------------+-----------------------------------------------------+
| 1965 | four winners                                                                      | five winners                                                                                          |
+------+------------------------------+---------------------+------------------------------+------------------------------+------------------+------------------------------+----------------------+
| 1966 | The Dick Van Dyke Show (CBS) | The Fugitive (ABC)  | The Andy Williams Show (NBC) | Dick Van Dyke                | Bill Cosby       | Mary Tyler Moore             | Barbara Stanwyck     |
|      |                              |                     |                              | The Dick Van Dyke Show (CBS) | I Spy (CBS)      | The Dick Van Dyke Show (CBS) | 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 this:

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

DESCRIPTION

This module is like Text::Table::Tiny (0.04) with added support for column/row spans, and border style.

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.

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

SOURCE

Source repository is at https://github.com/perlancar/perl-Text-Table-Span.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/perlancar/perl-Text-Table-Span/issues

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.

AUTHOR

perlancar <perlancar@cpan.org>

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.

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

cpanm

cpanm Text::Table::Span

CPAN shell

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

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

PER-ROW ATTRIBUTES

align

valign

bottom_border

top_border

PER-COLUMN ATTRIBUTES

align

valign

PER-CELL ATTRIBUTES

align

valign

colspan

rowspan

FUNCTIONS

generate_table

HOMEPAGE

SOURCE

BUGS

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions