/ 
Text-Table-Sprintf-0.008
River stage three • 7 direct dependents • 793 total dependents
/ Text::Table::Sprintf

NAME

Text::Table::Sprintf - Generate simple text tables from 2D arrays using sprintf()

VERSION

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

SYNOPSIS

use Text::Table::Sprintf;

my $rows = [
    # header row
    ['Name', 'Rank', 'Serial'],
    # rows
    ['alice', 'pvt', '123456'],
    ['bob',   'cpl', '98765321'],
    ['carol', 'brig gen', '8745'],
];
print Text::Table::Sprintf::table(rows => $rows, header_row => 1);

DESCRIPTION

This module provides a single function, table, which formats a two-dimensional array of data as a simple text table.

The example shown in the SYNOPSIS generates the following table:

+-------+----------+----------+
| Name  | Rank     | Serial   |
+-------+----------+----------+
| alice | pvt      | 123456   |
| bob   | cpl      | 98765321 |
| carol | brig gen | 8745     |
+-------+----------+----------+

This module models its interface on Text::Table::Tiny 0.03, employs the same technique of using sprintf(), but takes the technique further by using a single large format and sprintf the whole table. This results in even more performance gain (see benchmark result or benchmark using Acme::CPANModules::TextTable).

Caveats: make sure each row contains the same number of elements. Otherwise, the table will not be correctly formatted (cells might move to another row/column).

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

  • can_align_cell_containing_newline

    Value: no.

  • can_align_cell_containing_wide_character

    Value: no.

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

  • can_customize_border

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

    Value: no.

  • can_halign

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

    Value: yes.

    Only support l (left) and r (right) alignment, not c (center).

  • can_halign_individual_cell

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

    Value: no.

  • can_halign_individual_column

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

    Value: no.

  • can_halign_individual_row

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

    Value: no.

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

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

  • can_valign

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

    Value: no.

  • can_valign_individual_cell

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

    Value: no.

  • can_valign_individual_column

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

    Value: no.

  • can_valign_individual_row

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

    Value: no.

  • 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: "fast".

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

FUNCTIONS

table

Usage:

my $table_str = Text::Table::Sprintf::table(%params);

The table function understands these arguments, which are passed as a hash.

  • rows

    Aoaos. Required. Takes an array reference which should contain one or more rows of data, where each row is an array reference.

  • header_row

    Bool. Optional. Defaults to false. If given a true value, the first row in the data will be interpreted as a header row, and separated from the rest of the table with a ruled line.

  • separate_rows

    Bool. Optional. Defaults to false. If set to true, will draw separator line between data rows.

  • align

    Str or array of str. Optional. Declare alignment for all columns or for individul columns. Valid alignment value is 'l' (for left) or 'r' (for right), center alignment is currently not supported. Default alignment is left.

generate_table

Alias for "table", for compatibility with Text::Table::Tiny.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Text-Table-Sprintf.

SOURCE

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

SEE ALSO

Text::Table::Tiny

Other text table modules listed in Acme::CPANModules::TextTable. The selling point of Text::Table::Sprintf is performance and light footprint (just about two pages of code that does not use any module, core or otherwise).

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

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.