GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Text::ANSITable(3) User Contributed Perl Documentation Text::ANSITable(3)

Text::ANSITable - Create nice formatted tables using extended ASCII and ANSI colors

This document describes version 0.608 of Text::ANSITable (from Perl distribution Text-ANSITable), released on 2022-02-14.

 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('UTF8::SingleLineBold');  # if not, a nice default is picked
 $t->color_theme('Standard::NoGradation');  # 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!
 print $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. (Note: support for wide characters requires Text::ANSI::WideUtil which is currently set as an optional prereq, so you'll need to install it explicitly or set your CPAN client to install 'recommends' prereq).

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.

Features declared by this module:

Features from feature set PerlTrove declared by this module:
  • Development Status

    Value: "5 - Production/Stable".

  • Environment

    Value: "Console".

  • Intended Audience

    Value: ["Developers"].

  • License

    Value: "OSI Approved :: Artistic License".

  • Programming Language

    Value: "Perl".

  • Topic

    Value: ["Software Development :: Libraries :: Perl Modules","Utilities"].

Features from feature set TextTable declared by this module:
  • can_align_cell_containing_color_code

    Value: yes.

  • can_align_cell_containing_newline

    Value: yes.

  • can_align_cell_containing_wide_character

    Value: yes.

  • can_color

    Can produce colored table.

    Value: yes.

  • can_color_theme

    Allow choosing colors from a named set of palettes.

    Value: yes.

  • can_colspan

    Value: no.

  • can_customize_border

    Let user customize border character in some way, e.g. selecting from several available borders, disable border.

    Value: yes.

  • can_halign

    Provide a way for user to specify horizontal alignment (left/middle/right) of cells.

    Value: yes.

  • can_halign_individual_cell

    Provide a way for user to specify different horizontal alignment (left/middle/right) for individual cells.

    Value: yes.

  • can_halign_individual_column

    Provide a way for user to specify different horizontal alignment (left/middle/right) for individual columns.

    Value: yes.

  • can_halign_individual_row

    Provide a way for user to specify different horizontal alignment (left/middle/right) for individual rows.

    Value: yes.

  • can_hpad

    Provide a way for user to specify horizontal padding of cells.

    Value: yes.

  • can_hpad_individual_cell

    Provide a way for user to specify different horizontal padding of individual cells.

    Value: yes.

  • can_hpad_individual_column

    Provide a way for user to specify different horizontal padding of individual columns.

    Value: yes.

  • can_hpad_individual_row

    Provide a way for user to specify different horizontal padding of individual rows.

    Value: yes.

  • can_rowspan

    Value: no.

  • can_set_cell_height

    Allow setting height of rows.

    Value: yes.

  • can_set_cell_height_of_individual_row

    Allow setting height of individual rows.

    Value: yes.

  • can_set_cell_width

    Allow setting height of rows.

    Value: yes.

  • can_set_cell_width_of_individual_column

    Allow setting height of individual rows.

    Value: yes.

  • can_use_box_character

    Can use terminal box-drawing character when drawing border.

    Value: yes.

  • can_valign

    Provide a way for user to specify vertical alignment (top/middle/bottom) of cells.

    Value: yes.

  • can_valign_individual_cell

    Provide a way for user to specify different vertical alignment (top/middle/bottom) for individual cells.

    Value: yes.

  • can_valign_individual_column

    Provide a way for user to specify different vertical alignment (top/middle/bottom) for individual columns.

    Value: yes.

  • can_valign_individual_row

    Provide a way for user to specify different vertical alignment (top/middle/bottom) for individual rows.

    Value: yes.

  • can_vpad

    Provide a way for user to specify vertical padding of cells.

    Value: yes.

  • can_vpad_individual_cell

    Provide a way for user to specify different vertical padding of individual cells.

    Value: yes.

  • can_vpad_individual_column

    Provide a way for user to specify different vertical padding of individual columns.

    Value: yes.

  • can_vpad_individual_row

    Provide a way for user to specify different vertical padding of individual rows.

    Value: yes.

  • speed

    Subjective speed rating, relative to other text table modules.

    Value: "slow".

For more details on module features, see Module::Features.

Columns can be referred to be integer number (0-based) or name (string). You should not have integer numbers as column names because that will be confusing. Example:

 $t->columns(["col1", "col2", "col3"]); # col1=0, col2=1, col3=2
 $t->add_row([...]);
 ...

 # set visible columns
 $t->column_filter([1,2,1]); # col2, col3, col2
 $t->column_filter(["col2","col3","col2"]); # same thing

See also: "REFERRING TO ROWS".

Rows are referred to by integer number (0-based).

 $t->columns(["name", "age", "gender"]);
 $t->add_row(["marty", ...]); # first row (0)
 $t->add_row(["wendy", ...]); # second row (1)
 $t->add_row(["charlotte", ...]); # third row (2)

 # set visible rows
 $t->row_filter([0,2]); # marty & charlotte

See also: "REFERRING TO COLUMNS".

To list available border styles, just list the "BorderStyle::*" modules. You can use the provided method:

 say $_ for $t->list_border_styles;

Or you can also try out borders using the provided ansitable-list-border-styles script.

To choose border style, set the "border_style" attribute to an available border style name (which is the BorderStyle::* module name without the prefix) with optional arguments.

 # during construction
 my $t = Text::ANSITable->new(
     ...
     border_style => "UTF8::SingleLineBold",
     ...
 );

 # after the object is constructed
 $t->border_style("UTF8::SingleLineBold");
 $t->border_style("Test::CustomChar=character,x");
 $t->border_style(["Test::CustomChar", {character=>"x"}]);

If no border style is selected explicitly, a nice default will be chosen. You can also set the "ANSITABLE_BORDER_STYLE" or "BORDER_STYLE" environment variable to set the default.

To create a new border style, see BorderStyle.

To list available color themes, just list the "ColorTheme::*" modules (usually you want to use color themes specifically created for Text::ANSITable in "ColorTheme::Text::ANSITable::*" namespace). You can use the provided method:

 say $_ for $t->list_color_themes;

Or you can also run the provided ansitable-list-color-themes script.

To choose a color theme, set the "color_theme" attribute to an available color theme (which is the ColorTheme::* module name without the prefix) with optional arguments:

 # during construction
 my $t = Text::ANSITable->new(
     ...
     color_theme => "Standard::NoGradation",
     ...
 );

 # after the object is constructed
 $t->color_theme("Standard::NoGradation");
 $t->color_theme(["Lens::Darken", {theme=>"Standard::NoGradation"}]);

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.

To create a new color theme, see ColorTheme and an existing "ColorTheme::Text::ANSITable::*" module.

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

    This sets width for all columns.

  • conditional column styles

    The example below sets column width to 10 for columns whose names matching "/[acm]time/", else sets the column width to 20.

     $t->add_cond_column_style(sub {  /[acm]time/ }, width => 10);
     $t->add_cond_column_style(sub { !/[acm]time/ }, width => 20);
        
  • per-column "width" style

     $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

    This sets height for all rows.

  • conditional row styles

    The example below sets row height to 2 for every odd rows, and 1 for even rows.

     $t->add_cond_row_style(sub { $_ % 2 == 0 }, height => 2);
     $t->add_cond_row_style(sub { $_ % 2      }, height => 1);
        
  • per-row "height" style

     $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

    This sets left and right padding for all columns.

  • table-level "cell_lpad" and "cell_rpad" attributes

    They set left and right padding for all columns, respectively.

  • conditional column "pad" style

     $t->add_cond_column_style($cond, pad => 0);
        
  • conditional column "lpad"/"rpad" style

     $t->add_cond_column_style($cond, lpad => 1, rpad => 2);
        
  • per-column "pad" style

     $t->set_column_style($colname, pad => 0);
        
  • per-column "lpad"/"rpad" style

     $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 "cell_vpad" attribute

    This sets top and bottom padding for all rows.

  • table-level "cell_tpad"/"cell_bpad" attributes

    They set top/bottom padding separately for all rows.

  • conditional row "vpad" style

    Example:

     $t->add_cond_row_style($cond, vpad => 1);
        
  • per-row "vpad" style

    Example:

     $t->set_row_style($rownum, vpad => 1);
        

    When adding row:

     $t->add_row($rownum, {vpad=>1});
        
  • per-row "tpad"/"bpad" style

    Example:

     $t->set_row_style($rownum, tpad => 1);
     $t->set_row_style($rownum, bpad => 2);
        

    When adding row:

     $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):
  • 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.

  • conditional column "fgcolor" and "bgcolor" style

    Example:

     $t->add_cond_column_style($cond, fgcolor => 'fa8888', bgcolor => '202020');
        
  • per-column "fgcolor" and "bgcolor" styles

    Example:

     $t->set_column_style('colname', fgcolor => 'fa8888');
     $t->set_column_style('colname', bgcolor => '202020');
        
  • conditional row "fgcolor" and "bgcolor" style

    Example:

     $t->add_cond_row_style($cond, fgcolor => 'fa8888', bgcolor => '202020');
        
  • per-row "fgcolor" and "bgcolor" styles

    Example:

     $t->set_row_style($rownum, {fgcolor => 'fa8888', bgcolor => '202020'});
        

    When adding row/rows:

     $t->add_row($row, {fgcolor=>..., bgcolor=>...});
     $t->add_rows($rows, {bgcolor=>...});
        
  • conditional cell "fgcolor" and "bgcolor" style

     $t->add_cond_cell_style($cond, fgcolor=>..., bgcolor=>...);
        
  • per-cell "fgcolor" and "bgcolor" styles

    Example:

     $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
  • conditional column "align" and <valign> styles

     $t->add_cond_column_style($cond, align=>..., valign=>...);
        
  • per-column "align" and "valign" styles

    Example:

     $t->set_column_style($colname, align  => 'middle'); # or left, or right
     $t->set_column_style($colname, valign => 'top');    # or bottom, or middle
        
  • conditional row "align" and <valign> styles

     $t->add_cond_row_style($cond, align=>..., valign=>...);
        
  • per-row "align" and "valign" styles
  • conditional cell "align" and <valign> styles

     $t->add_cond_cell_style($cond, align=>..., valign=>...);
        
  • 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" style regulates 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}]]").

Data::Unixish::Apply is an optional prerequisite, so you will need to install it separately if you need this feature.

To see what functions are available, install App::dux and then run "dux -l". Functions of interest to formatting data include: "bool", "num", "sprintf", "sprintfn", "wrap", "ANSI::*" (in Data::Unixish::ANSI distribution), (among others).

As an alternative to setting styles for specific {column,row,cell}, you can also create conditional styles. You specify a Perl code for the condition, then if the condition evaluates to true, the corresponding styles are applied to the corresponding {column,row,cell}.

To add a conditional style, use the "add_cond_{column,row,cell}_style" methods. These methods accept condition code as its first argument and one or more styles in the subsequent argument(s). For example:

 $t->add_cond_row_style(sub { $_ % 2 }, bgcolor=>'202020');

The above example will set row bgcolor for odd rows. You can add more conditional styles:

 $t->add_cond_row_style(sub { $_ % 2 == 0 }, bgcolor=>'404040');

All the conditions will be evaluated and the applicable styles will be merged together. For example, if we add a third conditional row style:

 $t->add_cond_row_style(sub { $_ % 10 == 0 }, height=>2, fgcolor=>'ffff00');

then every tenth row will have its height set to 2, fgcolor set to ffff00, and bgcolor set to 404040 (from the second conditional).

Condition coderef will be called with these arguments:

 ($self, %args)

Available keys in %args for conditional column styles: "col" (int, column index), "colname" (str, column name). Additionally, $_ will be set locally to the column index.

Available keys in %args for conditional row styles: "row" (int, row index), "row_data" (array). Additionally, $_ will be set locally to the row index.

Available keys in %args for conditional cell styles: "content" (str), "col" (int, column index), "row" (int, row index). Additionally, $_ will be set locally to the cell content.

Coderef should return boolean indicating whether style should be applied to a particular column/row/cell. When returning a true value, coderef can also return a hashref to return additional styles that will be merged/applied too.

A style set is just a collection of style settings that can be applied. Organizing styles into style sets makes applying the styles simpler and more reusable.

More than one style sets can be applied.

Style set module accepts arguments.

For example, the Text::ANSITable::StyleSet::AltRow style set defines this:

 has odd_bgcolor  => (is => 'rw');
 has even_bgcolor => (is => 'rw');
 has odd_fgcolor  => (is => 'rw');
 has even_fgcolor => (is => 'rw');

 sub apply {
     my ($self, $table) = @_;

     $table->add_cond_row_style(sub {
         my ($t, %args) = @_;
         my %styles;
         if ($_ % 2) {
             $styles{bgcolor} = $self->odd_bgcolor
                 if defined $self->odd_bgcolor;
             $styles{fgcolor} = $self->odd_fgcolor
                 if defined $self->odd_bgcolor;
         } else {
             $styles{bgcolor} = $self->even_bgcolor
                 if defined $self->even_bgcolor;
             $styles{fgcolor} = $self->even_fgcolor
                 if defined $self->even_bgcolor;
         }
         \%styles;
     });
 }

To apply this style set:

 $t->apply_style_set("AltRow", odd_bgcolor=>"003300", even_bgcolor=>"000000");

To create a new style set, create a module under "Text::ANSITable::StyleSet::" like the above example. Please see the other existing style set modules for more examples.

Array of str. Must be unique.

Store column names. Note that when drawing, you can omit some columns, reorder them, or display some more than once (see "column_filter" attribute).

Caveat: Since, for convenience, a column can be referred to using its name or position, weird/unecxpected thing can happen if you name a column with a number (e.g. 0, 1, 2, ...). So don't do that.

Store row data. You can set this attribute directly, or add rows incrementally using "add_row()" and "add_rows()" methods.

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, $rownum)" and should return a bool value indicating whether that row should be displayed.

Internal note: During drawing, rows will be filtered and put into "$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 "($colname, $colnum)" 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.

Internal note: During drawing, column names will be filtered and put into "$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 "NO_COLOR" environment variable, "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.

(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.

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).

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.

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.

(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).

Whether to support wide characters. The default is to check for the existence of Text::ANSI::WideUtil (an optional prereq). You can explicitly enable or disable wide-character support here.

Border style name to use. This is a module name in the "BorderStyle::Text::ANSITable::*", "BorderStyle::*", or "BorderStyle::Text::ANSITable::OldCompat::*" namespace, without the prefix. See the BorderStyle specification on how to create a new border style.

Color theme name to use. This is a module name in the "ColorTheme::Text::ANSITable::*", "ColorTheme::*", or "ColorTheme::Text::ANSITable::OldCompat::*" namespace, without the prefix. See the ColorTheme and an example existing color theme module like ColorTheme::Text::ANSITable::Standard::Gradation specification on how to create a new border style.

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.

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.

Set (horizontal) alignment for all cells. Either "top", "middle", or "bottom". Can be overriden by per-column/per-row/per-cell "align" style.

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.

Set bottom padding for all cells. Overrides the "cell_vpad" attribute. Can be overriden by per-row "bpad" style.

Set foreground color for all cells. Value should be 6-hexdigit RGB. Can also be a coderef that will receive %args (e.g. rownum, col_name, colnum) 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, colnum) and should return an RGB color.

Like "header_fgcolor" but for background color.

Constructor.

Return the names of available border styles. Border styles will be searched in "BorderStyle::*" modules.

Return the names of available color themes. Color themes will be searched in "ColorTheme::*" modules.

Return the names of available style sets. Style set names are retrieved by listing modules under "Text::ANSITable::StyleSet::*" namespace.

Can also be called as a static method: "Text::ANSITable->get_border_style($name)".

Can also be called as a static method: "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()").

Add multiple rows. Note that row data is not copied, only referenced.

Can also add per-row styles (which can also be done using "row_style()").

Add a row separator line.

Get cell value at row #$rownum (starts from zero) and column named/numbered $col.

Set cell value at row #$rownum (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".

Get all the conditional column styles set so far.

Add a new conditional column style. See "CONDITIONAL STYLES" for more details on conditional style.

Get "effective" column style named $style for a particular column. Effective column style is calculated from all the conditional column styles and the per-column styles then merged together. This is the per-column style actually applied.

Get per-row style for row numbered $rownum.

Set per-row style(s) for row numbered $rownum. Available values for $style: "align", "valign", "height", "vpad", "tpad", "bpad", "fgcolor", "bgcolor".

Get all the conditional row styles set so far.

Add a new conditional row style. See "CONDITIONAL STYLES" for more details on conditional style.

Get "effective" row style named $style for a particular row. Effective row style is calculated from all the conditional row styles and the per-row styles then merged together. This is the per-row style actually applied.

Get per-cell style named $style for a particular cell. Return undef if there is no per-cell style with that name.

Set per-cell style(s). Available values for $style: "align", "valign", "formats", "fgcolor", "bgcolor".

Get all the conditional cell styles set so far.

Add a new conditional cell style. See "CONDITIONAL STYLES" for more details on conditional style.

Get "effective" cell style named $style for a particular cell. Effective cell style is calculated from all the conditional cell styles and the per-cell styles then merged together. This is the per-cell style actually applied.

Apply a style set. See "STYLE SETS" for more details.

Render table.

I don't see my data!

This might be caused by you not defining columns first, e.g.:

 my $t = Text::ANSITable->new;
 $t->add_row([1,2,3]);
 print $t->draw;

You need to do this first before adding rows:

 $t->columns(["col1", "col2", "col3"]);

All the rows are the same!

 my $t = Text::ANSITable->new;
 $t->columns(["col"]);
 my @row;
 for (1..3) {
     @row = ($_);
     $t->add_row(\@row);
 }
 print $t->draw;

will print:

 col
 3
 3
 3

You need to add row in this way instead of adding the same reference everytime:

     $t->add_row([@row]);

Output is too fancy! I just want to generate some plain (Text::ASCIITable-like) output to be copy-pasted to my document.

 $t->use_utf8(0);
 $t->use_box_chars(0);
 $t->use_color(0);
 $t->border_style('ASCII::SingleLine');

and you're good to go. Alternatively you can set environment UTF8=0, BOX_CHARS=0, COLOR=0, and ANSITABLE_BORDER_STYLE=ASCII::SingleLine.

Why am I getting 'Wide character in print' warning?

You are probably using a utf8 border style, and you haven't done something like this to your output:

 binmode(STDOUT, ":utf8");

My table looks garbled when viewed through pager like less!

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.

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.

How do I hide some columns/rows when drawing?

Use the "column_filter" and "row_filter" attributes. For example, given this table:

 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

Doing this:

 $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

Doing this:

 $t->column_filter([qw/two one 0/]);

will display:

  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

Doing this:

 $t->column_filter(sub { my ($colname, $idx) = @_; $colname =~ /t/ });

will display:

  two | three
 -----+-------
    1 |     1
    2 |     2
    3 |     3
    4 |     4
    5 |     5
    6 |     6
    7 |     7
    8 |     8
    9 |     9
   10 |    10

How do I format data?

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.

How does the module determine column data type?

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.

How does the module format data types?

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).

Other color themes might use different colors.

How do I force column to be of a certain data type?

For example, you have a column named "deleted" but want to display it as bool. You can do:

 $t->set_column_style(deleted => type => 'bool');

How do I wrap long text?

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):

 $t->set_column_style('description', formats=>[[wrap => {width=>60, ansi=>1, mb=>1}]]);

How do I highlight text with color?

The "ansi::highlight" dux function can be used to highlight text (see: Data::Unixish::ANSI::highlight).

 $t->set_column_style(2, formats => [[highlight => {pattern=>$pat}]]);

I want to change the default bool cross/check sign representation!

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.

How do I do conditional cell formatting?

There are several ways.

First, you can use the "cond" dux function through "formats" style. For example, if the cell contains the string "Cuti", you want to color the cell yellow. Otherwise, you want to color the cell red:

 $t->set_column_style($colname, formats => [
     [cond => {
         if   => sub { $_ =~ /Cuti/ },
         then => ["ansi::color", {color=>"yellow"}],
         else => ["ansi::color", {color=>"red"}],
     }]
 ]);

Another way is to use the "add_cond_{cell,row,column}" methods. See "CONDITIONAL STYLES" for more details. An example:

 $t->add_cond_row_style(sub {
     my %args = @_;
     $args{colname} =~ /Cuti/ ? {bgcolor=>"ffff00"} : {bgcolor=>"ff0000"};
 });

And another way is to use (or create) style set, which is basically a packaging of the above ways. An advantage of using style set is, because you do not specify coderef directly, you can specify it from the environment variable. See "STYLE SETS" for more details.

How to hide borders?

There is currently no "show_border" attribute. Choose border styles like "ASCII::Space", "ASCII::None", "UTF8::None":

 $t->border_style("UTF8::None");

Why are there 'ASCII::None' as well 'UTF8::None' and 'BoxChar::None' border styles?

Because of the row separator, that can still be drawn if "add_row_separator()" is used. See next question.

I want to hide borders, and I do not want row separators to be shown!

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:

   row1
   row2
   row3

I want to separate each row with a line!

Set "show_row_separator" to 1, or alternatively, set "ANSITABLE_STYLE='{"show_row_separator":1}".

How to disable colors?

Set "use_color" attribute or "COLOR" environment to 0.

How to specify colors using names (e.g. red, 'navy blue') instead of RGB?

Use modules like Graphics::ColorNames.

I'm not seeing colors when output is piped (e.g. to a pager)!

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.

How to enable 256 colors? I'm seeing only 16 colors.

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.

How to enable 24bit colors (true color)?

Currently only Konsole and the Konsole-based Yakuake terminal emulator software support 24bit colors.

How to force lower color depth? (e.g. I use Konsole but want 16 colors)

Set "COLOR_DEPTH" to 16.

How to change border gradation color?

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:

 $t->color_theme_args({border1=>'ff0000', border2=>'00ff00'}); # red to green

I'm using terminal emulator with white background, the texts are not very visible!

Try using the "*_whitebg" themes, as the other themes are geared towards terminal emulators with black background.

How to set different background colors for odd/even rows?

Aside from doing "$t->set_row_style($rownum, bgcolor=>...)" for each row, you can also do this:

 $t->cell_bgcolor(sub { my ($self, %args) = @_; $args{rownum} % 2 ? '202020' : undef });

Or, you can use conditional row styles:

 $t->add_cond_row_style(sub { $_ % 2 }, {bgcolor=>'202020'});

Or, you can use the Text::ANSITable::StyleSet::AltRow style set:

 $t->apply_style_set(AltRow => {even_bgcolor=>'202020'});

Can be used to set default value for the "color" attribute.

Can be used to set default value for the "color_depth" attribute.

Can be used to set default value for the "box_chars" attribute.

Can be used to set default value for the "utf8" attribute.

Can be used to override terminal width detection.

Can be used to set default value for "border_style" attribute. Takes precedence over BORDER_STYLE.

Can be used to set default value for "border_style" attribute. See also "ANSITABLE_BORDER_STYLE".

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:

 % 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 default value for the "wrap" column style.

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:

 % 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 "rownum => {style => val, ...}" pairs. Example:

 % 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 ""rownum,col" => {style => val, ...}" pairs. Example:

 % 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.

Can be used to apply style sets. Value should be a JSON-encoded array. Each element must be a style set name or a 2-element array containing style set name and its arguments ("[$name, \%args]"). Example:

 % ANSITABLE_STYLE_SETS='[["AltRow",{"odd_bgcolor":"003300"}]]'

will display table with row separator lines after every row.

Please visit the project's homepage at <https://metacpan.org/release/Text-ANSITable>.

Source repository is at <https://github.com/perlancar/perl-Text-ANSITable>.

For collections of border styles, search for "BorderStyle::*" modules.

For collections of color themes, search for "ColorTheme::*" modules.

Text::ASCIITable is one of the most popular table-formatting modules on CPAN. There are a couple of "extensions" for Text::ASCIITable: Text::ASCIITable::TW, Text::ASCIITable::Wrap; Text::ANSITable can be an alternative for all those modules since it can already handle wide-characters as well as multiline text in cells.

Text::TabularDisplay

Text::Table

Text::SimpleTable

Text::UnicodeTable::Simple

Table::Simple

Acme::CPANModules::TextTable catalogs text table modules.

Text::Table::Any and its CLI texttable can use Text::ANSITable as one of the backends.
App::TextTableUtils includes utilities like csv2ansitable or json2ansitable which can convert a CSV or array-of-array structure to a table rendered using Text::ANSITable.

Unix command column (e.g. "column -t").

perlancar <perlancar@cpan.org>

  • Mario Zieschang <mario@zieschang.info>
  • Steven Haryanto <stevenharyanto@gmail.com>

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

 % prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla plugin and/or Pod::Weaver::Plugin. Any additional steps required beyond that are considered a bug and can be reported to me.

This software is copyright (c) 2022, 2021, 2020, 2018, 2017, 2016, 2015, 2014, 2013 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

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.

2022-02-14 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.