table of contents
Read(3pm) | User Contributed Perl Documentation | Read(3pm) |
NAME¶
Spreadsheet::Read - Read the data from a spreadsheet
SYNOPSIS¶
use Spreadsheet::Read; my $book = ReadData ("test.csv", sep => ";"); my $book = ReadData ("test.sxc"); my $book = ReadData ("test.ods"); my $book = ReadData ("test.xls"); my $book = ReadData ("test.xlsx"); my $book = ReadData ($fh, parser => "xls"); my $sheet = $book->[1]; # first datasheet my $cell = $book->[1]{A3}; # content of field A3 of sheet 1 my $cell = $book->[1]{cell}[1][3]; # same, unformatted
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 and/or LibreOffice this module uses Spreadsheet::ReadSXC For Microsoft Excel this module uses Spreadsheet::ParseExcel, Spreadsheet::ParseXLSX, or Spreadsheet::XLSX. For CSV this module uses Text::CSV_XS or Text::CSV_PP. For SquirrelCalc there is a very simplistic built-in parserData structure¶
The data is returned as an array reference:$book = [ # Entry 0 is the overall control hash { sheets => 2, sheet => { "Sheet 1" => 1, "Sheet 2" => 2, }, type => "xls", parser => "Spreadsheet::ParseExcel", version => 0.59, error => undef, }, # 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 = %{$book->[$book->[0]{sheet}{"Sheet 2"}]};
Functions¶
- my $book = ReadData ($source [, option => value [, ... ]]);
- my $book = ReadData ("file.csv", sep => ',', quote => '"');
- my $book = ReadData ("file.xls", dtfmt => "yyyy-mm-dd");
- my $book = ReadData ("file.ods");
- my $book = ReadData ("file.sxc");
- my $book = ReadData ("content.xml");
- my $book = ReadData ($content);
- my $book = 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", "libreoffice") "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 rows and columns per sheet that have no visual data. If a sheet has no data at all, the sheet will be skipped entirely when this attribute is true. 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::Peek). A value of 9 and higher will dump the entire structure from the back-end parser.
All other attributes/options will be passed to the underlying parser if that
parser supports attributes.
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 """. When an error is found in the CSV, it is automatically reported (to STDERR). The structure will store the error in "$ss->[0]{error}" as anonymous list returned by "$csv->error_diag". See Text::CSV_XS for documentation.my $ss = ReadData ("bad.csv"); $ss->[0]{error} and say $ss->[0]{error}[1];
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 ($sheet, $row)
- my @row = Spreadsheet::Read::row ($book->[1], 3)
- Get full row of formatted values (like "$sheet->{A3} .. $sheet->{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 ($book, $row)
- my @row = Spreadsheet::Read::cellrow ($book->[1], 3)
- Get full row of unformatted values (like "$sheet->{cell}[1][3] .. $sheet->{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 ($book)
- my @rows = Spreadsheet::Read::rows ($book->[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.
TOOLS¶
This modules comes with a few tools that perform tasks from the FAQ, like "How do I select only column D through F from sheet 2 into a CSV file?" If the module was installed without the tools, you can find them here:http://repo.or.cz/w/Spreadsheet-Read.git/tree/HEAD:/examples
"xlscat"¶
Show (parts of) a spreadsheet in plain text, CSV, or HTMLusage: xlscat [-s <sep>] [-L] [-n] [-A] [-u] [Selection] file.xls [-c | -m] [-u] [Selection] file.xls -i [-S sheets] file.xls Generic options: -v[#] Set verbose level (xlscat/xlsgrep) -d[#] Set debug level (Spreadsheet::Read) -u Use unformatted values --noclip Do not strip empty sheets and trailing empty rows and columns -e <enc> Set encoding for input and output -b <enc> Set encoding for input -a <enc> Set encoding for output Input CSV: --in-sep=c Set input sep_char for CSV Input XLS: --dtfmt=fmt Specify the default date format to replace 'm-d-yy' the default replacement is 'yyyy-mm-dd' Output Text (default): -s <sep> Use separator <sep>. Default '|', \n allowed -L Line up the columns -n Number lines (prefix with column number) -A Show field attributes in ANSI escapes Output Index only: -i Show sheet names and size only Output CSV: -c Output CSV, separator = ',' -m Output CSV, separator = ';' Output HTML: -H Output HTML Selection: -S <sheets> Only print sheets <sheets>. 'all' is a valid set Default only prints the first sheet -R <rows> Only print rows <rows>. Default is 'all' -C <cols> Only print columns <cols>. Default is 'all' -F <flds> Only fields <flds> e.g. -FA3,B16
"xlsgrep"¶
Show (parts of) a spreadsheet that match a pattern in plain text, CSV, or HTMLusage: xlsgrep [-s <sep>] [-L] [-n] [-A] [-u] [Selection] pattern file.xls [-c | -m] [-u] [Selection] pattern file.xls -i [-S sheets] pattern file.xls Generic options: -v[#] Set verbose level (xlscat/xlsgrep) -d[#] Set debug level (Spreadsheet::Read) -u Use unformatted values --noclip Do not strip empty sheets and trailing empty rows and columns -e <enc> Set encoding for input and output -b <enc> Set encoding for input -a <enc> Set encoding for output Input CSV: --in-sep=c Set input sep_char for CSV Input XLS: --dtfmt=fmt Specify the default date format to replace 'm-d-yy' the default replacement is 'yyyy-mm-dd' Output Text (default): -s <sep> Use separator <sep>. Default '|', \n allowed -L Line up the columns -n Number lines (prefix with column number) -A Show field attributes in ANSI escapes Grep options: -i Ignore case -w Match whole words only -h[#] Show # header lines Output CSV: -c Output CSV, separator = ',' -m Output CSV, separator = ';' Output HTML: -H Output HTML Selection: -S <sheets> Only print sheets <sheets>. 'all' is a valid set Default only prints the first sheet -R <rows> Only print rows <rows>. Default is 'all' -C <cols> Only print columns <cols>. Default is 'all' -F <flds> Only fields <flds> e.g. -FA3,B16
"ss2tk"¶
Show a spreadsheet in a perl/Tk spreadsheet widgetusage: ss2tk [-w <width>] [X11 options] file.xls [<pattern>] -w <width> use <width> as default column width (4)
"xls2csv"¶
Convert a spreadsheet to CSV. This is just a small wrapper over "xlscat".usage: xls2csv [ -o file.csv ] file.xls
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://metacpan.org/release/Text-CSV_XS , http://metacpan.org/release/Text-CSV_PP , and http://metacpan.org/release/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://metacpan.org/release/Spreadsheet-ParseExcel
- Spreadsheet::ParseXLSX
- http://metacpan.org/release/Spreadsheet-ParseXLSX
- Spreadsheet::XLSX
- http://metacpan.org/release/Spreadsheet-XLSX
- Spreadsheet::ReadSXC
- http://metacpan.org/release/Spreadsheet-ReadSXC
- Spreadsheet::BasicRead
- http://metacpan.org/release/Spreadsheet-BasicRead for xlscat likewise functionality (Excel only)
- Spreadsheet::ConvertAA
- http://metacpan.org/release/Spreadsheet-ConvertAA for an alternative set of cell2cr () / cr2cell () pair
- Spreadsheet::Perl
- http://metacpan.org/release/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://metacpan.org/release/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-2014 H.Merijn Brand This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.2014-05-05 | perl v5.18.2 |