Catman...::Text(3pm)

💖 NAME 💖

okay so this whole page is filed under Catman...::Text(3pm) in your man pages, and what it's actually about is Catmandu::Importer::Text — a package that imports textual data. that's it, that's the whole job. it reads text. it gives you items. slay. ✨

---

🌸 SYNOPSIS 🌸

bestie here's the vibe, straight from the command line:

# From the command line

# separate fields by whitespace sequences just like awk
catmandu convert Text --split '\s+'

# import all lines starting with '#', omitting this character
catmandu convert Text --pattern '^#(.*)'

and if you're living that Perl script life instead:

# In a Perl script

use Catmandu;

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

# print all lines with line number
$importer->each(sub {
    my $item = $_[0];
    printf "%d: %s" , $item->{_id} , $item->{text};
});

not me printing line numbers with printf like it's nothing 💅

---

🦋 DESCRIPTION 🦋

so the way this works is: this package reads your textual input line by line. every single line becomes an item, and that item has two things going on:

• the line number lives in the field _id
• the text content lives in the field text

line separators are not included, so don't come looking for your newlines, they're gone, they said bye 🙈

and then — this is the part that eats — lines can further be split by a character or by a pattern, and you can hand it a regular expression to only import the lines you actually want, plus translate pattern groups into fields. iconic behaviour honestly. 👑

---

🎀 CONFIGURATION 🎀

💜 file

read input from a local file, given by its path. OR, plot twist, you can pass a scalar reference and it'll read from that string instead. cute right?

💜 fh

read input from an IO::Handle. if you don't specify one, Catmandu::Util::io gets called in to create the input stream — either from the file argument or, if there's nothing there, from STDIN.

💜 encoding

the binmode of the input stream fh. it's set to :utf8 by default, so like, you're already good. ✨

💜 fix

an ARRAY of one or more fixes or file scripts that get applied to the imported items. stack 'em up, bestie.

💜 split

a single character, or a regular expression given as a string with at least two characters, used to split each line. the resulting parts get imported into the field text as an array.

💜 pattern

a regular expression, given as a string, used to only import the lines that match. whitespaces inside patterns are ignored, or you have to escape them if your pattern is made of multiple lines (iykyk).

and here's the tea: if your pattern contains capturing groups, then the captured values get imported into the field match instead of into text. 🍓

so for instance, dates in YYYY-MM-DD format can be imported as named fields like this:

(?<year>\d\d\d\d)-(?<month>\d\d)-(?<day>\d\d)

or as an array like this:

(\d\d\d\d)-  # year
(\d\d)-      # month
(\d\d)       # day

literally so satisfying. 😭

---

⭐ METHODS ⭐

every Catmandu::Importer is a Catmandu::Iterable, and all of its methods are inherited. so like, go read that one too, bestie, it's giving main character energy. 👑

---

🌈 SEE ALSO 🌈

• Catmandu::Exporter::Text
• Catmandu::Fix::parse_text
• the Unix tools awk and sed — you can find them at <https://en.wikipedia.org/wiki/AWK> and <https://en.wikipedia.org/wiki/Sed>

fr fr if you already know awk and sed you're gonna feel so at home here. the --split '\s+' thing is literally the awk vibe. 🫶

---

and that's the page!! this one shipped with perl v5.40.1 and got dated 2026-01-24, so go forth and import some text, bestie — you're gonna ate it. mwah 💖💅🎀