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