Catman...er::XLS(3pm)

💖 Catmandu::Importer::XLS — the manual, but make it make sense 💖

okay bestie, gather round, because this one is so useful and also the page name got absolutely mangled by whatever gremlin formatted it (it's Catmandu::Importer::XLS, section 3pm, from the User Contributed Perl Documentation crew 🫶). Yes. It's a whole Perl module. Yes it slays. Let's go. ✨

---

🌸 NAME 🌸

Catmandu::Importer::XLS — the package that imports XLS files. that's it. that's the whole job. iconic behavior honestly 💅

---

🦋 SYNOPSIS 🦋

you can run it from the command line, like the main character you are:

# On the command line
$ catmandu convert XLS < ./t/test.xls
$ catmandu convert XLS --header 0 < ./t/test.xls
$ catmandu convert XLS --fields 1,2,3 < ./t/test.xls
$ catmandu convert XLS --columns 1 < ./t/test.xls
$ catmandu convert XLS --worksheet 1 < ./t/test.xls

or, if you're a Perl girlie (respect 🙌), you do it in Perl:

# Or in Perl
use Catmandu::Importer::XLS;

my $importer = Catmandu::Importer::XLS->new(file => "./t/test.xls");

my $n = $importer->each(sub {
    my $hashref = $_[0];
    # ...
});

like. look at that. each gives you a $hashref per row and you do whatever your heart desires with it. no cap. 💖

---

🎀 DESCRIPTION 🎀

It's a Catmandu importer for XLS files. that's the vibe. that's the whole vibe check. ✅

---

✨ METHODS ✨

This module inherits all the methods of Catmandu::Importer, and through that, all of Catmandu::Iterable. So everything those two can do, this one can do too — nothing extra to memorize, just the family inheritance working its magic. 🧚

---

💜 CONFIGURATION 💜

So obviously you get everything Catmandu::Importer already gives you (file, fh, etc. — the usual suspects), and on top of that this importer takes these extra parameters. Obsessed with the options honestly:

• header — by default, the object fields get read straight from the XLS header line. If there is no header line available, the object fields get named after column coordinates instead (A,B,C,...). Default: 1.
• fields — give it custom object field names. You can hand them over as an array, a hash reference, or a comma-separated list. your call, bestie, whatever format your heart says 💫
• columns — when you pass the columns option, the object fields get named as column coordinates (A,B,C,...). Default: 0.
• empty — this is the "how do we treat empty fields in the data" setting, and she has layers:
  • when the option value is 'string', the empty values become empty strings.
  • when the option value is 'nil', the empty values get turned into undefined fields.
  • when the option is 'ignore', the empty values are ignored.
  • Default is 'string'.
• worksheet — if your Excel workbook contains more than one worksheet, you can select a specific one by its index number (0,1,2,...). Default: 0.

ngl the empty option is doing the most and I respect her for it. pick your fighter: 'string', 'nil', or 'ignore'. 🍓

---

🌈 SEE ALSO 🌈

go read these too, they're the friend group:

• Catmandu::Importer
• Catmandu::Iterable
• Catmandu::Importer::CSV
• Catmandu::Importer::XLSX

---

and that's the whole page bestie!! 🥳 this was written for perl v5.40.1, dated 2026-01-24, and it's page Catmandu::Importer::XLS(3pm) of the User Contributed Perl Documentation. mwah. go import some spreadsheets. 💖✨🦋👑