FreeBSD Manual Pages
Text::Table::Manifold(User Contributed Perl DocumentatText::Table::Manifold(3) NAME "Text::Table::Manifold" - Render tables in manifold formats Synopsis This is scripts/synopsis.pl: #!/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( [ ['ReichwaldstraAe', 'BA<paragraph>hme', 'E E E E E E E E'], ['IIIIIIIIII', 'I I.I>>I.II~I'I<micro>I a1/4II^1I>>a?I?I', 'A snowman: a'], ['Two ticks: aa', 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 | +-------------------+---------------------+----------------------------------------+ | ReichwaldstraAe | BA<paragraph>hme | E E E E E E E E | | IIIIIIIIII | I I.I>>I.II~I'I<micro>I a1/4II^1I>>a?I?I | A snowman: a | | Two ticks: aa | 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 Outputs tables in any one of several supported types. 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 This module is available as a Unix-style distro (*.tgz). See <http://savage.net.au/Perl-modules/html/installing-a-module.html> for help on unpacking and installing distros. Installation Install Text::Table::Manifold as you would any "Perl" module: 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 "new()" is called as "my($parser) = Text::Table::Manifold -> new(k1 => v1, k2 => v2, ...)". 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 See the "FAQ" for details of all importable constants mentioned here. And remember, all methods listed here which are parameters to "new([%hash])", are also parameters to both "render([%hash])" and "render_as_string([%hash])". alignment([$arrayref]) Here, the [] indicate an optional parameter. Returns the alignment as an arrayref of constants, one per column. There should be one element in $arrayref for each column of data. If the $arrayref is too short, "align_center" is the default for the missing alignments. Obviously, $arrayref might force spaces to be added to one or both sides of a cell value. Alignment applies equally to every cell in the column. This happens before any spaces specified by "padding([$integer])" are added. See the "FAQ#What are the constants for alignment?" for legal values for the alignments (per column). "alignment" is a parameter to "new([%hash])". See "Constructor and Initialization". data([$arrayref]) Here, the [] indicate an optional parameter. Returns the data as an arrayref. Each element in this arrayref is an arrayref of one row of data. The structure of $arrayref, if provided, must match the description in the previous line. Rows do not need to have the same number of elements. Use Perl's "undef" or '' (the empty string) for missing values. See "empty([$empty])" and "undef([$undef])" for how '' and "undef" are handled. See "extend_data([$extend])" for how to extend short data rows, or let the code extend auto-extend them. "data" is a parameter to "new([%hash])". See "Constructor and Initialization". empty([$empty]) Here, the [] indicate an optional parameter. Returns the option specifying how empty cell values ('') are being dealt with. $empty controls how empty strings in cells are rendered. See the "FAQ#What are the constants for handling cell values which are empty strings?" for legal values for $empty. See also "undef([$undef])". "empty" is a parameter to "new([%hash])". See "Constructor and Initialization". escape([$escape]) Here, the [] indicate an optional parameter. Returns the option specifying how HTML entities and URIs are being dealt with. $escape controls how either HTML entities or URIs are rendered. See the "FAQ#What are the constants for escaping HTML entities and URIs?" for legal values for $escape. "escape" is a parameter to "new([%hash])". See "Constructor and Initialization". extend_data([$extend]) Here, the [] indicate an optional parameter. Returns the option specifying how short data rows are extended. If the # of elements in a data row is shorter than the longest row, $extend specifies how to extend those short rows. See the "FAQ#What are the constants for extending short rows?" for legal values for $extend. "extend_data" is a parameter to "new([%hash])". See "Constructor and Initialization". extend_footers([$extend]) Here, the [] indicate an optional parameter. Returns the option specifying how short footer rows are extended. If the # of elements in a footer row is shorter than the longest row, $extend specifies how to extend those short rows. See the "FAQ#What are the constants for extending short rows?" for legal values for $extend. "extend_footers" is a parameter to "new([%hash])". See "Constructor and Initialization". extend_headers([$extend]) Here, the [] indicate an optional parameter. Returns the option specifying how short header rows are extended. If the # of elements in a header row is shorter than the longest row, $extend specifies how to extend those short rows. See the "FAQ#What are the constants for extending short rows?" for legal values for $extend. "extend_headers" is a parameter to "new([%hash])". See "Constructor and Initialization". footers([$arrayref]) Here, the [] indicate an optional parameter. Returns the footers as an arrayref of strings. $arrayref, if provided, must be an arrayref of strings. See "extend_footers([$extend])" for how to extend a short footer row, or let the code auto-extend it. "footers" is a parameter to "new([%hash])". See "Constructor and Initialization". format([$format]) Here, the [] indicate an optional parameter. Returns the format as a constant (actually an integer). See the "FAQ#What are the constants for formatting?" for legal values for $format. "format" is a parameter to "new([%hash])". See "Constructor and Initialization". format_as_internal_boxed() Called by "render([%hash])". format_as_internal_github() Called by "render([%hash])". format_as_internal_html() Called by "render([%hash])". format_as_html_table() Called by "render([%hash])". format_as_text_csv(). Called by "render([%hash])". format_as_text_unicodebox_table() Called by "render([%hash])". headers([$arrayref]) Here, the [] indicate an optional parameter. Returns the headers as an arrayref of strings. $arrayref, if provided, must be an arrayref of strings. See "extend_headers([$extend])" for how to extend a short header row, or let the code auto-extend it. "headers" is a parameter to "new([%hash])". See "Constructor and Initialization". include([$include]) Here, the [] indicate an optional parameter. Returns the option specifying if header/data/footer rows are included in the output. See the "FAQ#What are the constants for including/excluding rows in the output?" for legal values for $include. "include" is a parameter to "new([%hash])". See "Constructor and Initialization". join([$join]) Here, the [] indicate an optional parameter. Returns the string used to join lines in the table when you call "render_as_string([%hash])". $join is the parameter passed to the Perl function "join()" by "render_as_string()". Further, you can use the key "join" in %hash to pass a value directly to "render_as_string([%hash])". new([%hash]) The constructor. See "Constructor and Initialization" for details of the parameter list. Note: "render([%hash])" and "render_as_string([%hash])"support the same options as "new()". padding([$integer]) Here, the [] indicate an optional parameter. Returns the padding as an integer. Padding is the # of spaces to add to both sides of the cell value after it has been aligned. "padding" is a parameter to "new([%hash])". See "Constructor and Initialization". pass_thru([$hashref]) Here, the [] indicate an optional parameter. Returns the hashref previously provided. See "FAQ#What is the format of the $hashref used in the call to pass_thru()?" for details. See scripts/html.table.pl, scripts/internal.table.pl and scripts/text.csv.pl for sample code where it is used in various ways. "pass_thru" is a parameter to "new([%hash])". See "Constructor and Initialization". render([%hash]) Here, the [] indicate an optional parameter. Returns an arrayref, where each element is 1 line of the output table. These lines do not have "\n" or any other line terminator added by this module. It's up to you how to handle the output. The simplest thing is to just do: print join("\n", @{$table -> render}), "\n"; Note: "render()" supports the same options as "new([%hash])". "render()" ignores the "join" key in the hash. See also "render_as_string([%hash])". render_as_string([%hash]) Here, the [] indicate an optional parameter. Returns the rendered data as a string. "render_as_string" uses the value of $hash{join}, or the result of calling $self -> join, in Perl's "join($join, @$araref)" to join the elements of the arrayref returned by internally calling "render([%hash])". Note: "render_as_string()" supports the same options as "new([%hash])", and passes them all to "render([%hash])". See also "render([%hash])". undef([$undef]) Here, the [] indicate an optional parameter. Returns the option specifying how undef cell values are being dealt with. $undef controls how undefs in cells are rendered. See the "FAQ#What are the constants for handling cell values which are undef?" for legal values for $undef. See also "empty([$empty])". "undef" is a parameter to "new([%hash])". See "Constructor and Initialization". widths() Returns an arrayref of the width of each column, after the data is cleaned and rectified, but before it has been aligned or padded. FAQ Note: See "TODO" for what has not been implemented yet. How are imported constants used? Firstly, you must import them with: use Text::Table::Manifold ':constants'; Then you can use them in the constructor: my($table) = Text::Table::Manifold -> new(empty => empty_as_text); And/or you can use them in method calls: $table -> format(format_internal_boxed); See scripts/synopsis.pl for various use cases. Note how sample code uses the names of the constants. The integer values listed below are just FYI. What are the constants for alignment? The parameters, one per column, to "alignment([$arrayref])" must be one of the following: o align_left => 0 o align_center => 1 So-spelt. Not 'centre'. o align_right => 2 Alignment applies equally to every cell in a column. What are the constants for handling cell values which are empty strings? The parameter to "empty([$empty])" must be one of the following: o empty_as_empty => 0 Do nothing. This is the default. o empty_as_minus => 1 Convert empty cell values to '-'. o empty_as_text => 2 Convert empty cell values to the text string 'empty'. o empty_as_undef => 3 Convert empty cell values to undef. See also "undef([$undef])". Warning: This updates the original data! What are the constants for escaping HTML entities and URIs? The parameter to "escape([$escape])" must be one of the following: o escape_nothing => 0 This is the default. o escape_html => 1 Use HTML::Entities::Interpolate to escape HTML entities. "HTML::Entities::Interpolate" cannot be loaded at runtime, and so is always needed. o escape_uri => 2 Use URI::Escape's uri_escape() method to escape URIs. "URI::Escape" is loaded at runtime if needed. Warning: This updates the original data! What are the constants for extending short rows? The parameters to "extend_data([$extend])", "extend_footers([$extend])" and "extend_headers([$extend])", must be one of the following: o extend_with_empty => 0 Short header/data/footer rows are extended with the empty string. Later, the values discussed under "FAQ#What are the constants for handling cell values which are empty strings?" will be applied. o extend_with_undef => 1 Short header/data/footer rows are extended with undef. Later, the values discussed under "FAQ#What are the constants for handling cell values which are undef?" will be applied. See also "empty([$empty])" and "undef([$undef])". Warning: This updates the original data! What are the constants for formatting? The parameter to "format([$format])" must be one of the following: o format_internal_boxed => 0 Render internally. o format_text_csv => 1 Text::CSV is loaded at runtime if this option is used. o format_internal_github => 2 Render internally. o format_internal_html => 3 Render internally. o format_html_table => 4 HTML::Table is loaded at runtime if this option is used. o format_text_unicodebox_table => 5 Text::UnicodeBox::Table is loaded at runtime if this option is used. What are the constants for including/excluding rows in the output? The parameter to "include([$include])" must be one or more of the following: o include_data => 1 Data rows are included in the output. o include_footers => 2 Footer rows are included in the output. o include_headers => 4 Header rows are included in the output. What is the format of the $hashref used in the call to pass_thru()? It takes these (key => value) pairs: o new => $hashref o For internal rendering of HTML $$hashref{table} is used to specify parameters for the "table" tag. Currently, "table" is the only tag supported by this mechanism. o When using HTML::Table, for external rendering of HTML $hashref is passed to the HTML::Table constructor. o When using Text::CSV, for external rendering of CSV $hashref is passed to the Text::CSV constructor. o When using Text::UnicodeBox::Table, for external rendering of boxes $hashref is passed to the Text::UnicodeBox::Table constructor. See html.table.pl, internal.html.pl and text.csv.pl, all in the scripts/ directory. What are the constants for handling cell values which are undef? The parameter to "undef([$undef])" must be one of the following: o undef_as_empty => 0 Convert undef cell values to the empty string (''). o undef_as_minus => 1 Convert undef cell values to '-'. o undef_as_text => 2 Convert undef cell values to the text string 'undef'. o undef_as_undef => 3 Do nothing. This is the default. See also "empty([$undef])". Warning: This updates the original data! Will you extend the program to support other external renderers? Possibly, but only if the extension matches the spirit of this module, which is roughly: Keep it simple, and provide just enough options but not too many options. IOW, there is no point in passing a huge number of options to an external class when you can use that class directly anyway. I've looked a number of times at PDF::Table, for example, but it is just a little bit too complex. Similarly, Text::ANSITable has too many methods. See also "TODO". How do I run author tests? This runs both standard and author tests: 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/tr14-33.html>. Perl modules relevant to this 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 Table Rendering Any::Renderer Data::Formatter::Text Data::Tab Data::Table Data::Tabulate Gapp::TableMap HTML::Table HTML::Tabulate LaTeX::Table PDF::Table PDF::TableX PDF::Report::Table Table::Simple Term::TablePrint Text::ANSITable Text::ASCIITable Text::CSV Text::FormatTable Text::MarkdownTable Text::SimpleTable Text::Table Text::Table::Tiny Text::TabularDisplay Text::Tabulate Text::UnicodeBox Text::UnicodeBox::Table Text::UnicodeTable::Simple Tie::Array::CSV Line Breaking Text::Format Text::LineFold Text::NWrap Text::Wrap Text::WrapI18N Machine-Readable Change Log The file Changes was converted into Changelog.ini by Module::Metadata::Changes. Version Numbers Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions. Repository <https://github.com/ronsavage/Text-Table-Manifold> Support Email the author, or log a bug on RT: <https://rt.cpan.org/Public/Dist/Display.html?Name=Text::Table::Manifold>. Author Text::Table::Manifold was written by Ron Savage _ron@savage.net.au_ in 2015. Marpa's homepage: <http://savage.net.au/Marpa.html>. My homepage: <http://savage.net.au/>. Copyright Australian copyright (c) 2014, Ron Savage. All Programs of mine are 'OSI Certified Open Source Software'; you can redistribute them and/or modify them under the terms of The Artistic License 2.0, a copy of which is available at: http://opensource.org/licenses/alphabetical. perl v5.24.1 2015-02-01 Text::Table::Manifold(3)
NAME | Synopsis | Description | Distributions | Installation | Constructor and Initialization | Methods | FAQ | TODO | See Also | Machine-Readable Change Log | Version Numbers | Repository | Support | Author | Copyright
Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Text::Table::Manifold&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>