[Catalyst-dev] RFC: Catalyst::View::CSV

[Travis Chase]

I have written a module for producing CSV formatted output as a view. It, of
course, can create any sort of delimited format one desires. Here is the POD
for details.

=3Dhead1 NAME

Catalyst::View::CSV - Comma separated values or Delimiter separated values
for your data

=3Dhead1 SYNOPSIS

  # lib/MyApp/View/CSV.pm
  package MyApp::View::CSV;
  use base qw( Catalyst::View::CSV );
  1;

  # lib/MyApp/Controller/SomeController.pm
  sub example_action_1 : Local {
    my ($self, $c) =3D @_;

    # Array reference of array references.
    my $data =3D [
      ['col 1','col 2','col ...','col N'], # row 1
      ['col 1','col 2','col ...','col N'], # row 2
      ['col 1','col 2','col ...','col N'], # row ...
      ['col 1','col 2','col ...','col N']  # row N
    ];

    # To output your data in comma seperated values just pass your array by
reference into the 'csv' key of the stash
    $c->stash->{'csv'} =3D $data;

    # Finally forward processing to the CSV View
    $c->forward('MyApp::View::CSV');
  }

  # Other ways of storing data
  sub example_action_2 : Local {
    my ($self, $c) =3D @_;

    # Array of array references
    my @data;

    push(@data,['col 1','col 2','col ...','col N']); # row 1
    push(@data,['col 1','col 2','col ...','col N']); # row 2
    push(@data,['col 1','col 2','col ...','col N']); # row ...
    push(@data,['col 1','col 2','col ...','col N']); # row N

    # OR to produce a single column of data you can simply do the following

    my @data =3D (
                'col 1 row 1',
                'col 1 row 2',
                'col 1 row ...',
                'col 1 row N'
               );

    $c->stash->{'csv'} =3D \@data;

    $c->forward('MyApp::View::CSV');
  }

  # Available Options to produce other types of delimiter seperated output
  sub  example_action_3 : Local {
    my ($self, $c) =3D @_;

    my $data =3D [
      ['col 1','col 2','col ...','col N'], # row 1
      ['col 1','col 2','col ...','col N'] # row 2
    ];

    # You can change any of the aspects of a delimiter seperated values
format by storing them in the appropriate stash key
    # This is an example of tab seperated values for instance

    $c->stash->{'quote_char'} =3D '"'; # default: '"'

    $c->stash->{'escape_char'} =3D '"'; # default: '"'

    $c->stash->{'sep_char'} =3D '\t'; # default: ','

    $c->stash->{'eol'} =3D "\n"; # default: "\n"

    $c->stash->{'csv'} =3D $data;
  }

=3Dhead1 DESCRIPTION

Catalyst::View::CSV is a Catalyst View handler that returns data in
delimiter seperated values (default is comma) format.

=3Dhead1 MIME MEDIA TYPE

If the Content-Type HTTP Header is not set, it will default to 'text/csv'.

  # Example of setting your own Content-Type
  $c->res->headers->header('Content-Type' =3D> 'text/plain');

  # Forward processing to CSV View with a text/plain Content-Type
  $c->forward("MyApp::View::CSV");

=3Dhead1 OPTIONS

=3Dover 4

=3Ditem quote_char

Determines what value will be enclosed within if it contains whitespace or
the delimiter character. DEFAULT: '"'

  $c->stash->{'quote_char'} =3D '/';

=3Ditem escape_char

Determines what value will be to escape any delimiter's found in a column.
DEFAULT: '"'

  $c->stash->{'escape_char'} =3D '/';

=3Ditem sep_char

Determines the separator between columns. DEFAULT: ','

  $c->stash->{'sep_char'} =3D '|';

=3Ditem eol

Any characters defined in eol will be placed at the end of a row. DEFAULT:
'\n'

  $c->stash->{'eol'} =3D '\0';

=3Ditem csv

The data that will be processed into delimiter separated values format is
stored here. The data should be an array ref of array refs of scalars or an
array ref of scalars. Note: if nothing is found in csv, the stash is
searched and any array references found will be used as the data instead.

  # Array ref of array refs of scalars
  my $data =3D [
    ['apple','banana','pear'],
    ['red','yellow','green']
  ];

  $c->stash->{csv} =3D $data;

  # Array ref of scalars
  my @data =3D ('Jan','Feb','Mar','Apr');

  $c->stash->{csv} =3D \@data;

=3Dback

=3Dhead1 SUBROUTINES

=3Dover 4

=3Ditem process

This method will be called by Catalyst if it is asked to forward to a
component without a specified action.

=3Ditem render

Allows others to use this view for much more fine-grained content
generation.

=3Ditem _csv

Subroutine that actually produces the delimiter separated values. Intended
to be private in scope to this module.

=3Dback

=3Dhead1 AUTHOR

Travis Chase - gaudeon_at_cpan_dot_org

=3Dhead1 SEE ALSO

L<Catalyst> L<Text::CSV>

=3Dhead1 LICENSE

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

=3Dcut
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.scsys.co.uk/pipermail/catalyst-dev/attachments/20080302/6=
5e389f1/attachment.htm