/ 
Spreadsheet-CSV-0.20
River stage zero No dependents
/ Spreadsheet::CSV

NAME

Spreadsheet::CSV - Drop-in replacement for Text::CSV_XS with spreadsheet support

VERSION

Version 0.14

SYNOPSIS

use Spreadsheet::CSV();
use CGI();

my $cgi = CGI->new();
my $handle = $cgi->upload('UploadFile');
my @rows;
my $csv = Spreadsheet::CSV->new();
while (my $row = $csv->getline ($handle)) {
    $row->[2] =~ m/pattern/ or next; # 3rd field should match
    push @rows, $row;
}
$csv->eof() or die $csv->error_diag();
close $handle or die "Screaming:$!";

DESCRIPTION

Spreadsheet::CSV attempts to provide a drop-in replacement for Text::CSV_XS when reading in user-provided input files, such as via Email or Web. This is currently only for reading documents and only via the $csv->getline interface documented above

SUBROUTINES/METHODS

new

(Class method) Returns a new instance of Spreadsheet::CSV. It accepts all the parameters from Text::CSV_XS, as well as two additional ones.

my $csv = Spreadsheet::CSV->new ({ attributes ... });

The following additional attributes are available:

worksheet_name

The worksheet to read from for file handles containing spreadsheets.

worksheet_number

The worksheet to read from for file handles containing spreadsheets (starting from 1). This option will only apply if the worksheet name has not been specified. By default worksheet_number will be '1'

getline 

$colref = $csv->getline ($io);

It reads a row from the IO object and parses this row into an array ref. This array ref is returned by the function or undef for failure. If the IO object points to a known spreadsheet file type, the first call to "getline" will convert the entire file into an in-memory list-of-lists before returning the first row.

Accepted file types are currently

* Microsoft Excel 97 - .xls
* Microsoft Excel 2003 - .xlsx
* OpenOffice - .ods and .sxc
* Gnumeric - .gnumeric
* Kspread - .ksp
* CSV - .csv

Patches for support for other file types would be gratefully accepted.

When checking for CSV, the Text::CSV_XS module will be passed a filehandle containing the same data as the input handle, but with ":encoding(UTF-8)" switched on.

eof 

$eof = $csv->eof ();

This method will return true (1) if the last call hit end of file, otherwise it will return false (''). This is useful to see the difference between a failure and end of file

error_diag

$error_str = $csv->error_diag ();

If (and only if) an error occurred, this function returns the diagnostics of that error.

content_type

$content_type = $csv->content_type ();

After the $handle has been passed to getline, the content_type can be queried. If $handle points to a recognised spreadsheet type, the appropriate content type will be returned (such as 'application/vnd.ms-excel', otherwise, undef will be returned

suffix

$suffix = $csv->suffix ();

After the $handle has been passed to getline, the file suffix can be queried. If $handle points to a recognised spreadsheet type, the suffix will be returned (such as 'xls'), otherwise, undef will be returned

DIAGNOSTICS

If an error occurred, "error_diag" can be used to get more information on the cause of the failure.

CONFIGURATION AND ENVIRONMENT

Spreadsheet::CSV requires no configuration files or environment variables.

DEPENDENCIES

Spreadsheet::CSV requires the following non-core modules

Spreadsheet::ParseExcel
Text::CSV_XS
Archive::Zip
XML::Parser
Compress::Zlib

and the following core modules

Fcntl
English
Carp
IO::File

AUTHOR

David Dick, <ddick at cpan.org>

INCOMPATIBILITIES

The only spreadsheets supported at the moment are

Microsoft Excel 97
Microsoft Excel 2003
OpenOffice
Gnumeric
KSpread
CSV

BUGS AND LIMITATIONS

At the moment this library will read everything into RAM. It relies on the system enforcing the reasonable limits for file size, to allow these files to be read into RAM. This may change in the future.

Spreadsheet::ParseExcel can lose precision when extracting floating point numbers

Please report any bugs or feature requests to bug-spreadsheet-csv at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Spreadsheet-CSV. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can look for information at:

LICENSE AND COPYRIGHT

Copyright 2013 David Dick.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.