1Text::ASCIITable(3)   User Contributed Perl Documentation  Text::ASCIITable(3)
2
3
4

NAME

6       Text::ASCIITable - Create a nice formatted table using ASCII
7       characters.
8

SHORT DESCRIPTION

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

SYNOPSIS

15         use Text::ASCIITable;
16         $t = Text::ASCIITable->new({ headingText => 'Basket' });
17
18         $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
26         # 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

FUNCTIONS

40   new(options)
41       Initialize a new table. You can specify output-options. For more
42       options, check out the usage for setOptions()
43
44         Usage:
45         $t = Text::ASCIITable->new();
46
47         Or with options:
48         $t = Text::ASCIITable->new({ hide_Lastline => 1, reportErrors => 0});
49
50   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
55   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
60         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
63       This module is also overloaded to accept push. To construct a table
64       with the use of overloading you might do the following:
65
66         $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
71         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
79       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
83         Example of multiple-rows pushing:
84         $t->addRow([
85           [ 1, 2, 3 ],
86           [ 4, 5, 6 ],
87           [ 7, 8, 9 ],
88         ]);
89
90   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
96       Example without arguments:
97         $t->addRow('one','two','three');
98         $t->addRowLine();
99         $t->addRow('one','two','three');
100
101       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
108   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
117   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
123   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
128        Usage:
129         $t->setColWidth('Description',30);
130
131   getTableWidth()
132       If you need to know how wide your table will be before you draw it. Use
133       this function.
134
135   setOptions(name,value) or setOptions({ option1 => value1, option2 =>
136       value2, ... })
137       Use this to set options like: hide_FirstLine,reportErrors, etc.
138
139         Usage:
140         $t->setOptions('hide_HeadLine',1);
141
142         Or set more than one option on the fly:
143         $t->setOptions({ hide_HeadLine => 1, hide_HeadRow => 1 });
144
145       Possible Options
146
147       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
154       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
159       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
165       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
172       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
177       hide_FirstLine, hide_HeadLine, hide_LastLine
178           Speaks for it self?
179
180       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
184       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
192           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
197       headingAlign
198           Align the heading(as mentioned above) to left, right, center, auto
199           or using a subroutine.
200
201       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
206       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
216       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
222       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
227             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
237           Note that ->draw() can be omitted, since Text::ASCIITable is
238           overloaded to print the table by default.
239
240   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
246       Custom tables
247
248       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
253        $t->draw(<LINE>,<ROW>,<LINE>,<ROW>,<LINE>,[<ROWLINE>])
254
255       LINE
256           Takes an array of 4 strings. For example "['|','|','-','+']"
257
258           •   LEFT - Defines the left chars. May be more than one char.
259
260           •   RIGHT - Defines the right chars. May be more then one char.
261
262           •   LINE - Defines the char used for the line. Must be only one
263               char.
264
265           •   DELIMETER - Defines the char used for the delimeters. Must be
266               only one char.
267
268       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
273           •   LEFT - Define the char used for the left side of the table.
274
275           •   RIGHT - Define the char used for the right side of the table.
276
277           •   DELIMETER - Defines the char used for the delimeters.
278
279       Examples:
280
281       The easiest way:
282
283        print $t;
284
285       Explanatory example:
286
287        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
294       Nice example:
295
296        print $t->draw( ['.','.','-','-'],   # .-------------.
297                        ['|','|','|'],       # | info | info |
298                        ['|','|','-','-'],   # |-------------|
299                        ['|','|','|'],       # | info | info |
300                        [' \\','/ ','_','|'] #  \_____|_____/
301                       );
302
303       Nice example2:
304
305        print $t->draw( ['.=','=.','-','-'],   # .=-----------=.
306                        ['|','|','|'],         # | info | info |
307                        ['|=','=|','-','+'],   # |=-----+-----=|
308                        ['|','|','|'],         # | info | info |
309                        ["'=","='",'-','-']    # '=-----------='
310                       );
311
312       With Options:
313
314        $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
331       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
335       User-defined subroutines for aligning
336
337       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
341         Here's a exampleroutine that aligns the text to the right.
342
343         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
350         $t->alignCol('Info',\&myownalign_cb);
351
352       User-defined subroutines for counting
353
354       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
359         $t->setOptions('cb_count',\&myallowansi_cb);
360         sub myallowansi_cb {
361           $_=shift;
362           s/\33\[(\d+(;\d+)?)?[musfwhojBCDHRJK]//g;
363           return length($_);
364         }
365
366   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
371       Example:
372
373         $t->setOptions('outputWidth',80);
374         for my $page (1..$t->pageCount()) {
375           print $t->drawPage($page)."\n";
376           print "continued..\n\n";
377         }
378

FEATURES

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
383       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
389       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
399       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
404       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
409       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
417       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
421       Page-flipping support
422           If you don't want the table to get wider than your terminal-width.
423
424       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

REQUIRES

431       Exporter, Carp
432

AUTHOR

434       Haakon Nessjoen, <lunatic@cpan.org>
435

VERSION

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

SEE ALSO

445       Text::FormatTable, Text::Table, Text::SimpleTable
446
447
448
449perl v5.36.0                      2022-07-22               Text::ASCIITable(3)
Impressum