NAME

Spreadsheet::Read - Read the data from a spreadsheet

SYNOPSYS

use Spreadsheet::Read; my $csv = ReadData ("test.csv", sep => ";"); my $sxc = ReadData ("test.sxc"); my $xls = ReadData ("test.xls");

DESCRIPTION

Spreadsheet::Read tries to transparantly read *any* spreadsheet and return it's content in a universal manner independant of the parsing module that does the actual spreadsheet scanning.

For OpenOffice this module uses Spreadsheet::ReadSXC

For Excel this module uses Spreadsheet::ParseExcel

For CSV this module uses Text::CSV_XS

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",
	  },
 	# 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,
 	  B4     => "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 metadata. 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");

my $ref = ReadData ("file.sxc");

my $ref = ReadData ("content.xml");

my $ref = ReadData ($content);

Tries to convert the given file, string, or stream to the data structure described above.

Precessing data from a stream or content is supported for Excel (through a File::Temp temporary file), or for XML (OpenOffice), but not for CSV.

Currently ReadSXC does not preserve sheet order.

Currently supported options are:

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.

sep

Set separator for CSV. Default is comma ,.

quote

Set quote character for CSV. Default is ".

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)

TODO

Cell attributes

Future plans include cell attributes, available as for example:

 	{ label  => "Sheet 1",
 	  maxrow => 2,
 	  maxcol => 4,
 	  cell   => [ undef,
	    [ undef, 1 ],
	    [ undef, undef, undef, undef, undef, "Nugget" ],
	    ],
 	  attr   => [ undef,
 	    [ undef, {
 	      color  => "Red",
 	      font   => "Arial",
 	      size   => "12",
 	      format => "## ###.##",
 	      align  => "right",
 	      }, ]
	    [ undef, undef, undef, undef, undef, {
 	      color  => "#e2e2e2",
 	      font   => "LetterGothic",
 	      size   => "15",
 	      format => undef,
 	      align  => "left",
 	      }, ]
 	  A1     => 1,
 	  B4     => "Nugget",
 	  },

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.

Safety / flexibility

Make the different formats/modules just load if available and ignore if not available.

OO-ify

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

http://search.cpan.org/~jwied/

A pure perl version is available on http://search.cpan.org/~makamaka/

Spreadsheet::ParseExcel

http://search.cpan.org/~kwitknr/

Spreadsheet::ReadSXC

http://search.cpan.org/~terhechte/

Text::CSV_XS, Text::CSV

http://search.cpan.org/~jwied/ http://search.cpan.org/~alancitt/

AUTHOR

H.Merijn Brand, <h.m.brand@xs4all.nl>

COPYRIGHT AND LICENSE

Copyright (C) 2005-2005 H.Merijn Brand

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