view release on metacpan or  search on metacpan

lib/Text/CSV.pm  view on Meta::CPAN

=pod

=head1 NAME

Text::CSV - comma-separated values manipulator (using XS or PurePerl)


=head1 SYNOPSIS

This section is taken from Text::CSV_XS.

 # Functional interface
 use Text::CSV qw( csv );

 # Read whole file in memory
 my $aoa = csv (in => "data.csv");    # as array of array
 my $aoh = csv (in => "data.csv",
                headers => "auto");   # as array of hash

 # Write array of arrays as csv file
 csv (in => $aoa, out => "file.csv", sep_char => ";");

 # Only show lines where "code" is odd
 csv (in => "data.csv", filter => { code => sub { $_ % 2 }});

 # Object interface
 use Text::CSV;

 my @rows;
 # Read/parse CSV
 my $csv = Text::CSV->new ({ binary => 1, auto_diag => 1 });
 open my $fh, "<:encoding(utf8)", "test.csv" or die "test.csv: $!";
 while (my $row = $csv->getline ($fh)) {
     $row->[2] =~ m/pattern/ or next; # 3rd field should match
     push @rows, $row;
     }
 close $fh;

 # and write as CSV
 open $fh, ">:encoding(utf8)", "new.csv" or die "new.csv: $!";
 $csv->say ($fh, $_) for @rows;
 close $fh or die "new.csv: $!";

=head1 DESCRIPTION

Text::CSV is a thin wrapper for L<Text::CSV_XS>-compatible modules now.
All the backend modules provide facilities for the composition and
decomposition of comma-separated values. Text::CSV uses Text::CSV_XS
by default, and when Text::CSV_XS is not available, falls back on
L<Text::CSV_PP>, which is bundled in the same distribution as this module.

=head1 CHOOSING BACKEND

This module respects an environmental variable called C<PERL_TEXT_CSV>
when it decides a backend module to use. If this environmental variable
is not set, it tries to load Text::CSV_XS, and if Text::CSV_XS is not
available, falls back on Text::CSV_PP;

If you always don't want it to fall back on Text::CSV_PP, set the variable
like this (C<export> may be C<setenv>, C<set> and the likes, depending
on your environment):

  > export PERL_TEXT_CSV=Text::CSV_XS

If you prefer Text::CSV_XS to Text::CSV_PP (default), then:

  > export PERL_TEXT_CSV=Text::CSV_XS,Text::CSV_PP

You may also want to set this variable at the top of your test files, in order
not to be bothered with incompatibilities between backends (you need to wrap
this in C<BEGIN>, and set before actually C<use>-ing Text::CSV module, as it
decides its backend as soon as it's loaded):

  BEGIN { $ENV{PERL_TEXT_CSV}='Text::CSV_PP'; }
  use Text::CSV;

=head1 NOTES

This section is also taken from Text::CSV_XS.

=head2 Embedded newlines

B<Important Note>:  The default behavior is to accept only ASCII characters
in the range from C<0x20> (space) to C<0x7E> (tilde).   This means that the
fields can not contain newlines. If your data contains newlines embedded in
fields, or characters above C<0x7E> (tilde), or binary data, you B<I<must>>
set C<< binary => 1 >> in the call to L</new>. To cover the widest range of
parsing options, you will always want to set binary.

But you still have the problem  that you have to pass a correct line to the
L</parse> method, which is more complicated from the usual point of usage:

 my $csv = Text::CSV->new ({ binary => 1, eol => $/ });
 while (<>) {		#  WRONG!
     $csv->parse ($_);
     my @fields = $csv->fields ();
     }

this will break, as the C<while> might read broken lines:  it does not care
about the quoting. If you need to support embedded newlines,  the way to go
is to  B<not>  pass L<C<eol>|/eol> in the parser  (it accepts C<\n>, C<\r>,
B<and> C<\r\n> by default) and then

 my $csv = Text::CSV->new ({ binary => 1 });
 open my $fh, "<", $file or die "$file: $!";
 while (my $row = $csv->getline ($fh)) {
     my @fields = @$row;
     }

The old(er) way of using global file handles is still supported

 while (my $row = $csv->getline (*ARGV)) { ... }

=head2 Unicode

Unicode is only tested to work with perl-5.8.2 and up.

See also L</BOM>.

The simplest way to ensure the correct encoding is used for  in- and output