NAME

Spreadsheet::Read - Read the data from a spreadsheet

SYNOPSYS

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 $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 Excel this module uses Spreadsheet::ParseExcel

For CSV this module uses Text::CSV_XS (0.29 or up prefered) or Text_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");

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

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.

ReadSXC does preserve sheet order as of version 0.20.

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.

attr

Control the generation of the {attr}[c][r] entries. Default is false.

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.

sep

Set separator for CSV. Default is comma ,.

quote

Set quote character for CSV. Default is ".

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 backend parser.

In case of CSV parsing, ReadData () will use the first line to auto-detect the separation character, if not explicitly passed, and the end-of-line sequence. This means that if the first line does not contain embedded newlines, the rest of the CSV file can have them, and they will be parsed correctly.

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 @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.

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, {
             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. Excel only.

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.

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.

AUTHOR

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

COPYRIGHT AND LICENSE

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

To install Spreadsheet::Read, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Spreadsheet::Read

CPAN shell

perl -MCPAN -e shell
install Spreadsheet::Read

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)