Debian Codegraph @

README

raw
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