Text::ASCIITable(3pm)

💅 Text::ASCIITable(3pm) 💅

okay so bestie, this is the Text::ASCIITable(3pm) page from the User Contributed Perl Documentation, and it's literally about making cute little ASCII tables. No cap, it's giving main character energy fr fr. 🎀✨

---

✨ NAME ✨

Text::ASCIITable — Create a nice formatted table using ASCII characters. 💖

🌸 SHORT DESCRIPTION 🌸

Pretty nifty if you want to output dynamic text to your console or other fixed-size-font displays, and at the same time it will display it in a nice human-readable, or "cool" way. periodt. 🦋

💖 SYNOPSIS 💖

bestie, here's the whole vibe:

  use Text::ASCIITable;
  $t = Text::ASCIITable->new({ headingText => 'Basket' });

  $t->setCols('Id','Name','Price');
  $t->addRow(1,'Dummy product 1',24.4);
  $t->addRow(2,'Dummy product 2',21.2);
  $t->addRow(3,'Dummy product 3',12.3);
  $t->addRowLine();
  $t->addRow('','Total',57.9);
  print $t;

  # Result:
  .------------------------------.
  |            Basket            |
  +----+-----------------+-------+
  | Id | Name            | Price |
  +----+-----------------+-------+
  |  1 | Dummy product 1 |  24.4 |
  |  2 | Dummy product 2 |  21.2 |
  |  3 | Dummy product 3 |  12.3 |
  +----+-----------------+-------+
  |    | Total           |  57.9 |
  '----+-----------------+-------'

---

🔥 FUNCTIONS 🔥

new(options) — new table who dis 💅

Initialize a new table. You can specify output-options. For more options, check out the usage for setOptions().

  Usage:
  $t = Text::ASCIITable->new();

  Or with options:
  $t = Text::ASCIITable->new({ hide_Lastline => 1, reportErrors => 0});

setCols(@cols) — set the columns, periodt ✨

Define the columns for the table (compare with <TH> in HTML). For example setCols(['Id','Nick','Name']). Note that you cannot add Cols after you have added a row. Multiline columnnames are allowed. 👑

addRow(@collist) — add a row, slay 🎀

Adds one row to the table. This must be an array of strings. If you defined 3 columns. This array must have 3 items in it. And so on. Should be self explanatory. The strings can contain newlines.

Note: It does not require argument to be an array, thus; $t->addRow(['id','name']) and $t->addRow('id','name') does the same thing.

This module is also overloaded to accept push. To construct a table with the use of overloading you might do the following:

  $t = Text::ASCIITable->new();
  $t->setCols('one','two','three','four');
  push @$t, ( "one\ntwo" ) x 4; # Replaces $t->addrow();
  print $t;                     # Replaces print $t->draw();

Which would construct:

 .-----+-----+-------+------.
 | one | two | three | four |
 |=----+-----+-------+-----=|
 | one | one | one   | one  |  # Note that theese two lines
 | two | two | two   | two  |  # with text are one singe row.
 '-----+-----+-------+------'

There is also possible to give this function an array of arrayrefs and hence support the output from DBI::selectall_arrayref($sql) without changes.

Example of multiple-rows pushing:

  $t->addRow([
    [ 1, 2, 3 ],
    [ 4, 5, 6 ],
    [ 7, 8, 9 ],
  ]);

addRowLine([$row]) — line after row, cute 🌸

Will add a line after the current row. As an argument, you may specify after which row you want a line (first row is 1) or an array of row numbers. (HINT: If you want a line after every row, read about the drawRowLine option in setOptions())

Example without arguments:

  $t->addRow('one','two','three');
  $t->addRowLine();
  $t->addRow('one','two','three');

Example with argument:

  $t->addRow('one','two','three');
  $t->addRow('one','two','three');
  $t->addRow('one','two','three');
  $t->addRow('one','two','three');
  $t->addRowLine(1); # or multiple: $t->addRowLine([2,3]);

alignCol($col,$direction) or alignCol({col1 => direction1, col2 => direction2, ... }) — align that column, bestie 🦋

Given a columnname, it aligns all data to the given direction in the table. This looks nice on numerical displays in a column. The column names in the table will be unaffected by the alignment. Possible directions is: left, center, right, justify, auto or your own subroutine. (Hint: Using auto (default), aligns numbers right and text left)

alignColName($col,$direction) — align the column name, iconic ✨

Given a columnname, it aligns the columnname in the row explaining columnnames, to the given direction. (auto, left, right, center, justify or a subroutine) (Hint: Overrides the 'alignHeadRow' option for the specified column.)

setColWidth($col,$width,$strict) — set column width, no cap 💅

Wordwrapping/strict size. Set a max-width (in chars) for a column. If last parameter is 1, the column will be set to the specified width, even if no text is that long.

 Usage:
  $t->setColWidth('Description',30);

getTableWidth() — how wide tho? 📏

If you need to know how wide your table will be before you draw it. Use this function.

setOptions(name,value) or setOptions({ option1 => value1, option2 => value2, ... }) — set all the options, periodt 🎀

Use this to set options like: hide_FirstLine, reportErrors, etc.

  Usage:
  $t->setOptions('hide_HeadLine',1);

  Or set more than one option on the fly:
  $t->setOptions({ hide_HeadLine => 1, hide_HeadRow => 1 });

🎀 Possible Options 🎀

• hide_HeadRow — Hides output of the columnlisting. Together with hide_HeadLine, this makes a table only show the rows. (However, even though the column-names will not be shown, they will affect the output if they have for example ridiculoustly long names, and the rows contains small amount of info. You would end up with a lot of whitespace)
• reportErrors — Set to 0 to disable error reporting. Though if a function encounters an error, it will still return the value 1, to tell you that things didn't go exactly as they should.
• allowHTML — If you are going to use Text::ASCIITable to be shown on HTML pages, you should set this option to 1 when you are going to use HTML tags to for example color the text inside the rows, and you want the browser to handle the table correct.
• allowANSI — If you use ANSI codes like <ESC>[1mHi this is bold<ESC>[m or similar. This option will make the table to be displayed correct when showed in a ANSI compliant terminal. Set this to 1 to enable. There is an example of ANSI support in this package, named ansi-example.pl.
• alignHeadRow — Set which direction the Column-names (in the headrow) are supposed to point. Must be left, right, center, justify, auto or a user-defined subroutine.
• hide_FirstLine, hide_HeadLine, hide_LastLine — Speaks for it self?
• drawRowLine — Set this to 1 to print a line between each row. You can also define the outputstyle of this line in the draw() function.
• headingText — Add a heading above the columnnames/rows which uses the whole width of the table to output a heading/title to the table. The heading-part of the table is automatically shown when the headingText option contains text. Note: If this text is so long that it makes the table wider, it will not hesitate to change width of columns that have "strict width".

It supports multiline, and with Text::ASCIITable::Wrap you may wrap your text before entering it, to prevent the title from expanding the table. Internal wrapping-support for headingText might come in the future.

• headingAlign — Align the heading (as mentioned above) to left, right, center, auto or using a subroutine.
• headingStartChar, headingStopChar — Choose the startingchar and endingchar of the row where the title is. The default is '|' on both. If you didn't understand this, try reading about the draw() function.
• cb_count — Set the callback subroutine to use when counting characters inside the table. This is useful to make support for having characters or codes inside the table that are not shown on the screen to the user, so the table should not count these characters. This could be for example HTML tags, or ANSI codes. Though those two examples are alredy supported internally with the allowHTML and allowANSI, options. This option expects a CODE reference. (\&callback_function)
• undef_as — Sets the replacing string that replaces an undef value sent to addRow() (or even the overloaded push version of addRow()). The default value is an empty string ''. An example of use would be to set it to '(undef)', to show that the input really was undefined.
• chaining — Set this to 1 to support chainging of methods. The default is 0, where the methods return 1 if they come upon an error as mentioned in the reportErrors option description.

Usage example:

print Text::ASCIITable->new({ chaining => 1 })
  ->setCols('One','Two','Three')
  ->addRow([
    [ 1, 2, 3 ],
    [ 4, 5, 6 ],
    [ 7, 8, 9 ],
    ])
  ->draw();

Note that ->draw() can be omitted, since Text::ASCIITable is overloaded to print the table by default.

draw([@topdesign,@toprow,@middle,@middlerow,@bottom,@rowline]) — draw the whole table 💖

All the arrays containing the layout is optional. If you want to make your own "design" to the table, you can do that by giving this method these arrays containing information about which characters to use where.

Custom tables 🎨

The draw method takes 6 arrays of strings to define the layout. The first, third, fifth and sixth is LINE layout and the second and fourth is ROW layout. The "fourth" parameter is repeated for each row in the table. The sixth parameter is only used if drawRowLine is enabled.

 $t->draw(<LINE>,<ROW>,<LINE>,<ROW>,<LINE>,[<ROWLINE>])

LINE — line layout ✨

Takes an array of 4 strings. For example "['|','|','-','+']"

• LEFT — Defines the left chars. May be more than one char.
• RIGHT — Defines the right chars. May be more then one char.
• LINE — Defines the char used for the line. Must be only one char.
• DELIMETER — Defines the char used for the delimiters. Must be only one char.

ROW — row layout 🎀

Takes an array of 3 strings. You should not give more than one char to any of these parameters, if you do.. it will probably destroy the output.. Unless you do it with the knowledge of how it will end up. An example: "['|','|','+']"

• LEFT — Define the char used for the left side of the table.
• RIGHT — Define the char used for the right side of the table.
• DELIMETER — Defines the char used for the delimiters.

Examples 💅

The easiest way:

 print $t;

Explanatory example:

 print $t->draw( ['L','R','l','D'],  # LllllllDllllllR
                 ['L','R','D'],      # L info D info R
                 ['L','R','l','D'],  # LllllllDllllllR
                 ['L','R','D'],      # L info D info R
                 ['L','R','l','D']   # LllllllDllllllR
                );

Nice example:

...and lowkey the custom-charset glow-up is where it gets fun:

print $t->draw( ['.','.','-','-'],   # .-------------.
                ['|','|','|'],       # | info | info |
                ['|','|','-','-'],   # |-------------|
                ['|','|','|'],       # | info | info |
                [' \\','/ ','_','|'] #  \_____|_____/
               );

And here's the iconic example2, where the corners get a lil ✨ upgrade ✨:

print $t->draw( ['.=','=.','-','-'],   # .=-----------=.
                ['|','|','|'],         # | info | info |
                ['|=','=|','-','+'],   # |=-----+-----=|
                ['|','|','|'],         # | info | info |
                ["'=","='",'-','-']    # '=-----------='
               );

Now let's throw some options in the mix 🎀:

$t->setOptions('drawRowLine',1);
print $t->draw( ['.=','=.','-','-'],   # .=-----------=.
                ['|','|','|'],         # | info | info |
                ['|-','-|','=','='],   # |-===========-|
                ['|','|','|'],         # | info | info |
                ["'=","='",'-','-'],   # '=-----------='
                ['|=','=|','-','+']    # rowseperator
               );

Which makes this output:

  .=-----------=.
  | col1 | col2 |
  |-===========-|
  | info | info |
  |=-----+-----=| <-- rowseperator between each row
  | info | info |
  '=-----------='

Look at that rowseperator just slidin' in between each row, no cap 💅.

🌸 A tip: turn on allowANSI and use the extra charset in your terminal to build a gorgeous table. But do not expect good results if you use an ANSI-formatted table together with $t->drawPage. That combo is giving chaos, bestie 🫠.

💖 User-defined subroutines for aligning

If you wanna format your text more thoroughly than "auto", or honestly you just think you've got a better way of aligning text — bestie, you can absolutely make your own subroutine. Main character move.

Here's an example routine that aligns the text to the right:

sub myownalign_cb {
  my ($text,$length,$count,$strict) = @_;
  $text = (" " x ($length - $count)) . $text;
  return substr($text,0,$length) if ($strict);
  return $text;
}

$t->alignCol('Info',\&myownalign_cb);

🦋 User-defined subroutines for counting

This feature is for when you're just not happy with the built-in allowHTML or allowANSI support. Below is an example of how you make a count-callback that makes ASCIITable support ANSI codes inside the table. (Spoiler: it would make the same result as setting allowANSI to 1.)

$t->setOptions('cb_count',\&myallowansi_cb);
sub myallowansi_cb {
  $_=shift;
  s/\33\[(\d+(;\d+)?)?[musfwhojBCDHRJK]//g;
  return length($_);
}

✨ drawPage($page,@topdesign,@toprow,@middle,@middlerow,@bottom,@rowline) ✨

If you don't want your table to be wider than your screen, you can use this together with $t->setOptions('outputWidth',40) to set the max size of the output. Protecting the vibe from getting clipped by your terminal edge 🙈.

Example:

$t->setOptions('outputWidth',80);
for my $page (1..$t->pageCount()) {
  print $t->drawPage($page)."\n";
  print "continued..\n\n";
}

---

🌈 FEATURES 🌈

In case you need to know whether this module has what you need, here's the list of features included in Text::ASCIITable. Consider this your vibe check ✅.

🎀 Configurable layout

You can easily alter how the table should look, in so many ways. There are a few examples in the draw() section of this documentation. And like — you can remove parts of the layout or even add a heading-part to the table. Go off, decorate it 💅.

🎀 Text Aligning

Align the text in a column auto(matically), left, right, center or justify. Usually you want to align text to the right if you only have numbers in that row. The 'auto' direction aligns text to left, and numbers to the right. The 'justify' alignment evens out your text on each line, so the first and the last word always are at the beginning and the end of the current line — which gives you that newspaper paragraph look, iconic 📰. You can also use your own subroutine as a callback-function to align your text. Yes, your rules.

🎀 Multiline support in rows

With the \n(ewline) character you can have rows use more than just one line on the output. (This looks nice with the drawRowLine option enabled. Chef's kiss.)

🎀 Wordwrap support

You can set a column to not be wider than a set amount of characters. If a line exceedes for example 30 characters, the line will be broken up in several lines. Snip snip ✂️.

🎀 HTML support

If you put in <HTML> tags inside the rows, the output would usually be broken when viewed in a browser, since the browser "execute" the tags instead of displaying it. But if you enable allowHTML, you are able to write html tags inside the rows without the output being broken if you display it in a browser. But you should not mix this with wordwrap, since this could make undesirable results.

🎀 ANSI support

Allows you to decorate your tables with colors or bold/underline when you display your tables to a terminal window. Glow up guaranteed ✨.

🎀 Page-flipping support

If you don't want the table to get wider than your terminal-width. Flip through those pages like it's a carousel 🎠.

🎀 Errorreporting

If you write a script in perl, and don't want users to be notified of the errormessages from Text::ASCIITable, you can easily turn off error reporting by setting reportErrors to 0. You will still get a 1 instead of undef returned from the function. Silent but it still shows up, periodt.

---

💜 REQUIRES 💜

• Exporter, Carp

---

👑 AUTHOR 👑

Haakon Nessjoen, <lunatic@cpan.org>

---

⭐ VERSION ⭐

Current version is 0.22.

---

🌸 COPYRIGHT 🌸

Copyright 2002-2011 by Haakon Nessjoen. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

🦋 SEE ALSO 🦋

• Text::FormatTable
• Text::Table
• Text::SimpleTable

---

And that's the whole page, bestie 🫶 — this one came from perl v5.36.0, dated 2022-10-13, and it's the Text::ASCIITable(3pm) page. Go make some unreasonably pretty tables, you've got this 💖✨