The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-CSV-R-0.3
River stage zero No dependents
++
/ Text::CSV::R

NAME

Text::CSV::R - Text::CSV wrapper similar to R's read.table and write.table

SYNOPSIS

  #use Text::CSV::R qw(:all);
  use Text::CSV::R qw(read_table write_csv colnames rownames);

  my $M = read_table($filename, %options);

  print join(q{,}, @{ colnames($M) });
  print join(q{,}, @{ rownames($M) });

  print $M->[0][0];

  for my $row (@{$M}) {
    for my $col (@{$row}) {
        # do someting with $col
    }
  }

  write_csv($M, $newfilename);

DESCRIPTION

This is just a convenient wrapper around Text::CSV. It behaves mostly like R's read.table and write.table functions. This module has a very simple API and uses the simplest possible data structure for a table: a reference to a two-dimensional array. It is very lightweight and has Text::CSV as only dependency.

EXPORT_OK

By default Text::CSV::R does not export any subroutines. The subroutines defined are

read_table($file, %options)

Parses $file with the specified options (see "OPTIONS"). Returns the data as reference to a two-dimensional array. Internally, it is an array tied to Text::CSV::R::Matrix, which allows optional storing of column and row names. The $file can be a filename or a filehandle.

read_csv($file, %options)

Alias for

    read_table($file, sep_char => q{,}, header => 1 );
read_csv2($file, %options)

Alias for

    read_table($file, sep_char => q{;}, header => 1, dec => q{,} );
read_delim($file, %options)

Alias for

    read_table($file, sep_char => "\t", header => 1 );
write_table($array_ref, $file, %options)

Writes the two-dimensional $array_ref to $file with the specified options (see "OPTIONS"). If array is tied to Text::CSV::R::Matrix, then col and rownames are written (see "OPTIONS"). The $file can be a filename or a filehandle.

  my $M = read_table($file);
  write_table($M, $newfile, row_names => 0); # print only colnames

  # write a normal 2D array, there are no column and rownames, so just print
  # the fields 
  write_table(\@array, $newfile);

Headers include no column for the row names, i.e. the number of columns in the header is the number of data columns - 1 if row names are provided.

write_csv($array_ref, $file, %options)

Similar to

    write_table($file, sep_char => q{,} );

The only difference is that headers include a column for the row names.

colnames($M, $array_ref)

Get and set (if $array_ref defined) the colnames.

rownames($M, $array_ref)

Get and set (if $array_ref defined) the rownames.

OPTIONS

All non-R options are passed to Text::CSV. Listed are now the supported R options. If there is a Text::CSV equivalent, you can either use the Text::CSV or the R option name. There might be subtle differences to the R implementation.

Read and Write Options
sep
  Text::CSV  : sep_char 
  R          : sep
  Default    : \t 
  Description: the field separator character
dec
  Text::CSV   :  
  R           : dec
  Default     : .
  Description : the character used in the file for decimal points.
fill
  Text::CSV   : 
  R           : fill
  Default     : 0 for read, 1 for write
  Description : if true then in case the rows have unequal length, blank
                fields are implicitly added.
quote
  Text::CSV   : quote_char 
  R           : quote
  Default     : "
  Description : the quoting character
encoding
  Text::CSV   : 
  R           : encoding
  Default     : 
  Description : if specified, the file is opened with ':encoding(value)'
Read Options
  Text::CSV   :  
  R           : header
  Default     : 0
  Description : a logical value indicating whether the file contains the
                column names as its first line. If not specified, set to
                1 if and only if the first row contains one fewer field 
                than the row with the maximal number of fields.
blank_lines_skip
  Text::CSV   :  
  R           : blank.lines.skip
  Default     : 1
  Description : a logical value indicating whether blank lines in the 
                input are ignored.
nrows
  Text::CSV   :  
  R           : nrows
  Default     : -1
  Description : the maximum number of rows to read in.  Negative values 
                are ignored.
skip
  Text::CSV   :  
  R           : skip
  Default     : 0
  Description : the number of lines of the data file to skip before
                beginning to read data
strip_white
  Text::CSV   : allow_whitespace 
  R           : strip.white
  Default     : 0
  Description : allows the stripping of leading and trailing white space
row_names
  Text::CSV   : 
  R           : row.names
  Default     : 
  Description : if specified, it defines the column with the row names. If
                not, set to 0 if and only if the first row contains one 
                fewer field than the row with the maximal number of fields.  
                Otherwise, rownames will be 1 .. #rows.
Write Options
eol
  Text::CSV   : eol
  R           : eol
  Default     : \n
  Description : the character(s) to print at the end of each line (row).
append
  Text::CSV   : 
  R           : append
  Default     : 
  Description : Only relevant if 'file' is a character string.  If true,
                the output is appended to the file.  Otherwise, any
                existing file of the name is destroyed.
col_names, row_names
  Text::CSV   : 
  R           : col.names, row.names
  Default     : 1 if array is tied to Text::CSV::R::Matrix, 0 otherwise
  Description : if scalar, then specifies whether col and rownames should be 
                printed.  Requires that array is tied to Text::CSV::R::Matrix.
                It is also possible to provide the col and rownames by array
                reference.

SEE ALSO

Text::CSV, Text::CSV::Slurp, Spreadsheet::Read

DIFFERENCES TO R

Due to the language differences: Dots in function and option names are replaced with underscores and indexing starts with 0, not 1.
The sep and quote options in R support multiple characters, the Text::CSV counterparts do not.

BUGS AND LIMITATIONS

The encode option requires Perl 5.8 or newer.

Please report any bugs or feature requests to bug-text-csv-r@rt.cpan.org, or through the web interface at http://rt.cpan.org.

COPYRIGHT AND LICENSE

Copyright (C) 2010 <limaone@cpan.org>

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.