NAME

Template::Plugin::ASCIITable

SYNOPSIS

  [% USE ASCIITable %]
  blah
  [% ASCIITable.cols('a', 'b', 'c');
     ASCIITable.rows([1,2,3],['one','two','three']);
     ASCIITable.draw() %]

DESCRIPTION

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']]) %]

METHODS

new

This is the plugin construtor. You should never call it directly: use the USE directive.

draw

This method invokes Text::ASCIITable to obtain the textual representation of the table, and returns it.

You can pass various parameters to it, see "Parameters".

Parameters

These parameters can be set in three ways:

• passing them to the constructor

• passing them to the draw call

• setting them with individual method calls

All three forms are case-insensitive: you can do

  [% USE t=ASCIITable(allow=>'HTML') %]
  [% t.Allow('html') %]
  [% t.draw(ALLOW=>'HtMl') %]

hide

This parameter accepts a list of names of features to hide. The recognized names are:

firstline

The very first decoration line of the table, before the column names.

headrow

The line containing the names of the columns.

headline

The decoration line separating the column names from the data lines.

rowline

The decoration line separating one data line from the next. Hidden by default.

lastline

The very last decoration line, after all the data.

Note: t.hide('headrow');t.hide('headline') will cause both features to be hidden. See "show".

show

This 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".

errors

Setting this to a true value will set the reportErrors option (see Text::ASCIITable).

allow

This 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:

ansi

This 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.

html

This 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".

deny

This 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".

alignHeadRow

Sets the alignment for the column names. Can be one of:

• left

• right

• center

• auto

cols

This 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:

a single string

that becomes the name of the column, and width and alignment default to 'auto'

an array reference

that contains, in order:

• the name

• the alignment for the data, one of 'left', 'right', 'center', 'auto' (see "alignCol" in Text::ASCIITable)

• the maximum width of the column, in characters (see "setColWidth" in Text::ASCIITable)

• whether to force the width of the column, a boolean (see "setColWidth" in Text::ASCIITable, the last parameter)

• the name alignment (see "alignColName" in Text::ASCIITable)

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".

addCols

This 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.

rows

This 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".

addRows

This 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.

style

This 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:

default

this is the default Text::ASCIITable style:

  .--------------------------.
  | one | two | three | four |
  +-----+-----+-------+------+
  | one | one | one   | one  |
  | two | two | two   | two  |
  '-----+-----+-------+------'

rest-simple

this 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-grid

this is the "grid table" style as used in reStructuredText:

 +-----+-----+-------+------+
 | one | two | three | four |
 +=====+=====+=======+======+
 | one | one | one   | one  |
 +-----+-----+-------+------+
 | two | two | two   | two  |
 +-----+-----+-------+------+

TODO

Better tests?

BUGS

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 AND LICENSE

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;

cpanm Template::Plugin::ASCIITable

perl -MCPAN -e shell
install Template::Plugin::ASCIITable