# perldoc > Spreadsheet::ParseExcel

---
type: CommandReference
command: Spreadsheet::ParseExcel
mode: perldoc
section: 3
source: perldoc
---

## Quick Reference

- `Spreadsheet::ParseExcel->new()` — create parser object
- `$parser->parse('file.xls')` — parse Excel file, returns workbook or undef
- `$workbook->worksheets()` — get array of worksheet objects
- `$worksheet->get_cell($row, $col)` — get cell object at (row, col)
- `$cell->value()` — get formatted cell value
- `$cell->unformatted()` — get unformatted value
- `$parser->error()` — error string on failure
- `$parser->error_code()` — error code (0=ok, 1=not found, 2=no data, 3=encrypted)

## Name

Read information from an Excel 95-2003 binary file.

## Synopsis

perl
#!/usr/bin/perl -w
use strict;
use Spreadsheet::ParseExcel;

my $parser   = Spreadsheet::ParseExcel->new();
my $workbook = $parser->parse('Book1.xls');

if ( !defined $workbook ) {
    die $parser->error(), ".\n";
}

for my $worksheet ( $workbook->worksheets() ) {
    my ( $row_min, $row_max ) = $worksheet->row_range();
    my ( $col_min, $col_max ) = $worksheet->col_range();

    for my $row ( $row_min .. $row_max ) {
        for my $col ( $col_min .. $col_max ) {
            my $cell = $worksheet->get_cell( $row, $col );
            next unless $cell;

            print "Row, Col    = ($row, $col)\n";
            print "Value       = ", $cell->value(),       "\n";
            print "Unformatted = ", $cell->unformatted(), "\n";
            print "\n";
        }
    }
}
## Methods

### Parser

- `new()` — create parser. Optional args: `Password => 'secret'` (decrypt), `CellHandler => \&handler, NotSetCell => 1` (reduce memory)
- `parse($filename, $formatter)` — parse Excel file. `$filename` can be file, filehandle, or scalar ref. `$formatter` is formatter object (e.g. `Spreadsheet::ParseExcel::FmtJapan`). Returns workbook or undef.
- `error()` — returns error string: '' (success), 'File not found', 'No Excel data found in file', 'File is encrypted'
- `error_code()` — returns integer code: 0 (success), 1, 2, 3

### Workbook

- `worksheets()` — returns array of `Spreadsheet::ParseExcel::Worksheet` objects
- `worksheet($name_or_index)` — returns single worksheet by name or index (0-based). Returns undef if not found.
- `worksheet_count()` — number of worksheets
- `get_filename()` — filename or undef if read from filehandle

### Worksheet

- `get_cell($row, $col)` — returns `Spreadsheet::ParseExcel::Cell` object or undef
- `row_range()` — returns `($min, $max)` of defined rows
- `col_range()` — returns `($min, $max)` of defined columns
- `get_name()` — worksheet name (e.g., 'Sheet1')

### Cell

- `value()` — formatted cell value (e.g., date string, number with commas)
- `unformatted()` — raw cell value (numeric/string without formatting)

### Format properties (accessed via `$cell->{Format}`)

- `{Font}` — Font object
- `{AlignH}` — horizontal alignment: 0=none,1=left,2=center,3=right,4=fill,5=justify,6=center across,7=distributed
- `{AlignV}` — vertical alignment: 0=top,1=center,2=bottom,3=justify,4=distributed
- `{Indent}` — indent level for left alignment
- `{Wrap}` — true if text wrap on
- `{Shrink}` — true if shrink to fit
- `{Rotate}` — text rotation; in Excel97+ returns degrees; in older returns 0=none,1=top down,2=90° anti-clockwise,3=90° clockwise
- `{JustLast}` — true if justify last
- `{ReadDir}` — text reading direction
- `{BdrStyle}` — array ref `[$left, $right, $top, $bottom]`
- `{BdrColor}` — array ref of border color indexes
- `{BdrDiag}` — array ref `[$kind, $style, $color]` where kind: 0=none,1=right-down,2=right-up,3=both
- `{Fill}` — array ref `[$pattern, $front_color, $back_color]`
- `{Lock}` — true if cell locked
- `{Hidden}` — true if cell hidden
- `{Style}` — true if format is a style format

### Font properties (accessed via `$format->{Font}`)

- `{Name}` — font name string (e.g., 'Arial')
- `{Bold}` — true if bold
- `{Italic}` — true if italic
- `{Height}` — font size (height)
- `{Underline}` — true if underlined
- `{UnderlineStyle}` — 0=none,1=single,2=double,33=single accounting,34=double accounting
- `{Color}` — color index; convert to RGB via `$workbook->ColorIdxToRGB()`
- `{Strikeout}` — true if strikeout
- `{Super}` — 0=none,1=superscript,2=subscript

## Examples

### Basic usage with cell handler (reduced memory)

perl
#!/usr/bin/perl -w
use strict;
use Spreadsheet::ParseExcel;

my $parser = Spreadsheet::ParseExcel->new(
    CellHandler => \&cell_handler,
    NotSetCell  => 1
);

my $workbook = $parser->parse('file.xls');

sub cell_handler {
    my $workbook    = $_[0];
    my $sheet_index = $_[1];
    my $row         = $_[2];
    my $col         = $_[3];
    my $cell        = $_[4];

    # Do something with the formatted cell value
    print $cell->value(), "\n";
}
### Abort parsing early

perl
sub cell_handler {
    my $workbook    = $_[0];
    my $sheet_index = $_[1];
    my $row         = $_[2];
    my $col         = $_[3];
    my $cell        = $_[4];

    if ( $sheet_index >= 1 and $row >= 10 ) {
        $workbook->ParseAbort(1);
        return;
    }
    print $cell->value(), "\n";
}
### Decrypt with password

perl
my $parser = Spreadsheet::ParseExcel->new( Password => 'secret' );
my $workbook = $parser->parse('encrypted.xls');
## Exit Codes

- 0: success
- 1: file not found
- 2: no Excel data found in file
- 3: file is encrypted (and decryption failed)

## See Also

- [Spreadsheet::XLSX](http://search.cpan.org/~dmow/Spreadsheet-XLSX/) — for Excel 2007 XLSX files
- [Spreadsheet::Read](http://search.cpan.org/~hmbrand/Spreadsheet-Read/) — unified interface for multiple spreadsheet formats
- [Spreadsheet::WriteExcel](http://search.cpan.org/~jmcnamara/Spreadsheet-WriteExcel/) — create Excel files
- [Spreadsheet::ParseExcel::SaveParser](http://search.cpan.org/~jmcnamara/Spreadsheet-ParseExcel/) — modify and rewrite Excel files
- [Text::CSV_XS](http://search.cpan.org/~hmbrand/Text-CSV_XS/) — fast CSV parsing
- `xls2csv` (Ken Prows), `xlscat` (H.Merijn Brand), `excel2txt` (Ken Youens-Clark), `XLSperl` (Jon Allen) — utility scripts

## Known Problems

- Cannot read formula values from files created by Spreadsheet::WriteExcel (unless values were stored).
- For date fields with system-default short-date locale, formatting may default to 'yyyy-mm-dd'.