NAME¶
Text::Table - Organize Data in Tables
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 fronm 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.
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 ampersamd "&". 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 colunm
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.]
- 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 fieds.
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.121
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) .