| 1 |
NAME |
| 2 |
Text::ASCIITable - Create a nice formatted table using ASCII characters. |
| 3 |
|
| 4 |
SHORT DESCRIPTION |
| 5 |
Pretty nifty if you want to output dynamic text to your console or other |
| 6 |
fixed-size-font displays, and at the same time it will display it in a |
| 7 |
nice human-readable, or "cool" way. |
| 8 |
|
| 9 |
SYNOPSIS |
| 10 |
use Text::ASCIITable; |
| 11 |
$t = Text::ASCIITable->new({ headingText => 'Basket' }); |
| 12 |
|
| 13 |
$t->setCols('Id','Name','Price'); |
| 14 |
$t->addRow(1,'Dummy product 1',24.4); |
| 15 |
$t->addRow(2,'Dummy product 2',21.2); |
| 16 |
$t->addRow(3,'Dummy product 3',12.3); |
| 17 |
$t->addRowLine(); |
| 18 |
$t->addRow('','Total',57.9); |
| 19 |
print $t; |
| 20 |
|
| 21 |
# Result: |
| 22 |
.------------------------------. |
| 23 |
| Basket | |
| 24 |
+----+-----------------+-------+ |
| 25 |
| Id | Name | Price | |
| 26 |
+----+-----------------+-------+ |
| 27 |
| 1 | Dummy product 1 | 24.4 | |
| 28 |
| 2 | Dummy product 2 | 21.2 | |
| 29 |
| 3 | Dummy product 3 | 12.3 | |
| 30 |
+----+-----------------+-------+ |
| 31 |
| | Total | 57.9 | |
| 32 |
'----+-----------------+-------' |
| 33 |
|
| 34 |
FUNCTIONS |
| 35 |
new(options) |
| 36 |
Initialize a new table. You can specify output-options. For more |
| 37 |
options, check out the usage for setOptions() |
| 38 |
|
| 39 |
Usage: |
| 40 |
$t = Text::ASCIITable->new(); |
| 41 |
|
| 42 |
Or with options: |
| 43 |
$t = Text::ASCIITable->new({ hide_Lastline => 1, reportErrors => 0}); |
| 44 |
|
| 45 |
setCols(@cols) |
| 46 |
Define the columns for the table(compare with <TH> in HTML). For example |
| 47 |
"setCols(['Id','Nick','Name'])". Note that you cannot add Cols after you |
| 48 |
have added a row. Multiline columnnames are allowed. |
| 49 |
|
| 50 |
addRow(@collist) |
| 51 |
Adds one row to the table. This must be an array of strings. If you |
| 52 |
defined 3 columns. This array must have 3 items in it. And so on. Should |
| 53 |
be self explanatory. The strings can contain newlines. |
| 54 |
|
| 55 |
Note: It does not require argument to be an array, thus; |
| 56 |
$t->addRow(['id','name']) and $t->addRow('id','name') does the same thing. |
| 57 |
|
| 58 |
This module is also overloaded to accept push. To construct a table with |
| 59 |
the use of overloading you might do the following: |
| 60 |
|
| 61 |
$t = Text::ASCIITable->new(); |
| 62 |
$t->setCols('one','two','three','four'); |
| 63 |
push @$t, ( "one\ntwo" ) x 4; # Replaces $t->addrow(); |
| 64 |
print $t; # Replaces print $t->draw(); |
| 65 |
|
| 66 |
Which would construct: |
| 67 |
.-----+-----+-------+------. |
| 68 |
| one | two | three | four | |
| 69 |
|=----+-----+-------+-----=| |
| 70 |
| one | one | one | one | # Note that theese two lines |
| 71 |
| two | two | two | two | # with text are one singe row. |
| 72 |
'-----+-----+-------+------' |
| 73 |
|
| 74 |
There is also possible to give this function an array of arrayrefs and |
| 75 |
hence support the output from DBI::selectall_arrayref($sql) without |
| 76 |
changes. |
| 77 |
|
| 78 |
Example of multiple-rows pushing: |
| 79 |
$t->addRow([ |
| 80 |
[ 1, 2, 3 ], |
| 81 |
[ 4, 5, 6 ], |
| 82 |
[ 7, 8, 9 ], |
| 83 |
]); |
| 84 |
|
| 85 |
addRowLine([$row]) |
| 86 |
Will add a line after the current row. As an argument, you may specify |
| 87 |
after which row you want a line (first row is 1) or an array of row |
| 88 |
numbers. (HINT: If you want a line after every row, read about the |
| 89 |
drawRowLine option in setOptions()) |
| 90 |
|
| 91 |
Example without arguments: $t->addRow('one','two','three'); |
| 92 |
$t->addRowLine(); $t->addRow('one','two','three'); |
| 93 |
|
| 94 |
Example with argument: $t->addRow('one','two','three'); |
| 95 |
$t->addRow('one','two','three'); $t->addRow('one','two','three'); |
| 96 |
$t->addRow('one','two','three'); $t->addRowLine(1); # or multiple: |
| 97 |
$t->addRowLine([2,3]); |
| 98 |
|
| 99 |
alignCol($col,$direction) or alignCol({col1 => direction1, col2 => direction2, ... }) |
| 100 |
Given a columnname, it aligns all data to the given direction in the |
| 101 |
table. This looks nice on numerical displays in a column. The column |
| 102 |
names in the table will be unaffected by the alignment. Possible |
| 103 |
directions is: left, center, right, justify, auto or your own |
| 104 |
subroutine. (Hint: Using auto(default), aligns numbers right and text |
| 105 |
left) |
| 106 |
|
| 107 |
alignColName($col,$direction) |
| 108 |
Given a columnname, it aligns the columnname in the row explaining |
| 109 |
columnnames, to the given direction. (auto,left,right,center,justify or |
| 110 |
a subroutine) (Hint: Overrides the 'alignHeadRow' option for the |
| 111 |
specified column.) |
| 112 |
|
| 113 |
setColWidth($col,$width,$strict) |
| 114 |
Wordwrapping/strict size. Set a max-width(in chars) for a column. If |
| 115 |
last parameter is 1, the column will be set to the specified width, even |
| 116 |
if no text is that long. |
| 117 |
|
| 118 |
Usage: |
| 119 |
$t->setColWidth('Description',30); |
| 120 |
|
| 121 |
getTableWidth() |
| 122 |
If you need to know how wide your table will be before you draw it. Use |
| 123 |
this function. |
| 124 |
|
| 125 |
setOptions(name,value) or setOptions({ option1 => value1, option2 => value2, ... }) |
| 126 |
Use this to set options like: hide_FirstLine,reportErrors, etc. |
| 127 |
|
| 128 |
Usage: |
| 129 |
$t->setOptions('hide_HeadLine',1); |
| 130 |
|
| 131 |
Or set more than one option on the fly: |
| 132 |
$t->setOptions({ hide_HeadLine => 1, hide_HeadRow => 1 }); |
| 133 |
|
| 134 |
Possible Options |
| 135 |
|
| 136 |
hide_HeadRow |
| 137 |
Hides output of the columnlisting. Together with hide_HeadLine, this |
| 138 |
makes a table only show the rows. (However, even though the |
| 139 |
column-names will not be shown, they will affect the output if they |
| 140 |
have for example ridiculoustly long names, and the rows contains |
| 141 |
small amount of info. You would end up with a lot of whitespace) |
| 142 |
|
| 143 |
reportErrors |
| 144 |
Set to 0 to disable error reporting. Though if a function encounters |
| 145 |
an error, it will still return the value 1, to tell you that things |
| 146 |
didn't go exactly as they should. |
| 147 |
|
| 148 |
allowHTML |
| 149 |
If you are going to use Text::ASCIITable to be shown on HTML pages, |
| 150 |
you should set this option to 1 when you are going to use HTML tags |
| 151 |
to for example color the text inside the rows, and you want the |
| 152 |
browser to handle the table correct. |
| 153 |
|
| 154 |
allowANSI |
| 155 |
If you use ANSI codes like <ESC>[1mHi this is bold<ESC>[m or |
| 156 |
similar. This option will make the table to be displayed correct |
| 157 |
when showed in a ANSI compliant terminal. Set this to 1 to enable. |
| 158 |
There is an example of ANSI support in this package, named |
| 159 |
ansi-example.pl. |
| 160 |
|
| 161 |
alignHeadRow |
| 162 |
Set wich direction the Column-names(in the headrow) are supposed to |
| 163 |
point. Must be left, right, center, justify, auto or a user-defined |
| 164 |
subroutine. |
| 165 |
|
| 166 |
hide_FirstLine, hide_HeadLine, hide_LastLine |
| 167 |
Speaks for it self? |
| 168 |
|
| 169 |
drawRowLine |
| 170 |
Set this to 1 to print a line between each row. You can also define |
| 171 |
the outputstyle of this line in the draw() function. |
| 172 |
|
| 173 |
headingText |
| 174 |
Add a heading above the columnnames/rows wich uses the whole width |
| 175 |
of the table to output a heading/title to the table. The |
| 176 |
heading-part of the table is automatically shown when the |
| 177 |
headingText option contains text. Note: If this text is so long that |
| 178 |
it makes the table wider, it will not hesitate to change width of |
| 179 |
columns that have "strict width". |
| 180 |
|
| 181 |
It supports multiline, and with Text::ASCIITable::Wrap you may wrap |
| 182 |
your text before entering it, to prevent the title from expanding |
| 183 |
the table. Internal wrapping-support for headingText might come in |
| 184 |
the future. |
| 185 |
|
| 186 |
headingAlign |
| 187 |
Align the heading(as mentioned above) to left, right, center, auto |
| 188 |
or using a subroutine. |
| 189 |
|
| 190 |
headingStartChar, headingStopChar |
| 191 |
Choose the startingchar and endingchar of the row where the title |
| 192 |
is. The default is '|' on both. If you didn't understand this, try |
| 193 |
reading about the draw() function. |
| 194 |
|
| 195 |
cb_count |
| 196 |
Set the callback subroutine to use when counting characters inside |
| 197 |
the table. This is useful to make support for having characters or |
| 198 |
codes inside the table that are not shown on the screen to the user, |
| 199 |
so the table should not count these characters. This could be for |
| 200 |
example HTML tags, or ANSI codes. Though those two examples are |
| 201 |
alredy supported internally with the allowHTML and allowANSI, |
| 202 |
options. This option expects a CODE reference. (\&callback_function) |
| 203 |
|
| 204 |
undef_as |
| 205 |
Sets the replacing string that replaces an undef value sent to |
| 206 |
addRow() (or even the overloaded push version of addRow()). The |
| 207 |
default value is an empty string ''. An example of use would be to |
| 208 |
set it to '(undef)', to show that the input really was undefined. |
| 209 |
|
| 210 |
chaining |
| 211 |
Set this to 1 to support chainging of methods. The default is 0, |
| 212 |
where the methods return 1 if they come upon an error as mentioned |
| 213 |
in the reportErrors option description. |
| 214 |
|
| 215 |
Usage example: |
| 216 |
print Text::ASCIITable->new({ chaining => 1 }) |
| 217 |
->setCols('One','Two','Three') |
| 218 |
->addRow([ |
| 219 |
[ 1, 2, 3 ], |
| 220 |
[ 4, 5, 6 ], |
| 221 |
[ 7, 8, 9 ], |
| 222 |
]) |
| 223 |
->draw(); |
| 224 |
|
| 225 |
Note that ->draw() can be omitted, since Text::ASCIITable is |
| 226 |
overloaded to print the table by default. |
| 227 |
|
| 228 |
draw([@topdesign,@toprow,@middle,@middlerow,@bottom,@rowline]) |
| 229 |
All the arrays containing the layout is optional. If you want to make |
| 230 |
your own "design" to the table, you can do that by giving this method |
| 231 |
these arrays containing information about which characters to use where. |
| 232 |
|
| 233 |
Custom tables |
| 234 |
|
| 235 |
The draw method takes 6 arrays of strings to define the layout. The |
| 236 |
first, third, fifth and sixth is LINE layout and the second and fourth |
| 237 |
is ROW layout. The "fourth" parameter is repeated for each row in the |
| 238 |
table. The sixth parameter is only used if drawRowLine is enabled. |
| 239 |
|
| 240 |
$t->draw(<LINE>,<ROW>,<LINE>,<ROW>,<LINE>,[<ROWLINE>]) |
| 241 |
|
| 242 |
LINE |
| 243 |
Takes an array of 4 strings. For example "['|','|','-','+']" |
| 244 |
|
| 245 |
* LEFT - Defines the left chars. May be more than one char. |
| 246 |
|
| 247 |
* RIGHT - Defines the right chars. May be more then one char. |
| 248 |
|
| 249 |
* LINE - Defines the char used for the line. Must be only one |
| 250 |
char. |
| 251 |
|
| 252 |
* DELIMETER - Defines the char used for the delimeters. Must be |
| 253 |
only one char. |
| 254 |
|
| 255 |
ROW Takes an array of 3 strings. You should not give more than one char |
| 256 |
to any of these parameters, if you do.. it will probably destroy the |
| 257 |
output.. Unless you do it with the knowledge of how it will end up. |
| 258 |
An example: "['|','|','+']" |
| 259 |
|
| 260 |
* LEFT - Define the char used for the left side of the table. |
| 261 |
|
| 262 |
* RIGHT - Define the char used for the right side of the table. |
| 263 |
|
| 264 |
* DELIMETER - Defines the char used for the delimeters. |
| 265 |
|
| 266 |
Examples: |
| 267 |
|
| 268 |
The easiest way: |
| 269 |
|
| 270 |
print $t; |
| 271 |
|
| 272 |
Explanatory example: |
| 273 |
|
| 274 |
print $t->draw( ['L','R','l','D'], # LllllllDllllllR |
| 275 |
['L','R','D'], # L info D info R |
| 276 |
['L','R','l','D'], # LllllllDllllllR |
| 277 |
['L','R','D'], # L info D info R |
| 278 |
['L','R','l','D'] # LllllllDllllllR |
| 279 |
); |
| 280 |
|
| 281 |
Nice example: |
| 282 |
|
| 283 |
print $t->draw( ['.','.','-','-'], # .-------------. |
| 284 |
['|','|','|'], # | info | info | |
| 285 |
['|','|','-','-'], # |-------------| |
| 286 |
['|','|','|'], # | info | info | |
| 287 |
[' \\','/ ','_','|'] # \_____|_____/ |
| 288 |
); |
| 289 |
|
| 290 |
Nice example2: |
| 291 |
|
| 292 |
print $t->draw( ['.=','=.','-','-'], # .=-----------=. |
| 293 |
['|','|','|'], # | info | info | |
| 294 |
['|=','=|','-','+'], # |=-----+-----=| |
| 295 |
['|','|','|'], # | info | info | |
| 296 |
["'=","='",'-','-'] # '=-----------=' |
| 297 |
); |
| 298 |
|
| 299 |
With Options: |
| 300 |
|
| 301 |
$t->setOptions('drawRowLine',1); |
| 302 |
print $t->draw( ['.=','=.','-','-'], # .=-----------=. |
| 303 |
['|','|','|'], # | info | info | |
| 304 |
['|-','-|','=','='], # |-===========-| |
| 305 |
['|','|','|'], # | info | info | |
| 306 |
["'=","='",'-','-'], # '=-----------=' |
| 307 |
['|=','=|','-','+'] # rowseperator |
| 308 |
); |
| 309 |
Which makes this output: |
| 310 |
.=-----------=. |
| 311 |
| col1 | col2 | |
| 312 |
|-===========-| |
| 313 |
| info | info | |
| 314 |
|=-----+-----=| <-- rowseperator between each row |
| 315 |
| info | info | |
| 316 |
'=-----------=' |
| 317 |
|
| 318 |
A tips is to enable allowANSI, and use the extra charset in your |
| 319 |
terminal to create a beautiful table. But don't expect to get good |
| 320 |
results if you use ANSI-formatted table with $t->drawPage. |
| 321 |
|
| 322 |
User-defined subroutines for aligning |
| 323 |
|
| 324 |
If you want to format your text more throughoutly than "auto", or think |
| 325 |
you have a better way of aligning text; you can make your own |
| 326 |
subroutine. |
| 327 |
|
| 328 |
Here's a exampleroutine that aligns the text to the right. |
| 329 |
|
| 330 |
sub myownalign_cb { |
| 331 |
my ($text,$length,$count,$strict) = @_; |
| 332 |
$text = (" " x ($length - $count)) . $text; |
| 333 |
return substr($text,0,$length) if ($strict); |
| 334 |
return $text; |
| 335 |
} |
| 336 |
|
| 337 |
$t->alignCol('Info',\&myownalign_cb); |
| 338 |
|
| 339 |
User-defined subroutines for counting |
| 340 |
|
| 341 |
This is a feature to use if you are not happy with the internal |
| 342 |
allowHTML or allowANSI support. Given is an example of how you make a |
| 343 |
count-callback that makes ASCIITable support ANSI codes inside the |
| 344 |
table. (would make the same result as setting allowANSI to 1) |
| 345 |
|
| 346 |
$t->setOptions('cb_count',\&myallowansi_cb); |
| 347 |
sub myallowansi_cb { |
| 348 |
$_=shift; |
| 349 |
s/\33\[(\d+(;\d+)?)?[musfwhojBCDHRJK]//g; |
| 350 |
return length($_); |
| 351 |
} |
| 352 |
|
| 353 |
drawPage($page,@topdesign,@toprow,@middle,@middlerow,@bottom,@rowline) |
| 354 |
If you don't want your table to be wider than your screen you can use |
| 355 |
this with $t->setOptions('outputWidth',40) to set the max size of the |
| 356 |
output. |
| 357 |
|
| 358 |
Example: |
| 359 |
|
| 360 |
$t->setOptions('outputWidth',80); |
| 361 |
for my $page (1..$t->pageCount()) { |
| 362 |
print $t->drawPage($page)."\n"; |
| 363 |
print "continued..\n\n"; |
| 364 |
} |
| 365 |
|
| 366 |
FEATURES |
| 367 |
In case you need to know if this module has what you need, I have made |
| 368 |
this list of features included in Text::ASCIITable. |
| 369 |
|
| 370 |
Configurable layout |
| 371 |
You can easily alter how the table should look, in many ways. There |
| 372 |
are a few examples in the draw() section of this documentation. And |
| 373 |
you can remove parts of the layout or even add a heading-part to the |
| 374 |
table. |
| 375 |
|
| 376 |
Text Aligning |
| 377 |
Align the text in a column auto(matically), left, right, center or |
| 378 |
justify. Usually you want to align text to right if you only have |
| 379 |
numbers in that row. The 'auto' direction aligns text to left, and |
| 380 |
numbers to the right. The 'justify' alignment evens out your text on |
| 381 |
each line, so the first and the last word always are at the |
| 382 |
beginning and the end of the current line. This gives you the |
| 383 |
newspaper paragraph look. You can also use your own subroutine as a |
| 384 |
callback-function to align your text. |
| 385 |
|
| 386 |
Multiline support in rows |
| 387 |
With the \n(ewline) character you can have rows use more than just |
| 388 |
one line on the output. (This looks nice with the drawRowLine option |
| 389 |
enabled) |
| 390 |
|
| 391 |
Wordwrap support |
| 392 |
You can set a column to not be wider than a set amount of |
| 393 |
characters. If a line exceedes for example 30 characters, the line |
| 394 |
will be broken up in several lines. |
| 395 |
|
| 396 |
HTML support |
| 397 |
If you put in <HTML> tags inside the rows, the output would usually |
| 398 |
be broken when viewed in a browser, since the browser "execute" the |
| 399 |
tags instead of displaying it. But if you enable allowHTML. You are |
| 400 |
able to write html tags inside the rows without the output being |
| 401 |
broken if you display it in a browser. But you should not mix this |
| 402 |
with wordwrap, since this could make undesirable results. |
| 403 |
|
| 404 |
ANSI support |
| 405 |
Allows you to decorate your tables with colors or bold/underline |
| 406 |
when you display your tables to a terminal window. |
| 407 |
|
| 408 |
Page-flipping support |
| 409 |
If you don't want the table to get wider than your terminal-width. |
| 410 |
|
| 411 |
Errorreporting |
| 412 |
If you write a script in perl, and don't want users to be notified |
| 413 |
of the errormessages from Text::ASCIITable. You can easily turn of |
| 414 |
error reporting by setting reportErrors to 0. You will still get an |
| 415 |
1 instead of undef returned from the function. |
| 416 |
|
| 417 |
REQUIRES |
| 418 |
Exporter, Carp |
| 419 |
|
| 420 |
AUTHOR |
| 421 |
Håkon Nessjøen, <[email protected]> |
| 422 |
|
| 423 |
VERSION |
| 424 |
Current version is 0.22. |
| 425 |
|
| 426 |
COPYRIGHT |
| 427 |
Copyright 2002-2011 by Håkon Nessjøen. All rights reserved. This module |
| 428 |
is free software; you can redistribute it and/or modify it under the |
| 429 |
same terms as Perl itself. |
| 430 |
|
| 431 |
SEE ALSO |
| 432 |
Text::FormatTable, Text::Table, Text::SimpleTable |
| 433 |
|