Text::ANSITable - Create a nice formatted table using extended ASCII and ANSI colors
version 0.26
use 5.010; use Text::ANSITable; # don't forget this if you want to output utf8 characters binmode(STDOUT, ":utf8"); my $t = Text::ANSITable->new; # set styles $t->border_style('Default::bold'); # if not, a nice default is picked $t->color_theme('Default::sepia'); # if not, a nice default is picked # fill data $t->columns(["name", "color", "price"]); $t->add_row(["chiki" , "yellow", 2000]); $t->add_row(["lays" , "green" , 7000]); $t->add_row(["tao kae noi", "blue" , 18500]); # draw it! say $t->draw;
Samples of output:
This module is yet another text table formatter module like Text::ASCIITable or Text::SimpleTable, with the following differences:
Colors and color themes
ANSI color codes will be used by default (even 256 and 24bit colors), but will degrade to lower color depth and black/white according to terminal support.
Box-drawing characters
Box-drawing characters will be used by default, but will degrade to using normal ASCII characters if terminal does not support them.
Unicode and wide character support
Border styles using Unicode characters (double lines, bold/heavy lines, brick style, etc). Columns containing wide characters stay aligned.
Compared to Text::ASCIITable, it uses lower_case method/attr names instead of CamelCase, and it uses arrayref for columns and add_row. When specifying border styles, the order of characters are slightly different. More fine-grained options to customize appearance.
lower_case
CamelCase
columns
add_row
It uses Moo object system.
To list available border styles:
say $_ for $t->list_border_styles;
Or you can also try out borders using the provided ansitable-list-border-styles script. Or, you can also view the documentation for the Text::ANSITable::BorderStyle::* modules, where border styles are searched.
Text::ANSITable::BorderStyle::*
To choose border style, either set the border_style attribute to an available border style or a border specification directly.
border_style
$t->border_style("Default::singleh_boxchar"); $t->border_style("Foo::bar"); # dies, no such border style $t->border_style({ ... }); # set specification directly
If no border style is selected explicitly, a nice default will be chosen. You can also set the ANSITABLE_BORDER_STYLE environment variable to set the default.
ANSITABLE_BORDER_STYLE
To create a new border style, create a module under Text::ANSITable::BorderStyle::. Please see one of the existing border style modules for example, like Text::ANSITable::BorderStyle::Default. For more about border styles, refer to SHARYANTO::Role::BorderStyle.
Text::ANSITable::BorderStyle::
To list available color themes:
say $_ for $t->list_color_themes;
Or you can also run the provided ansitable-list-color-themes script. Or you can view the documentation for the Text::ANSITable::ColorTheme::* modules where color themes are searched.
Text::ANSITable::ColorTheme::*
To choose a color theme, either set the color_theme attribute to an available color theme or a color theme specification directly.
color_theme
$t->color_theme("Default::default_nogradation"); $t->color_theme("Foo::bar"); # dies, no such color theme $t->color_theme({ ... }); # set specification directly
If no color theme is selected explicitly, a nice default will be chosen. You can also set the ANSITABLE_COLOR_THEME environment variable to set the default.
ANSITABLE_COLOR_THEME
To create a new color theme, create a module under Text::ANSITable::ColorTheme::. Please see one of the existing color theme modules for example, like Text::ANSITable::ColorTheme::Default. For more about color themes, refer to SHARYANTO::Role::ColorTheme.
Text::ANSITable::ColorTheme::
By default column width is set just so it is enough to show the widest data. This can be customized in the following ways (in order of precedence, from lowest):
table-level cell_width attribute
cell_width
This sets width for all columns.
per-column width style
width
$t->set_column_style('colname', width => 20);
You can use negative number to mean minimum width.
This can be customized in the following ways (in order of precedence, from lowest):
table-level cell_height attribute
cell_height
This sets height for all rows.
per-row height style
height
$t->set_row_style(1, height => 2);
You can use negative number to mean minimum height.
By default cell (horizontal) padding is 1. This can be customized in the following ways (in order of precedence, from lowest):
table-level cell_pad attribute
cell_pad
This sets left and right padding for all columns.
table-level cell_lpad and cell_rpad attributes
cell_lpad
cell_rpad
They set left and right padding for all columns, respectively.
per-column pad style
pad
$t->set_column_style($colname, pad => 0);
per-column lpad/rpad style
lpad
rpad
$t->set_column_style($colname, lpad => 1); $t->set_column_style($colname, rpad => 2);
Default vertical padding is 0. This can be changed in the following ways (in order of precedence, from lowest):
table-level row_vpad attribute
row_vpad
This sets top and bottom padding for all rows.
table-level row_tpad/row_bpad attributes
row_tpad
row_bpad
They set top/bottom padding separately for all rows.
per-row vpad style
vpad
Example:
$t->set_row_style($rownum, vpad => 1);
When adding row:
$t->add_row($rownum, {vpad=>1});
per-row tpad/vpad style
tpad
$t->set_row_style($row_num, tpad => 1); $t->set_row_style($row_num, bpad => 2);
$t->add_row($row, {tpad=>1, bpad=>2});
By default data format colors are used, e.g. cyan/green for text (using the default color scheme, items num_data, bool_data, etc). In absense of that, cell_fgcolor and cell_bgcolor from the color scheme are used. You can customize colors in the following ways (ordered by precedence, from lowest):
num_data
bool_data
cell_fgcolor
cell_bgcolor
table-level cell_fgcolor and cell_bgcolor attributes
Sets all cells' colors. Color should be specified using 6-hexdigit RGB which will be converted to the appropriate terminal color.
Can also be set to a coderef which will receive ($rownum, $colname) and should return an RGB color.
per-column fgcolor and bgcolor styles
fgcolor
bgcolor
$t->set_column_style('colname', fgcolor => 'fa8888'); $t->set_column_style('colname', bgcolor => '202020');
per-row fgcolor and bgcolor styles
$t->set_row_style($rownum, {fgcolor => 'fa8888', bgcolor => '202020'});
When adding row/rows:
$t->add_row($row, {fgcolor=>..., bgcolor=>...}); $t->add_rows($rows, {bgcolor=>...});
per-cell fgcolor and bgcolor styles
$t->set_cell_style($rownum, $colname, fgcolor => 'fa8888'); $t->set_cell_style($rownum, $colname, bgcolor => '202020');
For flexibility, all colors can be specified as coderef. See "COLOR THEMES" for more details.
By default, numbers are right-aligned, dates and bools are centered, and the other data types (text including) are left-aligned. All data are top-valigned. This can be customized in the following ways (in order of precedence, from lowest):
table-level cell_align and cell_valign attribute
cell_align
cell_valign
per-column align and valign styles
align
valign
$t->set_column_style($colname, align => 'middle'); # or left, or right $t->set_column_style($colname, valign => 'top'); # or bottom, or middle
per-row align and valign styles
per-cell align and valign styles
$t->set_cell_style($rownum, $colname, align => 'middle'); $t->set_cell_style($rownum, $colname, valign => 'top');
The per-column and per-cell formats styles regulate how to format data. The value for this style setting will be passed to Data::Unixish::Apply's apply(), as the functions argument. So it should be a single string (like date) or an array (like ['date', ['centerpad', {width=>20}]]).
formats
apply()
functions
date
['date', ['centerpad', {width=>20}]]
See Data::Unixish or install App::dux and then run dux -l to see what functions are available. Functions of interest to formatting data include: bool, num, sprintf, sprintfn, wrap, (among others).
dux -l
bool
num
sprintf
sprintfn
wrap
Store column names. Note that when drawing, you can omit some columns, reorder them, or display some more than once (see column_filter attribute).
column_filter
Store row data. You can set this attribute directly, or add rows incrementally using add_row() and add_rows() methods.
add_row()
add_rows()
When drawing, only show rows that match this. Can be an array containing indices of rows which should be shown, or a coderef which will be called for each row with arguments ($row, $row_num) and should return a bool value indicating whether that row should be displayed.
($row, $row_num)
Internal note: During drawing, rows will be filtered and put into $t->{_draw}{frows}.
$t->{_draw}{frows}
When drawing, only show columns that match this. Can be an array containing names of columns that should be displayed (column names can be in different order or duplicate, column can also be referred to with its numeric index). Can also be a coderef which will be called with ($col_name, $col_num) for every column and should return a bool value indicating whether that column should be displayed. The coderef version is more limited in that it cannot reorder the columns or instruct for the same column to be displayed more than once.
($col_name, $col_num)
Internal note: During drawing, column names will be filtered and put into $t->{_draw}{fcols}.
$t->{_draw}{fcols}
Set column wrapping for all columns. Can be overriden by per-column wrap style. By default column wrapping will only be done for text columns and when width is explicitly set to a positive value.
Whether to output color. Default is taken from COLOR environment variable, or detected via (-t STDOUT). If use_color is set to 0, an attempt to use a colored color theme (i.e. anything that is not the no_color theme) will result in an exception.
COLOR
(-t STDOUT)
use_color
no_color
(In the future, setting use_color to 0 might opt the module to use normal/plain string routines instead of the slower ta_* functions from Text::ANSI::Util; this also means that the module won't handle ANSI escape codes in the content text.)
Terminal's color depth. Either 16, 256, or 2**24 (16777216). Default will be retrieved from COLOR_DEPTH environment or detected using Term::Detect.
COLOR_DEPTH
Whether to use box drawing characters. Drawing box drawing characters can be problematic in some places because it uses ANSI escape codes to switch to (and back from) line drawing mode ("\e(0" and "\e(B", respectively).
"\e(0"
"\e(B"
Default is taken from BOX_CHARS environment variable, or 1. If use_box_chars is set to 0, an attempt to use a border style that uses box drawing chararacters will result in an exception.
BOX_CHARS
use_box_chars
Whether to use Unicode (UTF8) characters. Default is taken from UTF8 environment variable, or detected using Term::Detect, or guessed via LANG environment variable. If use_utf8 is set to 0, an attempt to select a border style that uses Unicode characters will result in an exception.
UTF8
use_utf8
(In the future, setting use_utf8 to 0 might opt the module to use the non-"mb_*" version of functions from Text::ANSI::Util, e.g. ta_wrap() instead of ta_mbwrap(), and so on).
ta_wrap()
ta_mbwrap()
Border style specification to use.
You can set this attribute's value with a specification or border style name. See "BORDER STYLES"" in " for more details.
Some border styles can accept arguments. You can set it here. See the corresponding border style's documentation for information on what arguments it accepts.
Color theme specification to use.
You can set this attribute's value with a specification or color theme name. See "COLOR THEMES"" in " for more details.
Some color themes can accept arguments. You can set it here. See the corresponding color theme's documentation for information on what arguments it accepts.
When drawing, whether to show header.
When drawing, whether to show separator lines between rows. The default (2) is to only show separators drawn using add_row_separator(). If you set this to 1, lines will be drawn after every data row. If you set this attribute to 0, no lines will be drawn whatsoever.
add_row_separator()
Set width for all cells. Can be overriden by per-column width style.
Set height for all cell. Can be overriden by per-row height style.
Set (horizontal) alignment for all cells. Either left, middle, or right. Can be overriden by per-column/per-row/per-cell align style.
left
middle
right
Set (horizontal) alignment for all cells. Either top, middle, or bottom. Can be overriden by per-column/per-row/per-cell align style.
top
bottom
Set (horizontal) padding for all cells. Can be overriden by per-column pad style.
Set left padding for all cells. Overrides the cell_pad attribute. Can be overriden by per-column lpad style.
Set right padding for all cells. Overrides the cell_pad attribute. Can be overriden by per-column rpad style.
Set vertical padding for all cells. Can be overriden by per-row vpad style.
Set top padding for all cells. Overrides the cell_vpad attribute. Can be overriden by per-row tpad style.
cell_vpad
Set bottom padding for all cells. Overrides the cell_vpad attribute. Can be overriden by per-row bpad style.
bpad
Set foreground color for all cells. Value should be 6-hexdigit RGB. Can also be a coderef that will receive %args (e.g. row_num, col_name, col_num) and should return an RGB color. Can be overriden by per-cell fgcolor style.
Like cell_fgcolor but for background color.
Set foreground color for all headers. Overrides cell_fgcolor for headers. Value should be a 6-hexdigit RGB. Can also be a coderef that will receive %args (e.g. col_name, col_num) and should return an RGB color.
Like header_fgcolor but for background color.
header_fgcolor
Constructor.
Return the names of available border styles. Border styles will be searched in Text::ANSITable::BorderStyle::* modules.
Return the names of available color themes. Color themes will be searched in Text::ANSITable::ColorTheme::* modules.
Can also be called as a static method: Text::ANSITable->get_border_style($name).
Text::ANSITable->get_border_style($name)
Can also be called as a static method: Text::ANSITable->get_color_theme($name).
Text::ANSITable->get_color_theme($name)
Add a row. Note that row data is not copied, only referenced.
Can also add per-row styles (which can also be done using row_style()).
row_style()
Add multiple rows. Note that row data is not copied, only referenced.
Add a row separator line.
Get cell value at row #$row_num (starts from zero) and column named/numbered $col.
$row_num
$col
Set cell value at row #$row_num (starts from zero) and column named/numbered $col. Return old value.
Get per-column style for column named/numbered $col.
Set per-column style(s) for column named/numbered $col. Available values for $style: align, valign, pad, lpad, rpad, width, formats, fgcolor, bgcolor, type, wrap.
$style
type
Get per-row style for row numbered $row_num.
Set per-row style(s) for row numbered $row_num. Available values for $style: align, valign, height, vpad, tpad, bpad, fgcolor, bgcolor.
Get per-cell style.
Set per-cell style(s). Available values for $style: align, valign, formats, fgcolor, bgcolor.
Render table.
Can be used to set default value for the color attribute.
color
Can be used to set default value for the color_depth attribute.
color_depth
Can be used to set default value for the box_chars attribute.
box_chars
Can be used to set default value for the utf8 attribute.
utf8
Can be used to override terminal width detection.
Can be used to set default value for border_style attribute.
Can be used to set table's most attributes. Value should be a JSON-encoded hash of attr => val pairs. Example:
attr => val
% ANSITABLE_STYLE='{"show_row_separator":1}' ansitable-list-border-styles
will display table with row separator lines after every row.
Can be used to set per-column styles. Interpreted right before draw(). Value should be a JSON-encoded hash of col => {style => val, ...} pairs. Example:
col => {style => val, ...}
% ANSITABLE_COLUMN_STYLES='{"2":{"type":"num"},"3":{"type":"str"}}' ansitable-list-border-styles
will display the bool columns as num and str instead.
Can be used to set per-row styles. Interpreted right before draw(). Value should be a JSON-encoded a hash of row_num => {style => val, ...} pairs. Example:
row_num => {style => val, ...}
% ANSITABLE_ROW_STYLES='{"0":{"bgcolor":"000080","vpad":1}}' ansitable-list-border-styles
will display the first row with blue background color and taller height.
Can be used to set per-cell styles. Interpreted right before draw(). Value should be a JSON-encoded a hash of "row_num,col" => {style => val, ...} pairs. Example:
"row_num,col" => {style => val, ...}
% ANSITABLE_CELL_STYLES='{"1,1":{"bgcolor":"008000"}}' ansitable-list-border-styles
will display the second-on-the-left, second-on-the-top cell with green background color.
$t->use_utf8(0); $t->use_box_chars(0); $t->use_color(0); $t->border_style('Default::single_ascii');
and you're good to go. Alternatively you can set environment UTF8=0, BOX_CHARS=0, COLOR=0, and ANSITABLE_BORDER_STYLE=Default::single_ascii.
You are probably using a utf8 border style, and you haven't done something like this to your output:
binmode(STDOUT, ":utf8");
That's because less by default escapes ANSI color and box_char codes. Try using -R option of less to display ANSI color codes raw.
-R
Or, try not using colors and box_char border styles:
$t->use_color(0); $t->use_box_chars(0);
Note that as of this writing, less -R does not interpret box_char codes so you'll need to avoid using box_char border styles if you want your output to display properly under less.
Use the column_filter and row_filter attributes. For example, given this table:
row_filter
my $t = Text::ANSITable->new; $t->columns([qw/one two three/]); $t->add_row([$_, $_, $_]) for 1..10;
Doing this:
$t->row_filter([0, 1, 4]); print $t->draw;
will show:
one | two | three -----+-----+------- 1 | 1 | 1 2 | 2 | 2 5 | 5 | 5
$t->row_filter(sub { my ($row, $idx) = @_; $row->[0] % 2 }
will display:
one | two | three -----+-----+------- 1 | 1 | 1 3 | 3 | 3 5 | 5 | 5 7 | 7 | 7 9 | 9 | 9
$t->column_filter([qw/two one 0/]);
two | one | one -----+-----+----- 1 | 1 | 1 2 | 2 | 2 3 | 3 | 3 4 | 4 | 4 5 | 5 | 5 6 | 6 | 6 7 | 7 | 7 8 | 8 | 8 9 | 9 | 9 10 | 10 | 10
$t->column_filter(sub { my ($colname, $idx) = @_; $colname =~ /t/ });
two | three -----+------- 1 | 1 2 | 2 3 | 3 4 | 4 5 | 5 6 | 6 7 | 7 8 | 8 9 | 9 10 | 10
Use the formats per-column style or per-cell style. For example:
$t->set_column_style('available', formats => [[bool=>{style=>'check_cross'}], [centerpad=>{width=>10}]]); $t->set_column_style('amount' , formats => [[num=>{decimal_digits=>2}]]); $t->set_column_style('size' , formats => [[num=>{style=>'kilo'}]]);
See Data::Unixish::Apply and Data::Unixish for more details on the available formatting functions.
Currently: if column name has the word date or time in it, the column is assumed to contain date data. If column name has ? in it, the column is assumed to be bool. If a column contains only numbers (or undefs), it is num. Otherwise, it is str.
time
?
Currently: num will be right aligned and applied num_data color (cyan in the default theme). date will be centered and applied date_data color (gold in the default theme). bool will be centered and formatted as check/cross symbol and applied bool_data color (red/green depending on whether the data is false/true). str will be applied str_data color (no color in the default theme).
date_data
str_data
Other color themes might use different colors.
For example, you have a column named deleted but want to display it as bool. You can do:
deleted
$t->set_column_type(deleted => type => 'bool');
The wrap dux function can be used to wrap text (see: Data::Unixish::wrap). You'll want to set ansi and mb both to 1 to handle ANSI escape codes and wide characters in your text (unless you are sure that your text does not contain those):
ansi
mb
$t->set_column_style('description', formats=>[[wrap => {width=>60, ansi=>1, mb=>1}]]);
The ansi::highlight dux function can be used to highlight text (see: Data::Unixish::ansi::highlight).
ansi::highlight
$t->set_column_style(2, formats => [[highlight => {pattern=>$pat}]]);
By default, bool columns are shown as cross/check sign. This can be changed, e.g.:
$t->set_column_style($colname, type => 'bool', formats => [[bool => {style=>"Y_N"}]]);
See Data::Unixish::bool for more details.
There is currently no show_border attribute. Choose border styles like Default::space_ascii or Default::none_utf8:
show_border
Default::space_ascii
Default::none_utf8
$t->border_style("Default::none");
Because of the row separator, that can still be drawn if add_row_separator() is used. See next question.
The default is for separator lines to be drawn if drawn using add_row_separator(), e.g.:
$t->add_row(['row1']); $t->add_row(['row2']); $t->add_row_separator; $t->add_row(['row3']);
The result will be:
row1 row2 -------- row3
However, if you set show_row_separator to 0, no separator lines will be drawn whatsoever:
show_row_separator
row1 row2 row3
Set use_color attribute or COLOR environment to 0.
Use modules like Graphics::ColorNames.
The default is to disable colors when (-t STDOUT) is false. You can force-enable colors by setting use_color attribute or COLOR environment to 1.
Use terminal emulators that support 256 colors, e.g. Konsole, xterm, gnome-terminal, PuTTY/pterm (but the last one has minimal Unicode support). Better yet, use Konsole or Konsole-based emulators which supports 24bit colors.
Currently only Konsole and the Konsole-based Yakuake terminal emulator software support 24bit colors.
Set COLOR_DEPTH to 16.
The default color theme applies vertical color gradation to borders from white (ffffff) to gray (444444). To change this, set border1 and border2 theme arguments:
border1
border2
$t->color_theme_args({border1=>'ff0000', border2=>'00ff00'}); # red to green
Try using the "*_whitebg" themes, as the other themes are geared towards terminal emulators with black background.
Aside from doing $t->set_row_style($row_num, bgcolor=>...) for each row, you can also do this:
$t->set_row_style($row_num, bgcolor=>...)
$t->cell_bgcolor(sub { my ($self, %args) = @_; $args{row_num} % 2 ? '202020' : undef });
Most color themes still look crappy on 256 colors (I develop on Konsole).
Attributes: cell_wrap? (a shorter/nicer version for formats => [[wrap => {ansi=>1, mb=>1}]]).
Column styles: show_{left,right}_border (shorter name? {l,r}border?)
Row styles: show_{top,bottom}_border (shorter name? {t,b}border?)
row span? column span?
For collections of border styles, search for Text::ANSITable::BorderStyle::* modules.
For collections of color themes, search for Text::ANSITable::ColorTheme::* modules.
Other table-formatting modules: Text::Table, Text::SimpleTable, Text::ASCIITable (which I usually used), Text::UnicodeTable::Simple, Table::Simple (uses Moose).
Modules used: Text::ANSI::Util, Color::ANSI::Util.
Please visit the project's homepage at https://metacpan.org/release/Text-ANSITable.
Source repository is at https://github.com/sharyanto/perl-Text-ANSITable.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Text-ANSITable
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.
Steven Haryanto <stevenharyanto@gmail.com>
This software is copyright (c) 2014 by Steven Haryanto.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Text::ANSITable, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::ANSITable
CPAN shell
perl -MCPAN -e shell install Text::ANSITable
For more information on module installation, please visit the detailed CPAN module installation guide.