NAME

CSV::Template - A CSV templating module derived from HTML::Template

SYNOPSIS

  use CSV::Template;

  my $csv = CSV::Template->new(filename => "templates/test.tmpl");

  $csv->param(report_title => $csv->quote_string('My "Report"'));
  $csv->param(report_data => [
            { one => 1, two => 2, three => 3 },
            { one => 2, two => 4, three => 6 },
            { one => 3, two => 6, three => 9 },     
          ]);

  print $csv->output();

DESCRIPTION

This is really just a subclass of HTML::Template that does some minor post processing of the output. Since HTML::Template really just operates on plain text, and not HTML specifically, it dawned on me that there is no reason why I should not use HTML::Template (and all my HTML::Template friendly data structures) to generate my CSV files as well.

Now this is by no means a full-features CSV templating system. Currently it serves my needs which is to display report output in both HTML (with HTML::Template) and in CSV (to be viewed in Excel).

METHODS

It is best to refer to the HTML::Template docs, we only implement one method here, and override another.

quote_string ($string_to_quote)

This method can be used to quote strings with embedded comma's (they must be quoted properly so as not to be confused with the comma delimiter). In addition it handles strings which themselves have embedded double quotes. It returns the quoted string.

output

We do some post processing of the normal HTML::Template output here to make sure our display comes out correctly, by basically removing any totally blank lines from our output.

The reason for this is that when writing code for a template it is more convient to do this:

  <TMPL_LOOP NAME="report_data">
  <TMPL_VAR NAME="one">,<TMPL_VAR NAME="two">,<TMPL_VAR NAME="three">,
  </TMPL_LOOP>

Than it is to have to do this:

  <TMPL_LOOP NAME="report_data"><TMPL_VAR NAME="one">,<TMPL_VAR NAME="two">,<TMPL_VAR NAME="three">,
  </TMPL_LOOP>

The first example would normally leave an extra line in the output as a consequence of formating our template code the way we did. The second example avoids that problem, but at the sacrifice of clarity (in my opinion of course).

To remedy this problem, I decided that any empty lines should be removed from the output. If you desire a blank line in your output, then simply put a single comma on that line. Excel should see and understand this as a blank line (at least my copy does).

CAVEAT

This module makes no attempt to automatically quote strings with embedded commas, that is the responsibilty of the user. More automated string handling is on my "TO DO" list.

TO DO

This is really just a quick fix for now, it serves my current needs. But that is not to say that I cannot see the possibilites for more features.

Add "width" features

It would be nice if we could pad lines to a constant width, so that all the lines were of equal length. This would be useful when using this to prepare files for insertion into a database, etc. It shouldnt be too hard to accomplish.

Automatic string handling features

I would like to handle this in the code, so the template author and creater of the data-structure do not have to. Unfortunately I don't know enough yet about the inner workings of HTML::Template to do that, so it will have to wait.

BUGS

None that I am aware of. Of course, if you find a bug, let me know, and I will be sure to fix it.

CODE COVERAGE

I use Devel::Cover to test the code coverage of my tests, below is the Devel::Cover report on this module test suite.

 ---------------------------- ------ ------ ------ ------ ------ ------ ------
 File                           stmt branch   cond    sub    pod   time  total
 ---------------------------- ------ ------ ------ ------ ------ ------ ------
 /CSV/Template.pm              100.0    n/a    n/a  100.0  100.0   47.4  100.0
 t/10_CSV_Template_test.t      100.0    n/a    n/a  100.0    n/a   52.6  100.0
 ---------------------------- ------ ------ ------ ------ ------ ------ ------ 
 Total                         100.0    n/a    n/a  100.0  100.0  100.0  100.0
 ---------------------------- ------ ------ ------ ------ ------ ------ ------ 

Keep in mind this module only overrides one method in HTML::Template, so there is not much to cover here.

OTHER CSV MODULES

There are also a number of other CSV related modules out there, here are a few of the more file/persistence-related that I looked at before eventually creating this module.

DBD::CSV

This was very much overkill for my needs, but maybe not for yours.

Tie::CSV_File

This uses tie, which I am not a fan of, to map arrays of arrays to a CSV file. It would not handle my HTML::Template data structures, but if that is not a requirement of yours, give it a look.

SEE ALSO

HTML::Template

This module is a subclass of HTML::Template, so if you want to know how to use it you will need to refer to that module's excellent documentation.

AUTHOR

stevan little, <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

Copyright 2004 by Infinity Interactive, Inc.

http://www.iinteractive.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm CSV::Template

perl -MCPAN -e shell
install CSV::Template