Open-ILS/src/perlmods/lib/Template/Plugin/CSVFilter.pm

   1 # ---------------------------------------------------------------
   2 # Copyright © 2014 Merrimack Valley Library Consortium
   3 # Jason Stephenson <jstephenson@mvlc.org>
   4 #
   5 # This program is free software; you can redistribute it and/or modify
   6 # it under the terms of the GNU General Public License as published by
   7 # the Free Software Foundation; either version 2 of the License, or
   8 # (at your option) any later version.
   9 #
  10 # This program is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 # GNU General Public License for more details.
  14 # ---------------------------------------------------------------
  15 package Template::Plugin::CSVFilter;
  16 use Template::Plugin::Filter;
  17
  18 use base qw(Template::Plugin::Filter);
  19
  20 our $VERSION = "1.00";
  21
  22 sub init {
  23     my $self = shift;
  24
  25     $self->{_DYNAMIC} = 1;
  26     $self->install_filter($self->{_ARGS}->[0] || 'CSVFilter');
  27
  28     return $self;
  29 }
  30
  31 sub filter {
  32     my ($self, $text, $args, $conf) = @_;
  33
  34     $args = $self->merge_args($args);
  35     $conf = $self->merge_config($conf);
  36
  37     my $quote_char = $conf->{quote_char} || '"';
  38     my $delim = $conf->{separator} || ',';
  39     my $force_quotes = grep {$_ eq 'force_quotes'} @$args;
  40     if ($text) {
  41         $text =~ s/$quote_char/$quote_char$quote_char/g;
  42         $text = $quote_char . $text . $quote_char
  43             if ($force_quotes || $text =~ /[$delim$quote_char\r\n]/);
  44     }
  45     $text .= $delim unless(grep {$_ eq 'last'} @$args);
  46
  47     return $text;
  48 }
  49
  50 1;
  51 __END__
  52
  53 =pod
  54
  55 =head1 NAME
  56
  57 Template::Plugin::CSVFilter - Template Toolkit2 Filter for CSV fields
  58
  59 =head1 SYNOPSIS
  60
  61     [%- USE CSVFilter 'csv';
  62         FOREACH row IN rows;
  63           FOREACH field IN row;
  64             IF loop.count == loop.size;
  65               field | csv 'last';
  66             ELSE;
  67               field | csv;
  68             END;
  69           END; %]
  70     [%  END -%]
  71
  72 You can use the above as a template for a CSV output file,
  73 provided that you arrange your data variable to have a 'rows' member
  74 that is an array ref containing array refs of the fields for each row:
  75
  76     $var = {rows => [[...], ...]};
  77
  78 If you want headers in the first row of the output, then make sure the
  79 header fields make up the first sub array of 'rows' array.
  80
  81 =head1 DESCRIPTION
  82
  83 Template::Plugin::CSVFilter adds a filter that you can use in Template
  84 Toolkit2 templates to output data that is suitably formatted for
  85 inclusion in a CSV type file.  The filter will see to it that the
  86 field is properly quoted and that any included quote symbols are
  87 properly escaped.  It will also add the separator character after the
  88 field's text.
  89
  90 =head1 OPTIONS
  91
  92 CSVFilter accepts the following configuration options that require a
  93 single character argument:
  94
  95 =over
  96
  97 =item *
  98
  99 C<separator> - The argument is the character to use as the field
 100 delimiter.  If this is not specified, a default of , is used.
 101
 102 =item *
 103
 104 C<quote_char> - The argument is the character to for quoting fields.
 105 If this is not specified, a default of " is used.
 106
 107 =back
 108
 109 The above are best set when you use the filter in your template.
 110 However, you can set them at any or every time you use the filter in
 111 your template.
 112
 113 Each call to the filter can be modified by the following two arguments
 114 that do not themselves take an argument:
 115
 116 =over
 117
 118 =item *
 119
 120 C<force_quotes> - If present, this argument causes the field output to
 121 be quoted even if it would not ordinarily be.  If you use this where
 122 you C<USE> the filter, you will need to specify a name for the filter or
 123 the name of the filter will be C<force_quotes>.  If you specify this
 124 option when initializing the filter, then every output field will be
 125 quoted.
 126
 127 =item *
 128
 129 C<last> - This argument must be used on the last field in an output
 130 row in order to suppress output of the C<separator> character.  This
 131 argument must never be used when initializing the filter.
 132
 133 =back
 134
 135 =head1 SEE ALSO
 136
 137     Template
 138     Template::Plugin
 139     Template::Plugin::Filter
 140
 141 =head1 AUTHOR
 142
 143 Jason Stephenson <jstephenson@mvlc.org>
 144
 145
 146 =cut