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