Provided by: libtext-table-perl_1.132-1build1_amd64 bug

NAME

       Text::Table - Organize Data in Tables

VERSION

       version 1.132

SYNOPSIS

           use Text::Table;
           my $tb = Text::Table->new(
               "Planet", "Radius\nkm", "Density\ng/cm^3"
           );
           $tb->load(
               [ "Mercury", 2360, 3.7 ],
               [ "Venus", 6110, 5.1 ],
               [ "Earth", 6378, 5.52 ],
               [ "Jupiter", 71030, 1.3 ],
           );
           print $tb;

       This prints a table from the given title and data like this:

         Planet  Radius Density
                 km     g/cm^3
         Mercury  2360  3.7
         Venus    6110  5.1
         Earth    6378  5.52
         Jupiter 71030  1.3

       Note that two-line titles work, and that the planet names are aligned differently than the
       numbers.

DESCRIPTION

       Organization of data in table form is a time-honored and useful method of data
       representation.  While columns of data are trivially generated by computer through
       formatted output, even simple tasks like keeping titles aligned with the data columns are
       not trivial, and the one-shot solutions one comes up with tend to be particularly hard to
       maintain.  Text::Table allows you to create and maintain tables that adapt to alignment
       requirements as you use them.

   Overview
       The process is simple: you create a table (a Text::Table object) by describing the columns
       the table is going to have.  Then you load lines of data into the table, and finally print
       the resulting output lines.  Alignment of data and column titles is handled dynamically in
       dependence on the data present.

   Table Creation
       In the simplest case, if all you want is a number of (untitled) columns, you create an
       unspecified table and start adding data to it.  The number of columns is taken from the
       first line of data.

       To specify a table you specify its columns.  A column description can contain a title and
       alignment requirements for the data, both optional.  Additionally, you can specify how the
       title is aligned with the body of a column, and how the lines of a multiline title are
       aligned among themselves.

       The columns are collected in the table in the order they are given.  On data entry, each
       column corresponds to one data item, and in column selection columns are indexed left to
       right, starting from 0.

       Each title can be a multiline string which will be blank-filled to the length of the
       longest partial line.  The largest number of title lines in a column determines how many
       title lines the table has as a whole, including the case that no column has any titles.

       On output, Columns are separated by a single blank.  You can control what goes between
       columns by specifying separators between (or before, or after) columns.  Separators don't
       contain any data and don't count in column indexing.  They also don't accumulate: in a
       sequence of only separators and no columns, only the last one counts.

   Status Information
       The width (in characters), height (in lines), number of columns, and similar data about
       the table is available.

   Data Loading
       Table data is entered line-wise, each time specifying data entries for all table columns.
       A bulk loader for many lines at once is also available.  You can clear the data from the
       table for re-use (though you will more likely just create another table).

       Data can contain colorizing escape sequences (as provided by "Term::AnsiColor") without
       upsetting the alignment.

   Table Output
       The output area of a table is divided in the title and the body.

       The title contains the combined titles from the table columns, if any.  Its content never
       changes with a given table, but it may be spread out differently on the page through
       alignment with the data.

       The body contains the data lines, aligned column-wise as specified, and left-aligned with
       the column title.

       Each of these is arranged like a Perl array (counting from 0) and can be accessed in
       portions by specifying a first line and the number of following lines.  Also like an
       array, giving a negative first line counts from the end of the area.  The whole table, the
       title followed by the body, can also be accessed in this manner.

       The subdivisions are there so you can repeat the title (or parts of it) along with parts
       of the body on output, whether for screen paging or printout.

       A rule line is also available, which is the horizontal counterpart to the separator
       columns you specify with the table.  It is basically a table line as it would appear if
       all data entries in the line were empty, that is, a blank line except for where the column
       separators have non-blank entries.  If you print it between data lines, it will not
       disrupt the vertical separator structure as a plain blank line would.  You can also
       request a solid rule consisting of any character, and even one with the non-blank column
       separators replaced by a character of your choice.  This way you can get the popular
       representation of line-crossings like so:

             |
         ----+---
             |

   Warning Control
       On table creation, some parameters are checked and warnings issued if you allow warnings.
       You can also turn warnings into fatal errors.

SPECIFICATIONS

   Column Specification
       Each column specification is a single scalar.  Columns can be either proper data columns
       or column separators.  Both can be specified either as (possibly multi-line) strings, or
       in a more explicit form as hash-refs.  In the string form, proper columns are given as
       plain strings, and separators are given as scalar references to strings.  In hash form,
       separators have a true value in the field "is_sep" while proper columns don't have this
       field.

       Columns as strings
           A column is given as a column title (any number of lines), optionally followed by
           alignment requirements.  Alignment requirements start with a line that begins with an
           ampersand "&".  However, only the last such line counts as such, so if you have title
           lines that begin with "&", just append an ampersand on a line by itself as a dummy
           alignment section if you don't have one anyway.

           What follows the ampersand on its line is the alignment style (like left, right, ...
           as described in "Alignment"), you want for the data in this column.  If nothing
           follows, the general default auto is used.  If you specify an invalid alignment style,
           it falls back to left alignment.

           The lines that follow can contain sample data for this column.  These are considered
           for alignment in the column, but never actually appear in the output.  The effect is
           to guarantee a minimum width for the column even if the current data doesn't require
           it.  This helps dampen the oscillations in the appearance of dynamically aligned
           tables.

       Columns as Hashes
           The format is

               {
                   title   => $title,
                   align   => $align,
                   sample  => $sample,
                   align_title => $align_title,
                   align_title_lines => $align_title_lines,
               }

           $title contains the title lines and $sample the sample data.  Both can be given as a
           string or as an array-ref to the list of lines.  $align contains the alignment style
           (without a leading ampersand), usually as a string.  You can also give a regular
           expression here, which specifies regex alignment.  A regex can only be specified in
           the hash form of a column specification.

           In hash form you can also specify how the title of a column is aligned with its body.
           To do this, you specify the keyword "align_title" with "left", "right" or "center".
           Other alignment specifications are not valid here.  The default is "left".

           "align_title" also specifies how the lines of a multiline title are aligned among
           themselves.  If you want a different alignment, you can specify it with the key
           "align_title_lines".  Again, only "left", "right" or "center" are allowed.

           Do not put other keys than those mentioned above (title, align, align_title,
           align_title_lines, and sample) into a hash that specifies a column.  Most would be
           ignored, but some would confuse the interpreter (in particular, is_sep has to be
           avoided).

       Separators as strings
           A separator must be given as a reference to a string (often a literal, like "\' | '"),
           any string that is given directly describes a column.

           It is usually just a (short) string that will be printed between table columns on all
           table lines instead of the default single blank.  If you specify two separators (on
           two lines), the first one will be used in the title and the other in the body of the
           table.

       Separators as Hashes
           The hash representation of a separator has the format

               {
                   is_sep => 1,
                   title  => $title,
                   body   => $body,
               }

           $title is the separator to be used in the title area and $body the one for the body.
           If only one is given, the other is used for both.  If none is given, a blank is used.
           If one is shorter than the other, it is blank filled on the right.

           The value of "is_sep" must be set to a true value, this is the distinguishing feature
           of a separator.

   Alignment
       The original documentation to Text::Aligner contains all the details on alignment
       specification, but here is the rundown:

       The possible alignment specifications are left, right, center, num and point (which are
       synonyms), and auto.  The first three explain themselves.

       num (and point) align the decimal point in the data, which is assumed to the right if none
       is present.  Strings that aren't numbers are treated the same way, that is, they appear
       aligned with the integers unless they contain a ".".  Instead of the decimal point ".",
       you can also specify any other string in the form num(,), for instance.  The string in
       parentheses is aligned in the data.  The synonym point for num may be more appropriate in
       contexts that deal with arbitrary strings, as in point(=>) (which might be used to align
       certain bits of Perl code).

       regex alignment is a more sophisticated form of point alignment.  If you specify a regular
       expression, as delivered by "qr//", the start of the match is used as the alignment point.
       If the regex contains capturing parentheses, the last submatch counts.  [The usefulness of
       this feature is under consideration.]

       auto alignment combines numeric alignment with left alignment.  Data items that look like
       numbers, and those that don't, form two virtual columns and are aligned accordingly: "num"
       for numbers and "left" for other strings.  These columns are left-aligned with each other
       (i.e. the narrower one is blank-filled) to form the final alignment.

       This way, a column that happens to have only numbers in the data gets num alignment, a
       column with no numbers appears left-aligned, and mixed data is presented in a reasonable
       way.

   Column Selection
       Besides creating tables from scratch, they can be created by selecting columns from an
       existing table.  Tables created this way contain the data from the columns they were built
       from.

       This is done by specifying the columns to select by their index (where negative indices
       count backward from the last column).  The same column can be selected more than once and
       the sequence of columns can be arbitrarily changed.  Separators don't travel with columns,
       but can be specified between the columns at selection time.

       You can make the selection of one or more columns dependent on the data content of one of
       them.  If you specify some of the columns in angle brackets [...], the whole group is only
       included in the selection if the first column in the group contains any data that
       evaluates to boolean true.  That way you can de-select parts of a table if it contains no
       interesting data.  Any column separators given in brackets are selected or deselected
       along with the rest of it.

PUBLIC METHODS

   Table Creation
       new()
               my $tb = Text::Table->new( $column, ... );

           creates a table with the columns specified.  A column can be proper column which
           contains and displays data, or a separator which tells how to fill the space between
           columns.  The format of the parameters is described under "Column Specification".
           Specifying an invalid alignment for a column results in a warning if these are
           allowed.

           If no columns are specified, the number of columns is taken from the first line of
           data added to the table.  The effect is as if you had specified "Text::Table->new( (
           '') x $n)", where $n is the number of columns.

       select()
               my $sub = $tb->select( $column, ...);

           creates a table from the listed columns of the table $tb, including the data.  Columns
           are specified as integer indices which refer to the data columns of $tb.  Columns can
           be repeated and specified in any order.  Negative indices count from the last column.
           If an invalid index is specified, a warning is issued, if allowed.

           As with "new()", separators can be interspersed among the column indices and will be
           used between the columns of the new table.

           If you enclose some of the arguments (column indices or separators) in angle brackets
           "[...]" (technically, you specify them inside an arrayref), they form a group for
           conditional selection.  The group is only included in the resulting table if the first
           actual column inside the group contains any data that evaluate to a boolean true.
           This way you can exclude groups of columns that wouldn't contribute anything
           interesting.  Note that separators are selected and de-selected with their group.
           That way, more than one separator can appear between adjacent columns.  They don't add
           up, but only the rightmost separator is used.  A group that contains only separators
           is never selected.  [Another feature whose usefulness is under consideration.]

   Status Information
       n_cols()
               $tb->n_cols

           returns the number of columns in the table.

       width()
               $tb->width

           returns the width (in characters) of the table.  All table lines have this length (not
           counting a final "\n" in the line), as well as the separator lines returned by
           $tb->rule() and $b->body_rule().  The width of a table can potentially be influenced
           by any data item in it.

       height()
               $tb->height

           returns the total number of lines in a table, including title lines and body lines.
           For orthogonality, the synonym table_height() also exists.

       table_height()
           Same as "$table->height()".

       title_height()
               $tb->title_height

           returns the number of title lines in a table.

       body_height()
               $tb->body_height

           returns the number of lines in the table body.

       colrange()
               $tb->colrange( $i)

           returns the start position and width of the $i-th column (counting from 0) of the
           table.  If $i is negative, counts from the end of the table.  If $i is larger than the
           greatest column index, an imaginary column of width 0 is assumed right of the table.

   Data Loading
       add()
               $tb->add( $col1, ..., $colN)

           adds a data line to the table, returns the table.

           $col1, ..., $colN are scalars that correspond to the table columns.  Undefined entries
           are converted to '', and extra data beyond the number of table columns is ignored.

           Data entries can be multi-line strings.  The partial strings all go into the same
           column.  The corresponding fields of other columns remain empty unless there is
           another multi-line entry in that column that fills the fields.  Adding a line with
           multi-line entries is equivalent to adding multiple lines.

           Every call to add() increases the body height of the table by the number of effective
           lines, one in the absence of multiline entries.

       load()
               $tb->load( $line, ...)

           loads the data lines given into the table, returns the table.

           Every argument to load() represents a data line to be added to the table.  The line
           can be given as an array(ref) containing the data items, or as a string, which is
           split on whitespace to retrieve the data.  If an undefined argument is given, it is
           treated as an empty line.

       clear()
               $tb->clear;

           deletes all data from the table and resets it to the state after creation.  Returns
           the table.  The body height of a table is 0 after clear().

   Table Output
       The three methods table(), title(), and body() are very similar.  They access different
       parts of the printable output lines of a table with similar methods.  The details are
       described with the table() method.

       table()
           The table() method returns lines from the entire table, starting with the first title
           line and ending with the last body line.

           In array context, the lines are returned separately, in scalar context they are joined
           together in a single string.

               my @lines = $tb->table;
               my $line  = $tb->table( $line_number);
               my @lines = $tb->table( $line_number, $n);

           The first call returns all the lines in the table.  The second call returns one line
           given by $line_number.  The third call returns $n lines, starting with $line_number.
           If $line_number is negative, it counts from the end of the array.  Unlike the select()
           method, table() (and its sister methods title() and body()) is protected against large
           negative line numbers, it truncates the range described by $line_number and $n to the
           existing lines.  If $n is 0 or negative, no lines are returned (an empty string in
           scalar context).

       stringify()
           Returns a string representation of the table. This method is called for
           stringification by overload.

               my @table_strings = map { $_->stringify() } @tables;

       title()
           Returns lines from the title area of a table, where the column titles are rendered.
           Parameters and response to context are as with table(), but no lines are returned from
           outside the title area.

       body()
           Returns lines from the body area of a table, that is the part where the data content
           is rendered, so that $tb->body( 0) is the first data line.  Parameters and response to
           context are as with table().

       rule()
               $tb->rule;
               $tb->rule( $char);
               $tb->rule( $char, $char1);
               $tb->rule( sub { my ($index, $len) = @_; },
                          sub { my ($index, $len) = @_; },
               );

           Returns a rule for the table.

           A rule is a line of table width that can be used between table lines to provide visual
           horizontal divisions, much like column separators provide vertical visual divisions.
           In its basic form (returned by the first call) it looks like a table line with no
           data, hence a blank line except for the non-blank parts of any column-separators.  If
           one character is specified (the second call), it replaces the blanks in the first
           form, but non-blank column separators are retained.  If a second character is
           specified, it replaces the non-blank parts of the separators.  So specifying the same
           character twice gives a solid line of table width.  Another useful combo is
           "$tb->rule( '-', '+')", together with separators that contain a single nonblank "|",
           for a popular representation of line crossings.

           rule() uses the column separators for the title section if there is a difference.

           If callbacks are specified instead of the characters, then they receive the index of
           the section of the rule they need to render and its desired length in characters, and
           should return the string to put there. The indexes given are 0 based (where 0 is
           either the left column separator or the leftmost cell) and the strings will be trimmed
           or extended in the replacement.

       body_rule()
           body_rule() works like <rule()>, except the rule is generated using the column
           separators for the table body.

   Warning Control
       warnings()
               Text::Table->warnings();
               Text::Table->warnings( 'on');
               Text::Table->warnings( 'off'):
               Text::Table->warnings( 'fatal'):

           The warnings() method is used to control the appearance of warning messages while
           tables are manipulated.  When Text::Table starts, warnings are disabled.  The default
           action of warnings() is to turn warnings on.  The other possible arguments are self-
           explanatory.  warnings() can also be called as an object method ("$tb->warnings(
           ...)").

VERSION

       This document pertains to Text::Table version 1.127

BUGS

       o   auto alignment doesn't support alternative characters for the decimal point.  This is
           actually a bug in the underlying Text::Aligner by the same author.

AUTHOR

   MAINTAINER
       Shlomi Fish, <http://www.shlomifish.org/> - CPAN ID: "SHLOMIF".

   ORIGINAL AUTHOR
           Anno Siegel
           CPAN ID: ANNO
           siegel@zrz.tu-berlin.de
           http://www.tu-berlin.de/~siegel

COPYRIGHT

       Copyright (c) 2002 Anno Siegel. All rights reserved.  This program is free software; you
       can redistribute it and/or modify it under the terms of the ISC license.

       (This program had been licensed under the same terms as Perl itself up to version 1.118
       released on 2011, and was relicensed by permission of its originator).

       The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

       Text::Aligner, perl(1) .

AUTHOR

       Shlomi Fish <shlomif@cpan.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2002 by Anno Siegel and others.

       This is free software, licensed under:

         The ISC License

BUGS

       Please report any bugs or feature requests on the bugtracker website
       http://rt.cpan.org/NoAuth/Bugs.html?Dist=Text-Table or by email to
       bug-text-table@rt.cpan.org.

       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.

SUPPORT

   Perldoc
       You can find documentation for this module with the perldoc command.

         perldoc Text::Table

   Websites
       The following websites have more information about this module, and may be of help to you.
       As always, in addition to those websites please use your favorite search engine to
       discover more resources.

       •   MetaCPAN

           A modern, open-source CPAN search engine, useful to view POD in HTML format.

           <http://metacpan.org/release/Text-Table>

       •   Search CPAN

           The default CPAN search engine, useful to view POD in HTML format.

           <http://search.cpan.org/dist/Text-Table>

       •   RT: CPAN's Bug Tracker

           The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.

           <https://rt.cpan.org/Public/Dist/Display.html?Name=Text-Table>

       •   AnnoCPAN

           The AnnoCPAN is a website that allows community annotations of Perl module
           documentation.

           <http://annocpan.org/dist/Text-Table>

       •   CPAN Ratings

           The CPAN Ratings is a website that allows community ratings and reviews of Perl
           modules.

           <http://cpanratings.perl.org/d/Text-Table>

       •   CPAN Forum

           The CPAN Forum is a web forum for discussing Perl modules.

           <http://cpanforum.com/dist/Text-Table>

       •   CPANTS

           The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.

           <http://cpants.cpanauthors.org/dist/Text-Table>

       •   CPAN Testers

           The CPAN Testers is a network of smokers who run automated tests on uploaded CPAN
           distributions.

           <http://www.cpantesters.org/distro/T/Text-Table>

       •   CPAN Testers Matrix

           The CPAN Testers Matrix is a website that provides a visual overview of the test
           results for a distribution on various Perls/platforms.

           <http://matrix.cpantesters.org/?dist=Text-Table>

       •   CPAN Testers Dependencies

           The CPAN Testers Dependencies is a website that shows a chart of the test results of
           all dependencies for a distribution.

           <http://deps.cpantesters.org/?module=Text::Table>

   Bugs / Feature Requests
       Please report any bugs or feature requests by email to "bug-text-table at rt.cpan.org", or
       through the web interface at
       <https://rt.cpan.org/Public/Bug/Report.html?Queue=Text-Table>. You will be automatically
       notified of any progress on the request by the system.

   Source Code
       The code is open to the world, and available for you to hack on. Please feel free to
       browse it and play with it, or whatever. If you want to contribute patches, please send me
       a diff or prod me to pull from your repository :)

       <https://github.com/shlomif/perl-Text-Table>

         git clone ssh://git@github.com:shlomif/perl-Text-Table.git