Provided by: libspreadsheet-read-perl_0.41-1_all 
NAME
Spreadsheet::Read - Read the data from a spreadsheet
SYNOPSIS
use Spreadsheet::Read;
my $ref = ReadData ("test.csv", sep => ";");
my $ref = ReadData ("test.sxc");
my $ref = ReadData ("test.ods");
my $ref = ReadData ("test.xls");
my $ref = ReadData ("test.xlsx");
my $ref = ReadData ($fh, parser => "xls");
my $a3 = $ref->[1]{A3}, "\n"; # content of field A3 of sheet 1
DESCRIPTION
Spreadsheet::Read tries to transparently read *any* spreadsheet and return its content in
a universal manner independent of the parsing module that does the actual spreadsheet
scanning.
For OpenOffice this module uses Spreadsheet::ReadSXC
For Microsoft Excel this module uses Spreadsheet::ParseExcel or Spreadsheet::XLSX
For CSV this module uses Text::CSV_XS (0.29 or up required, 0.73 or up preferred) or
Text::CSV_PP (1.05 or up required).
For SquirrelCalc there is a very simplistic built-in parser
Data structure
The data is returned as an array reference:
$ref = [
# Entry 0 is the overall control hash
{ sheets => 2,
sheet => {
"Sheet 1" => 1,
"Sheet 2" => 2,
},
type => "xls",
parser => "Spreadsheet::ParseExcel",
version => 0.26,
},
# Entry 1 is the first sheet
{ label => "Sheet 1",
maxrow => 2,
maxcol => 4,
cell => [ undef,
[ undef, 1 ],
[ undef, undef, undef, undef, undef, "Nugget" ],
],
A1 => 1,
B5 => "Nugget",
},
# Entry 2 is the second sheet
{ label => "Sheet 2",
:
:
To keep as close contact to spreadsheet users, row and column 1 have index 1 too in the
"cell" element of the sheet hash, so cell "A1" is the same as "cell" [1, 1] (column
first). To switch between the two, there are two helper functions available: "cell2cr ()"
and "cr2cell ()".
The "cell" hash entry contains unformatted data, while the hash entries with the
traditional labels contain the formatted values (if applicable).
The control hash (the first entry in the returned array ref), contains some spreadsheet
meta-data. The entry "sheet" is there to be able to find the sheets when accessing them by
name:
my %sheet2 = %{$ref->[$ref->[0]{sheet}{"Sheet 2"}]};
Functions
my $ref = ReadData ($source [, option => value [, ... ]]);
my $ref = ReadData ("file.csv", sep => ',', quote => '"');
my $ref = ReadData ("file.xls", dtfmt => "yyyy-mm-dd");
my $ref = ReadData ("file.ods");
my $ref = ReadData ("file.sxc");
my $ref = ReadData ("content.xml");
my $ref = ReadData ($content);
my $ref = ReadData ($fh, parser => "xls");
Tries to convert the given file, string, or stream to the data structure described
above.
Processing Excel data from a stream or content is supported through a File::Temp
temporary file or IO::Scalar when available.
ReadSXC does preserve sheet order as of version 0.20.
Currently supported options are:
parser
Force the data to be parsed by a specific format. Possible values are "csv", "prl" (or
"perl"), "sc" (or "squirelcalc"), "sxc" (or "oo", "ods", "openoffice") "xls" (or
"excel"), and "xlsx" (or "excel2007").
When parsing streams, instead of files, it is highly recommended to pass this option.
cells
Control the generation of named cells ("A1" etc). Default is true.
rc
Control the generation of the {cell}[c][r] entries. Default is true.
attr
Control the generation of the {attr}[c][r] entries. Default is false. See "Cell
Attributes" below.
clip
If set, "ReadData ()" will remove all trailing lines and columns per sheet that have
no visual data. This option is only valid if "cells" is true. The default value is
true if "cells" is true, and false otherwise.
strip
If set, "ReadData ()" will remove trailing- and/or leading-whitespace from every
field.
strip leading strailing
----- ------- ---------
0 n/a n/a
1 strip n/a
2 n/a strip
3 strip strip
sep
Set separator for CSV. Default is comma ",".
quote
Set quote character for CSV. Default is """.
dtfmt
Set the format for M$Excel date fields that are set to use the default date format.
The default format in Excel is 'm-d-yy', which is both not year 2000 safe, nor very
useful. The default is now 'yyyy-mm-dd', which is more ISO-like.
Note that date formatting in M$Excel is not reliable at all, as it will
store/replace/change the date field separator in already stored formats if you change
your locale settings. So the above mentioned default can be either "m-d-yy" OR
"m/d/yy" depending on what that specific character happened to be at the time the user
saved the file.
debug
Enable some diagnostic messages to STDERR.
The value determines how much diagnostics are dumped (using Data::Dumper). A value of
9 and higher will dump the entire structure from the back-end parser.
Using CSV
In case of CSV parsing, "ReadData ()" will use the first line of the file to auto-detect
the separation character if the first argument is a file and both "sep" and "quote" are
not passed as attributes. Text::CSV_XS (or Text::CSV_PP) is able to automatically detect
and use "\r" line endings).
CSV can parse streams too, but be sure to pass "sep" and/or "quote" if these do not match
the default "," and """.
Functions
my $cell = cr2cell (col, row)
"cr2cell ()" converts a "(column, row)" pair (1 based) to the traditional cell
notation:
my $cell = cr2cell ( 4, 14); # $cell now "D14"
my $cell = cr2cell (28, 4); # $cell now "AB4"
my ($col, $row) = cell2cr ($cell)
"cell2cr ()" converts traditional cell notation to a "(column, row)" pair (1 based):
my ($col, $row) = cell2cr ("D14"); # returns ( 4, 14)
my ($col, $row) = cell2cr ("AB4"); # returns (28, 4)
my @row = row ($ref, $row)
my @row = Spreadsheet::Read::row ($ss->[1], 3)
Get full row of formatted values (like "$ss->{A3} .. $ss->{G3}")
Note that the indexes in the returned list are 0-based.
"row ()" is not imported by default, so either specify it in the use argument list, or
call it fully qualified.
my @row = cellrow ($ref, $row)
my @row = Spreadsheet::Read::cellrow ($ss->[1], 3)
Get full row of unformatted values (like "$ss->{cell}[1][3] .. $ss->{cell}[7][3]")
Note that the indexes in the returned list are 0-based.
"cellrow ()" is not imported by default, so either specify it in the use argument
list, or call it fully qualified.
my @rows = rows ($ref)
my @rows = Spreadsheet::Read::rows ($ss->[1])
Convert "{cell}"'s "[column][row]" to a "[row][column]" list.
Note that the indexes in the returned list are 0-based, where the index in the
"{cell}" entry is 1-based.
"rows ()" is not imported by default, so either specify it in the use argument list,
or call it fully qualified.
parses ($format)
Spreadsheet::Read::parses ("CSV")
"parses ()" returns Spreadsheet::Read's capability to parse the required format.
"parses ()" is not imported by default, so either specify it in the use argument list,
or call it fully qualified.
my $rs_version = Version ()
my $v = Spreadsheet::Read::Version ()
Returns the current version of Spreadsheet::Read.
"Version ()" is not imported by default, so either specify it in the use argument
list, or call it fully qualified.
Cell Attributes
If the constructor was called with "attr" having a true value, effort is made to analyze
and store field attributes like this:
{ label => "Sheet 1",
maxrow => 5,
maxcol => 2,
cell => [ undef,
[ undef, 1 ],
[ undef, undef, undef, undef, undef, "Nugget" ],
],
attr => [ undef,
[ undef, {
type => "numeric",
fgcolor => "#ff0000",
bgcolor => undef,
font => "Arial",
size => undef,
format => "## ##0.00",
halign => "right",
valign => "top",
uline => 0,
bold => 0,
italic => 0,
wrap => 0,
merged => 0,
hidden => 0,
locked => 0,
enc => "utf-8",
}, ]
[ undef, undef, undef, undef, undef, {
type => "text",
fgcolor => "#e2e2e2",
bgcolor => undef,
font => "Letter Gothic",
size => 15,
format => undef,
halign => "left",
valign => "top",
uline => 0,
bold => 0,
italic => 0,
wrap => 0,
merged => 0,
hidden => 0,
locked => 0,
enc => "iso8859-1",
}, ]
A1 => 1,
B5 => "Nugget",
},
This has now been partially implemented, mainly for Excel, as the other parsers do not
(yet) support all of that. YMMV.
TODO
Options
Module Options
New Spreadsheet::Read options are bound to happen. I'm thinking of an option that
disables the reading of the data entirely to speed up an index request (how many
sheets/fields/columns). See "xlscat -i".
Parser options
Try to transparently support as many options as the encapsulated modules support
regarding (un)formatted values, (date) formats, hidden columns rows or fields etc.
These could be implemented like "attr" above but names "meta", or just be new values
in the "attr" hashes.
Other spreadsheet formats
I consider adding any spreadsheet interface that offers a usable API.
Add an OO interface
Consider making the ref an object, though I currently don't see the big advantage
(yet). Maybe I'll make it so that it is a hybrid functional / OO interface.
SEE ALSO
Text::CSV_XS, Text::CSV_PP
http://search.cpan.org/dist/Text-CSV_XS , http://search.cpan.org/dist/Text-CSV_PP , and
http://search.cpan.org/dist/Text-CSV .
Text::CSV is a wrapper over Text::CSV_XS (the fast XS version) and/or Text::CSV_PP (the
pure perl version)
Spreadsheet::ParseExcel
http://search.cpan.org/dist/Spreadsheet-ParseExcel
Spreadsheet::XLSX
http://search.cpan.org/dist/Spreadsheet-XLSX
Spreadsheet::ReadSXC
http://search.cpan.org/dist/Spreadsheet-ReadSXC
Spreadsheet::BasicRead
http://search.cpan.org/dist/Spreadsheet-BasicRead for xlscat likewise functionality
(Excel only)
Spreadsheet::ConvertAA
http://search.cpan.org/dist/Spreadsheet-ConvertAA for an alternative set of cell2cr () /
cr2cell () pair
Spreadsheet::Perl
http://search.cpan.org/dist/Spreadsheet-Perl offers a Pure Perl implementation of a
spreadsheet engine. Users that want this format to be supported in Spreadsheet::Read are
hereby motivated to offer patches. It's not high on my TODO-list.
xls2csv
http://search.cpan.org/dist/xls2csv offers an alternative for my "xlscat -c", in the
xls2csv tool, but this tool focuses on character encoding transparency, and requires
some other modules.
AUTHOR
H.Merijn Brand, <h.m.brand@xs4all.nl>
COPYRIGHT AND LICENSE
Copyright (C) 2005-2010 H.Merijn Brand
This library is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.