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

✨ NAME ✨

okay so bestie, meet Catmandu::Importer::CSV — the little package that imports CSV data 💖 this is the Catmandu::Importer::CSV(3pm) manual page and she is literally here to feed you spreadsheets.

---

🎀 SYNOPSIS 🎀

from the command line, babes:

# From the command line

# convert a CSV file to JSON
catmandu convert CSV to JSON < journals.csv

# set column names if CSV file has no header line
echo '12157,"The Journal of Headache and Pain",2193-1801' | \
  catmandu convert CSV --header 0 --fields 'id,title,issn' to YAML

# set field separator and quote character
echo '12157;$The Journal of Headache and Pain$;2193-1801' | \
  catmandu convert CSV --header 0 --fields 'id,title,issn' --sep_char ';' --quote_char '$' to XLSX --file journal.xlsx

# In a Perl script

use Catmandu;

my $importer = Catmandu->importer('CSV', file => "/foo/bar.csv");

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

---

🌸 DESCRIPTION 🌸

so this package imports comma-separated values (CSV) — no cap, that's her whole job 🫶

the object fields get read from the CSV header line, or you can hand them over yourself with the fields parameter.

strings inside the CSV are quoted by quote_char, and the fields are separated by sep_char. that's the vibe 💅

---

🦋 CONFIGURATION 🦋

okay this is the part where she tells you all her lil settings, and there are a LOT, so buckle up 🎀

• file — read input from a local file by giving its path. alternatively, you can pass a scalar reference and she'll read from that string instead ✨
• fh — read input from an IO::Handle. if you don't specify one, Catmandu::Util::io gets called to build the input stream from the file argument, or else it just uses STDIN 💖
• encoding — the binmode of the input stream fh. defaults to :utf8 🌸
• fix — an ARRAY of one or more fixes, or file scripts, that get applied to the imported items. lil glow-up for your data 💅
• fields — the list of fields to use as columns. you can give it as an array reference, a comma-separated string, or a hash reference. important: if header is 0 and fields is undef, the fields get named by column index — 0, 1, 2, ... and so on 👑
• header — read the fields from a header line with the column names. set it to 1 to do that, and 1 is the default, so she's doing it unless you say otherwise 🌈
• sep_char — the column separator. default is , ✨
• quote_char — the quotation character. default is " 🎀
• escape_char — the character used for escaping inside a quoted field. default is " 💜
• allow_loose_quotes
• allow_loose_escapes — allow the common bad-practice stuff in CSV escaping. yes bestie, we're being lenient 🙈

---

👑 METHODS 👑

every Catmandu::Importer is a Catmandu::Iterable, so literally all of its methods are inherited. she's got main character energy by association 💅

heads up though: these methods are NOT idempotent. a CSV stream can only be read once — one shot, that's it, no reruns 😭

---

💀 SEE ALSO 💀

go check out her friends, they're iconic:

• Catmandu::Exporter::CSV
• Catmandu::Importer::XLS

---

that's the whole page, bestie 🫶 this was perl v5.40.1, dated 2026-01-24, and it lives in Catmandu::Importer::CSV(3pm) in the User Contributed Perl Documentation — mwah, slay, periodt 💖✨🎀