Template::Plugin::ASCIITable
[% USE ASCIITable %]
blah
[% ASCIITable.cols('a', 'b', 'c');
ASCIITable.rows([1,2,3],['one','two','three']);
ASCIITable.draw() %]
This module allows you to use Text::ASCIITable in your templates.
A plugin object will be instantiated with the directive:
[% USE ASCIITable %]
You can pass a number of parameters to the constructor, for example:
[% USE ASCIITable(cols => ['a','b','c'], show=>'rowline') %]
See "Parameters" for details.
To obtain the table, you invoke the draw method, to which you can pass the same parameters:
[% ASCIITable.draw(rows=>[[1,2,3],['one','two','three']]) %]
newThis is the plugin construtor. You should never call it directly: use the USE directive.
drawThis method invokes Text::ASCIITable to obtain the textual representation of the table, and returns it.
You can pass various parameters to it, see "Parameters".
These parameters can be set in three ways:
draw callAll three forms are case-insensitive: you can do
[% USE t=ASCIITable(allow=>'HTML') %]
[% t.Allow('html') %]
[% t.draw(ALLOW=>'HtMl') %]
hideThis parameter accepts a list of names of features to hide. The recognized names are:
firstlineThe very first decoration line of the table, before the column names.
headrowThe line containing the names of the columns.
headlineThe decoration line separating the column names from the data lines.
rowlineThe decoration line separating one data line from the next. Hidden by default.
lastlineThe very last decoration line, after all the data.
Note: t.hide('headrow');t.hide('headline') will cause both features to be hidden. See "show".
showThis parameter does the opposite of hide: sets the given features to be shown.
Note: t.show('headrow');t.show('headline') will cause both features to be shown. See "hide".
errorsSetting this to a true value will set the reportErrors option (see Text::ASCIITable).
allowThis parameter accepts a list of markup names to allow inside the cells. This in needed to let Text::ASCIITable calculate the correct column widths. The recognized markups are:
ansiThis will allow you to use ANSI escape sequences for things like colors or baldface. This usually works only if you output to a compliant terminal.
htmlThis will allow you to use HTML tags. No check is performed on the well-formedness of any such tag.
Note: t.allow('html');t.allow('ansi') will cause both markups to be recognized. See "deny".
denyThis parameter does the opposite of allow: ignores the given markups inside cells, counting them as data.
Note: t.deny('html');t.deny('ansi') will cause both markups to be ignored. See "allow".
alignHeadRowSets the alignment for the column names. Can be one of:
colsThis parameter sets the names, and optionally some properties, of all the columns in the table. To add columns to an existing table, use the "addCols" parameter (usually as a method).
This parameter accepts a list of column specifications. Each specification can be:
that becomes the name of the column, and width and alignment default to 'auto'
that contains, in order:
Note: this sets all of the columns. t.cols('a','b');t.cols('c') will result in a table with only 1 column. See "addCols".
addColsThis parameter works like cols, but adds the given columns to the existing ones, instead of replacing them. So t.cols('a','b');t.addCols('c') will result in a table with 3 columns.
rowsThis parameter accepts a list of array references, one per row. Each row must have one scalar element per each column that will be produced.
Note that, because of the way this plugin works, you can do something like:
[% USE t=ASCIITable(cols=>['a','b']);
t.rows([1,2,3],[4,5,6]);
t.addCols('c');
t.draw() %]
And it will print a 3x2 table.
Note: this sets all of the rows. t.rows([1,2,3],[4,5,6]);t.rows([7,8,9]) will result in a table with only 1 row. See "addRows".
addRowsThis parameter works like rows, but adds the given rows to the existing ones, instead of replacing them. So t.rows([1,2,3],[4,5,6]);t.addRows([7,8,9]) will result in a table with 3 rows.
styleThis parameter sets the draw style for the table. You can set it to a list of array references, or to a style name.
If you pass it a list, it can have 5, 6, or 8 elements. The first 6 elements are interpreted in the same way as the parameters of Text::ASCIITable::draw (see "Custom tables" in Text::ASCIITable). The last two, which default to 0, are the number of columns to remove on the left- and right-hand side of the generated table; this is used to have tables without vertical borders.
If you pass it a style name, it must be one of the following:
defaultthis is the default Text::ASCIITable style:
.--------------------------. | one | two | three | four | +-----+-----+-------+------+ | one | one | one | one | | two | two | two | two | '-----+-----+-------+------'
rest-simplethis is the "simple table" style as used in reStructuredText:
===== ===== ======= ====== one two three four ===== ===== ======= ====== one one one one two two two two ===== ===== ======= ======
If you give show('rowline') you get:
===== ===== ======= ====== one two three four ===== ===== ======= ====== one one one one ----- ----- ------- ------ two two two two ===== ===== ======= ======
Note that there is no blank space on either side.
rest-gridthis is the "grid table" style as used in reStructuredText:
+-----+-----+-------+------+ | one | two | three | four | +=====+=====+=======+======+ | one | one | one | one | +-----+-----+-------+------+ | two | two | two | two | +-----+-----+-------+------+
Better tests?
None known so far. If you find any, please report them using rt.cpan.org or e-mail. It would be great if you could provide a simple test case that exercises the bug.
Copyright (C) 2005 dakkar <dakkar@thenautilus.net>
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1;
