NAME

Synopsis

        #!/usr/bin/env perl

        use strict;
        use utf8;
        use warnings;
        use warnings qw(FATAL utf8); # Fatalize encoding glitches.
        use open     qw(:std :utf8); # Undeclared streams in UTF-8.

        use Text::Table::Manifold ':constants';

        # -----------

        # Set parameters with new().

        my($table) = Text::Table::Manifold -> new
        (
                alignment =>
                [
                        align_left,
                        align_center,
                        align_right,
                        align_center,
                ]
        );

        $table -> headers(['Homepage', 'Country', 'Name', 'Metadata']);
        $table -> data(
        [
                ['http://savage.net.au/',   'Australia', 'Ron Savage',    undef],
                ['https://duckduckgo.com/', 'Earth',     'Mr. S. Engine', ''],
        ]);

        # Note: Save the data, since render() may update it.

        my(@data) = @{$table -> data};

        # Set parameters with methods.

        $table -> empty(empty_as_text);
        $table -> format(format_internal_boxed);
        $table -> undef(undef_as_text);

        # Set parameters with render().

        print "Format: format_internal_boxed: \n";
        print join("\n", @{$table -> render(padding => 1)}), "\n";
        print "\n";

        $table -> headers(['One', 'Two', 'Three']);
        $table -> data(
        [
                ['Reichwaldstraße', 'Böhme', 'ʎ ʏ ʐ ʑ ʒ ʓ ʙ ʚ'],
                ['ΔΔΔΔΔΔΔΔΔΔ', 'Πηληϊάδεω Ἀχιλῆος', 'A snowman: ☃'],
                ['Two ticks: ✔✔', undef, '<table><tr><td>TBA</td></tr></table>'],
        ]);

        # Save the data, since render() may update it.

        @data = @{$table -> data};

        $table -> empty(empty_as_minus);
        $table -> format(format_internal_boxed);
        $table -> undef(undef_as_text);
        $table -> padding(2);

        print "Format: format_internal_boxed: \n";
        print join("\n", @{$table -> render}), "\n";
        print "\n";

        # Restore the saved data.

        $table -> data([@data]);

        # Etc.

This is data/synopsis.log, the output of synopsis.pl:

        Format: format_internal_boxed:
        +-------------------------+-----------+---------------+----------+
        | Homepage                |  Country  |          Name | Metadata |
        +-------------------------+-----------+---------------+----------+
        | http://savage.net.au/   | Australia |    Ron Savage |  undef   |
        | https://duckduckgo.com/ |   Earth   | Mr. S. Engine |  empty   |
        +-------------------------+-----------+---------------+----------+

        Format: format_internal_boxed:
        +-------------------+---------------------+----------------------------------------+
        |  One              |         Two         |                                 Three  |
        +-------------------+---------------------+----------------------------------------+
        |  Reichwaldstraße  |        Böhme        |                       ʎ ʏ ʐ ʑ ʒ ʓ ʙ ʚ  |
        |  ΔΔΔΔΔΔΔΔΔΔ       |  Πηληϊάδεω Ἀχιλῆος  |                          A snowman: ☃  |
        |  Two ticks: ✔✔    |        undef        |  <table><tr><td>TBA</td></tr></table>  |
        +-------------------+---------------------+----------------------------------------+

The latter table renders perfectly in FF, but not so in Chrome (today, 2015-01-31).

Description

Features:

o Generic interface to all supported table formats

o Separately specify header/data/footer rows

o Separately include/exclude header/data/footer rows

o Align cell values

Each column has its own alignment option, left, center or right.

For internally generated HTML, this is done with a CSS "div" within each "td", not with the obsolete "td align" attribute.

But decimal places are not alignable, yet, as discussed in the "TODO".

o Escape HTML entities or URIs

But not both at the same time!

o Extend short header/data/footer rows with empty strings or undef

Auto-extension results in all rows being the same length.

This takes place before the transformation, if any, mentioned next.

o Tranform cell values which are empty strings and undef

o Pad cell values

o Handle UFT8

o Return the table as an arrayref of lines or as a string

The arrayref is returned by "render([%hash])", and the string by "render_as_string([%hash])".

When returning a string by calling "render_as_string()" (which calls "render()"), you can specify how the lines in the arrayref are joined.

In the same way the "format" parameter discussed just below controls the output, the "join" parameter controls the join.

The format of the output is controlled by the "format" parameter to "new()", or by the parameter to the "format([$format])" method, or by the value of the "format" key in the hash passed to "render([%hash])" and "render_as_string(%hash])", and must be one of these imported constants:

o format_internal_boxed

All headers, footers and table data are surrounded by ASCII characters.

The rendering is done internally.

See scripts/internal.boxed.pl and output file data/internal.boxed.log.

o format_internal_github

Render as github-flavoured markdown.

The rendering is done internally.

See scripts/internal.github.pl and output file data/internal.github.log.

o format_internal_html

Render as a HTML table. You can use the "pass_thru([$hashref])" method to set options for the HTML table.

The rendering is done internally.

See scripts/internal.html.pl and output file data/internal.html.log.

o format_html_table

Passes the data to HTML::Table. You can use the "pass_thru([$hashref])" method to set options for the "HTML::Table" object constructor.

Warning: You must use "Text::Table::Manifold"'s "data()" method, or the "data" parameter to "new()", and not the "-data" option to "HTML::Table". This is because the module processes the data before calling the "HTML::Table" constructor.

o format_text_csv

Passes the data to Text::CSV. You can use the "pass_thru([$hashref])" method to set options for the "Text::CSV" object constructor.

See scripts/text.csv.pl and output file data/text.csv.log.

o format_text_unicodebox_table

Passes the data to Text::UnicodeBox::Table. You can use the "pass_thru([$hashref])" method to set options for the "Text::UnicodeBox::Table" object constructor.

See scripts/text.unicodebox.table.pl and output file data/text.unicodebox.table.log.

See also scripts/synopsis.pl, and the output data/synopsis.log.

Distributions

See <http://savage.net.au/Perl-modules/html/installing-a-module.html> for help on unpacking and installing distros.

Installation

Run:

        cpanm Text::Table::Manifold

or run:

        sudo cpan Text::Table::Manifold

or unpack the distro, and then either:

        perl Build.PL
        ./Build
        ./Build test
        sudo ./Build install

or:

        perl Makefile.PL
        make (or dmake or nmake)
        make test
        make install

Constructor and Initialization

It returns a new object of type "Text::Table::Manifold".

Details of all parameters are explained in the "FAQ".

Key-value pairs accepted in the parameter list (see corresponding methods for details [e.g. "data([$arrayref])"]):

o alignment => $arrayref of imported constants

This specifies alignment per column. There should be one array element per column of data. The $arrayref will be auto-extended if necessary, using the constant "align_center".

Alignment applies equally to every cell in the column.

A value for this parameter is optional.

Default: align_center for every column.

o data => $arrayref_of_arrayrefs

This specifies the table of cell values.

An arrayref of arrayrefs, each inner arrayref is a row of data.

The # of elements in each alignment/header/data/footer row does not have to be the same. See the "extend*" parameters for more. Auto-extension results in all rows being the same length.

A value for this parameter is optional.

Default: [].

o empty => An imported constant

This specifies how to transform cell values which are the empty string. See also the "undef" parameter.

The "empty" parameter is activated after the "extend*" parameters has been applied.

A value for this parameter is optional.

Default: empty_as_empty. I.e. do not transform.

o escape => An imported constant

This specifies escaping of either HTML entities or URIs.

A value for this parameter is optional.

Default: escape_nothing. I.e. do not transform.

o extend_data => An imported constant

The 2 constants available allow you to specify how short data rows are extended. Then, after extension, the transformations specified by the parameters "empty" and "undef" are applied.

A value for this parameter is optional.

Default: extend_with_empty. I.e. extend short data rows with the empty string.

o extend_footers => An imported constant

The 2 constants available allow you to specify how short footer rows are extended. Then, after extension, the transformations specified by the parameters "empty" and "undef" are applied.

A value for this parameter is optional.

Default: extend_with_empty. I.e. extend short footer rows with the empty string.

o extend_headers => An imported constant

The 2 constants available allow you to specify how short header rows are extended. Then, after extension, the transformations specified by the parameters "empty" and "undef" are applied.

A value for this parameter is optional.

Default: extend_with_empty. I.e. extend short header rows with the empty string.

o footers => $arrayref

These are the column footers. See also the "headers" option.

The # of elements in each header/data/footer row does not have to be the same. See the "extend*" parameters for more.

A value for this parameter is optional.

Default: [].

o format => An imported constant

This specifies which format to output from the rendering methods.

A value for this parameter is optional.

Default: format_internal_boxed.

o headers => $arrayref

These are the column headers. See also the "footers" option.

The # of elements in each header/data/footer row does not have to be the same. See the "extend*" parameters for more.

A value for this parameter is optional.

Default: [].

o include => An imported constant

Controls whether header/data/footer rows are included in the output.

The are three constants available, and any of them can be combined with '|', the logical OR operator.

A value for this parameter is optional.

Default: include_headers | include_data.

o join => $string

"render_as_string([%hash])" uses $hash{join}, or $self -> join, in Perl's "join($join, @$araref)" to join the elements of the arrayref returned by internally calling "render([%hash])".

"render()" ignores the "join" key in the hash.

A value for this parameter is optional.

Default: ''.

o padding => $integer

This integer is the # of spaces added to each side of the cell value, after the "alignment" parameter has been applied.

A value for this parameter is optional.

Default: 0.

o pass_thru => $hashref

A hashref of values to pass thru to another object.

The keys in this $hashref control what parameters are passed to rendering routines.

A value for this parameter is optional.

Default: {}.

o undef => An imported constant

This specifies how to transform cell values which are undef. See also the "empty" parameter.

The "undef" parameter is activated after the "extend*" parameters have been applied.

A value for this parameter is optional.

Default: undef_as_undef. I.e. do not transform.

Methods

And remember, all methods listed here which are parameters to "new([%hash])", are also parameters to both "render([%hash])" and "render_as_string([%hash])".

        print join("\n", @{$table -> render}), "\n";

FAQ

        use Text::Table::Manifold ':constants';

        my($table) = Text::Table::Manifold -> new(empty => empty_as_text);

        $table -> format(format_internal_boxed);

        shell> perl Build.PL; ./Build; ./Build authortest

TODO

o Fancy alignment of real numbers

It makes sense to right-justify integers, but in the rest of the table you probably want to left-justify strings.

Then, vertically aligning decimal points (whatever they are in your locale) is another complexity.

See Text::ASCIITable and Text::Table.

o Embedded newlines

Cell values could be split at each "\n" character, to find the widest line within the cell. That would be then used as the cell's width.

For Unicode, this is complex. See <http://www.unicode.org/versions/Unicode7.0.0/ch04.pdf>, and especially p 192, for 'Line break' controls. Also, the Unicode line breaking algorithm is documented in <http://www.unicode.org/reports/tr14/>.

Perl modules and other links relevant to this topic are listed under "See Also#Line Breaking".

o Nested tables

This really requires the implementation of embedded newline analysis, as per the previous point.

o Pass-thru class support

The problem is the mixture of options required to drive classes.

o Sorting the rows, or individual columns

See Data::Table and HTML::Table.

o Color support

See Text::ANSITable.

o Subtotal support

Maybe one day. I did see a subtotal feature in a module while researching this, but I can't find it any more.

See Data::Table. It has grouping features.

See Also

Machine-Readable Change Log

Version Numbers

Repository

Support

<https://github.com/ronsavage/Text-Table-Manifold/issues>

Author

Marpa's homepage: <http://savage.net.au/Marpa.html>.

My homepage: <http://savage.net.au/>.

Copyright

        All Programs of mine are 'OSI Certified Open Source Software';
        you can redistribute them and/or modify them under the terms of
        The Perl Artistic License, a copy of which is available at:
        https://perldoc.perl.org/perlartistic.html.