Catman...porter(3pm)

💖 Catmandu::Exporter — the whole vibe 💖

okay bestie, welcome to Catmandu::Exporter, from the User Contributed Perl Documentation collection ✨ it's literally the namespace for packages that can export, and honestly? iconic. 💅

---

✨ NAME ✨

Catmandu::Exporter — the namespace for all the packages that can export stuff 🎀

---

🌸 SYNOPSIS 🌸

like, straight into it, no notes:

# From the command line

# JSON is an importer and YAML an exporter
$ catmandu convert JSON to YAML < data.json

# OAI is an importer and JSON an exporter
$ catmandu convert OAI --url http://biblio.ugent.be/oai to JSON

# From Perl
use Catmandu;

my $importer = Catmandu->importer('JSON', file => 'data.json');
my $exporter = Catmandu->exporter('YAML');

$exporter->add({ record => "one"});
$exporter->add_many([ { record => "one" } , { record => "two" } ]);
$exporter->add_many($importer);

$exporter->commit;

undef($exporter); # Clean up memory

see how JSON is the importer and YAML is the exporter in that first one? and then OAI is the importer and JSON is the exporter in the second? they literally swap roles, it's giving versatility 💫 and yes, undef($exporter) at the end is you being a responsible main character and cleaning up memory 🧹

---

🦋 DESCRIPTION 🦋

A Catmandu::Exporter is a Perl package that can export your data into JSON, YAML, XML or literally so many other formats. By default, the data goes to STDOUT — classic. But if you want, you can hand it a file or fh parameter to write to a file, a string, or a handle instead. your call, bestie 🫶

Every single Catmandu::Exporter is also a Catmandu::Fixable, which means it gives you a fix parameter <em>and</em> a method so you can apply fixes to the items as they get exported. watch:

my $exporter = Catmandu->exporter('JSON', fix => ['upcase(title)']);

# This will be printed to STDOUT like: {"title":"MY TITLE"}
$exporter->add({ title => "my title"});

that fix literally upcased the title on the way out, no cap 🔥

And every Catmandu::Exporter is a Catmandu::Addable too, so it inherits the methods add and add_many. free methods, we love an inheritance moment 👑

---

🎀 CONFIGURATION 🎀

the settings, the levers, the little knobs you get to turn:

• file — write the output to a local file, given by its path or a file handle. OR, plot twist: you can pass a <em>scalar reference</em> to write to a string instead, or a <em>code reference</em> to write to a callback function. three options, all slay ✨
• fh — write the output to an IO::Handle. if you don't specify it, Catmandu::Util::io gets used to create the output handle from the file argument, or by using STDOUT.

⚠️ important bestie: it is <strong>the task of the Perl programmer</strong> to close any opened IO::Handles. Catmandu will <strong>not</strong> do this by itself. it's giving "you built it, you close it" 💀

• encoding — the binmode of the output stream fh. set to ":utf8" by default. cute, sensible, done 🌸
• fix — an ARRAY of one or more fixes or file scripts that get applied to the exported items. stack 'em up 🥞

---

💜 METHODS 💜

add

Adds <strong>one</strong> item to be exported. one item, one moment, very focused 🎯

add_many

Adds <strong>many</strong> items to be exported. this can be either an ARRAY-ref or a Catmandu::Iterator. Returns a true value when the export was successful, or undef on error 😭

count

Returns the number of items exported by this Catmandu::Exporter. the receipts, literally 🧾

log

Returns the current logger. that's it, that's the method 📝

commit

Commit all buffers to the output handle. flush it, bestie, let it out 💅

---

🌈 CODING 🌈

okay so you wanna build your <em>own</em> exporter?? obsessed. do it by creating a Perl package in the Catmandu::Exporter namespace that implements Catmandu::Exporter. Basically, you need to create a method add which writes a Perl hash to a file handle:

package Catmandu::Exporter::Foo;

use Catmandu::Sane;
use Moo;

with 'Catmandu::Exporter'

sub add {
    my ($self, $data) = @_;
    my $fh = $self->fh;
    $fh->print( "Hello, World!");
}

sub commit {
    my ($self) = @_;
    # this will be called at the end of the record stream
}

1;

📌 heads up: with 'Catmandu::Exporter' is written exactly like that in the original — no trailing semicolon, don't @ me, just copy it fr fr 🙈

and that commit sub? it'll get called at the end of the record stream. the grand finale, if you will 🎬

This exporter can be called from the command line as:

$ catmandu convert JSON to Foo < data.json

Or, via Perl:

use Catmandu;

my $exporter = Catmandu->exporter('Foo', file => "/tmp/output.txt");

$exporter->add({test => 123});

$exporter->commit;

undef($exporter);

you literally just made a whole format. main character energy, periodt 👑

---

⭐ SEE ALSO ⭐

• See function export_to_string in module Catmandu. 👀
• The exporters Catmandu::Exporter::JSON, Catmandu::Exporter::YAML, Catmandu::Exporter::CSV, and Catmandu::Exporter::Text are all included in <strong>Catmandu core</strong>. built-in besties, no extra install 🎁
• See Catmandu::Importer for the opposite action. the <em>reverse</em> vibe, iykyk 🔄

---

and that's the whole page, bestie!! 💖 this one came from the User Contributed Perl Documentation, running on perl v5.40.1, dated 2026-01-24. go export something gorgeous 🦋✨