Catman...PerlAPI(3pm)

📦

version 1.2025 · 3 versions

1.2025 · ubuntu resolute, ubuntu stonking (latest)
1.2020 · debian bookworm, ubuntu noble
1.2024 · debian trixie, ubuntu questing

Catmandu::PerlAPI 💖

okay bestie, this is the Catman...PerlAPI(3pm) page from the User Contributed Perl Documentation, and it's lowkey a whole tour of the Catmandu Perl API. grab a snack, we're doing this. ✨

🌸 NAME 🌸

Catmandu::PerlAPI — a short overview of the current Catmandu Perl API. periodt.

🦋 SYNOPSIS 🦋

    use Catmandu;

    # If you have Catmandu::OAI and Catmandu::MongoDB installed
    my $importer = Catmandu->importer('OAI',url => 'https://biblio.ugent.be/oai')
    my $store    = Catmandu->store('MongoDB',database_name => 'test');

    # Import all the OAI records into MongoDB
    $store->add_many($importer);

    # Export all the MongoDB records to YAML and apply some fixes
    # myfixes.txt:
    #   upcase(title.*)
    #   remove_field(_metadata)
    #   join_field(creator,'; ')
    #   join_field(subject,'-- ')
    my $fixer    = Catmandu->fixer('myfixes.txt');
    my $exporter = Catmandu->exporter('YAML');

    $exporter->add_many( $fixer->fix($store) );
    $exporter->commit;

look at that. import, store, fix, export. it's giving pipeline. 💅

🎀 DESCRIPTION 🎀

so this doc is a short overview of the Perl API of the 1.X version of Catmandu.

⚠️ real talk: the Perl API is provided as-is and might change in the future. if you want the stable, no-surprises experience, the docs point you to the command line interface of the tool. so like, for production vibes? CLI. for experimenting? go off. 💖

✨ USE ✨

to pull Catmandu into a Perl script, you load it with a use command:

    use Catmandu;

by default, no methods are imported into the Perl context. nothing. zero. nada. if you want all of them, or just some, you pass them as a list to the use command:

    use Catmandu -all;
    use Catmandu qw(config store exporter);

Catmandu can also load configuration options for exports, importers, fixers via configuration files (peep the CONFIG section below 👀). if you add the --load option (optionally with a path) to the use command, those config files get loaded right at the start of your script:

    use Catmandu -load;
    use Catmandu -load => ['/my/config/directory'];

    # or use all the options
    use Catmandu -all, -load => [qw(/config/path' '/another/config/path)];

🫶 yes that qw(...) in the last one really does look like that in the source. we don't touch it. we respect it.

👑 CLASS METHODS 👑

💜 log

returns the current Log::Any logger.

    use Catmandu;
    use Log::Any::Adapter;
    use Log::Log4perl;

    Log::Any::Adapter->set('Log4perl'); # requires Log::Any::Adapter::Log4perl
    Log::Log4perl::init('./log4perl.conf');

    my $logger = Catmandu->log;
    $logger->info("Starting main program");

with log4perl.conf like:

    # Send a copy of all logging messages to STDERR
    log4perl.rootLogger=DEBUG,STDERR

    # Logging specific for your main program
    log4perl.category.myprog=INFO,STDERR

    # Logging specific for on part of Catmandu
    log4perl.category.Catmandu::Fix=DEBUG,STDERR

    # Where to send the STDERR output
    log4perl.appender.STDERR=Log::Log4perl::Appender::Screen
    log4perl.appender.STDERR.stderr=1
    log4perl.appender.STDERR.utf8=1

    log4perl.appender.STDERR.layout=PatternLayout
    log4perl.appender.STDERR.layout.ConversionPattern=%d [%P] - %p %l time=%r : %m%n

loggers but make it aesthetic 🌈

💜 default_load_path(['/default/path'])

when you call it with no argument, it returns the default location where Catmandu goes looking for configuration and lib. if you hand it a path, it sets the default location to that.

the default load path is the script directory, or its parent if the script directory is bin.

💜 load

loads all the configuration options in the catmandu.yml configuration file. the CONFIG section below has extended examples of configuration options. 💖

💜 load('/path', '/another/path')

loads all the configuration options stored at alternative paths.

a load path of :up will search upwards from your program for configuration. cute.

see CONFIG below for extended examples of configuration options.

💜 roots

returns an ARRAYREF of paths where configuration was found.

📌 heads up: this list is empty before load.

💜 root

returns the first</s> path where configuration was found.

📌 heads up again: this is undef before load.

💜 config

returns the current configuration as a HASHREF.

💜 config($config)

sets a new configuration and reloads the environment. slay. ✨

💜 default_store

returns the name of the default store.

💜 store([NAME])

returns an instance of Catmandu::Store. NAME is the name of a Catmandu::Store, or the name of a store configured in a catmandu.yml configuration file. when no NAME is given, the 'default' store in the configuration file gets used.

e.g. if the configuration file catmandu.yml contains:

     store:
      default:
       package: ElasticSearch
       options:
         index_name: blog
      test:
       package: Mock

then in your program:

    # This will use ElasticSearch
    my $store = Catmandu->store('ElasticSearch', index_name => 'blog');

    # or because we have a 'default' set in the configuration file

    my $store = Catmandu->store('default');

    # or because 'default' will be used when no name was provided

    my $store = Catmandu->store;

    # This will use Mock
    my $store = Catmandu->store('test');

configuration settings can be overwritten by the store command:

  my $store2 = Catmandu->store('default', index_name => 'test2');

overriding? iconic behavior honestly. 💅

💜 default_fixer

returns the name of the default fixer.

💜 fixer(NAME) / fixer(FIX,FIX) / fixer([FIX])

returns an instance of Catmandu::Fix. NAME can be the name of a fixer section in a catmandu.yml file. or, one or more Catmandu::Fix-es can be provided inline.

e.g. if the configuration file catmandu.yml contains:

     fixer:
      default:
        - do_this()
        - do_that()

then in your program all these lines below will create the same fixer:

    my $fixer = Catmandu->fixer('do_this()', 'do_that()');
    my $fixer = Catmandu->fixer(['do_this()', 'do_that()']);
    my $fixer = Catmandu->fixer('default');
    my $fixer = Catmandu->fixer(); # The default name is 'default'

FIX-es can also be written to a Fix script. e.g. if myfixes.txt contains:

 do_this()
 do_that()

then the above code will even be equivalent to:

   my $fixer = Catmandu->fixer('myfixes.txt');

four ways to say the same thing. we love a flexible queen. 🎀

💜 default_importer

returns the name of the default importer.

💜 default_importer_package

returns the name of the default importer package, if no package name is given in the config or as a param.

💜 importer(NAME)

returns an instance of Catmandu::Importer. NAME is the name of a Catmandu::Importer, or the name of an importer configured in a catmandu.yml configuration file. when no NAME is given, the 'default' importer in the configuration file gets used.

e.g. if the configuration file catmandu.yml contains:

   importer:
     default:
       package: OAI
       options:
         url: http://www.instute.org/oai/

then in your program all these lines will be equivalent:

   my $importer = Catmandu->importer('OAI', url => 'http://www.instute.org/oai/');
   my $importer = Catmandu->importer('default');
   my $importer = Catmandu->importer(); # The default name is 'default'

configuration settings can be overwritten by the importer command:

   my $importer2 = Catmandu->importer('default', url => 'http://other.institute.org');

💜 default_exporter

returns the name of the default exporter.

💜 default_exporter_package

returns the name of the default exporter package, if no package name is given in the config or as a param.

💜 exporter([NAME])

returns an instance of Catmandu::Exporter with name NAME (or the default when no name is given). NAME can be in a configuration file — see 'importer' above. 💖

💜 validator([NAME])

returns an instance of Catmandu::Validator with name NAME (or the default when no name is given). NAME can be in a configuration file — see 'importer' above.

💜 export($data,[NAME])

export data using a default or named exporter, or an exporter instance.

    Catmandu->export({ foo=>'bar'});

    my $importer = Catmandu::Importer::Mock->new;
    Catmandu->export($importer, 'YAML', file => '/my/file');
    Catmandu->export($importer, 'my_exporter');
    Catmandu->export($importer, 'my_exporter', exporter_option => '...' , ...);
    Catmantu->export($importer, Catmandu::Exporter::YAML->new);

🙈 yes, that last line says Catmantu in the original. we do not fix it. we preserve it. it's part of the lore now.

💜 export_to_string

export data using a default or named exporter, straight into a string.

    my $importer = Catmandu::Importer::Mock->new;
    my $yaml = Catmandu->export_to_string($importer, 'YAML');
    # is the same as
    my $yaml = "";
    Catmandu->export($importer, 'YAML', file => \$yaml);

💜 import_from_string

import data from a string using a default or named importer. the return value should be an array of hashes.

    my $json = qq([{"name":"Nicolas"}]);
    {
        my $record = Catmandu->import_from_string( $json, "JSON" );
    }
    # is the same as
    {
        my $record = Catmandu->importer('JSON', file => \$json)->to_array()
    }

💜 define_importer

configure a new named importer.

    Catmandu->define_importer(books => CSV => (fields => 'title,author,publisher'));
    Catmandu->importer(books => (file => 'mybooks.csv'))->each(sub {
        my $book = shift;
        say $book->{title};
    });

    # this is equivalent to

    Catmandu->config->{importer}{books} = {
        package => 'CSV',
        options => {
            fields => 'title,author,publisher',
        },
    }

💜 define_exporter

configure a new named exporter.

    Catmandu->define_exporter('books', 'CSV', fix => 'capitalize(title)');
    my $csv = Catmandu->export_to_string({title => 'nexus'}, 'books');

    # this is equivalent to

    Catmandu->config->{exporter}{books} = {
        package => 'CSV',
        options => {
            fix => 'capitalize(title)',
        },
    }

💜 define_store

configure a new named store.

    Catmandu->define_store(mydb => MongoDB => (database_name => 'mydb'));
    Catmandu->store->bag('books')->get(1234);

    # this is equivalent to

    Catmandu->config->{store}{mydb} = {
        package => 'MongoDB',
        options => {
            database_name => 'mydb',
        },
    }

💜 define_fixer

configure a new named fixer.

    Catmandu->define_fixer('cleanup', [
        'trim(title)',
        'capitalize(title)',
        'remove_field(junk)',
        # ...
    ]);
    Catmandu->fixer('cleanup')->fix($record);

okay that's the first half of the page bestie, we're not done yet — more is coming, don't go anywhere 💖✨🦋

✨ EXPORTS ✨

okay bestie so when you use Catmandu with an import list, these are the little functions it can hand you 💖 and every single one of them is just a shortcut — same energy, same behaviour, just less typing:

config — literally the same thing as Catmandu->config. 💅
store — same as Catmandu->store. 🎀
importer — same as Catmandu->importer. ✨
exporter — same as Catmandu->exporter. 🦋
validator — same as Catmandu->validator. 🌸
export — same as Catmandu->export. 🔥
export_to_string — same as Catmandu->export_to_string. 💜
import_from_string — same as Catmandu->import_from_string. 🌈
fixer — same as Catmandu->fixer. 🧚
log — same as Catmandu->log. ⭐
-all, :all — this one just imports everything. the whole menu, no cap 👑

🫶 the `-load` / `:load` moment

this one is a whole vibe, so let's look at it slow:

use Catmandu -load;
use Catmandu -load => [];
# is the same as
Catmandu->load;

use Catmandu -load => ['/config/path'];
# is the same as
Catmandu->load('/config/path');

so like — bare use Catmandu -load; and use Catmandu -load => []; both do the exact same thing as calling Catmandu->load; yourself. and if you pass an arrayref of paths, use Catmandu -load => ['/config/path']; is exactly Catmandu->load('/config/path');. same, same, no difference, fr fr 💖

and that's it bestie, that's the whole page! go forth and export things responsibly 💅✨

and that's a wrap on this icon of a manual page 🎀 it's from perl v5.40.1, dated 2026-01-24, and it lives in the Catman...PerlAPI(3pm) files — as documented by the Perl documentation crew, no cap 🌸🫶

📦 where this page comes from

ubuntu resolute: libcatmandu-perl 1.2025-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libcatmandu-perl 1.2025-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Catman...PerlAPI(3pm)

Catmandu::PerlAPI 💖

🌸 NAME 🌸

🦋 SYNOPSIS 🦋

🎀 DESCRIPTION 🎀

✨ USE ✨

👑 CLASS METHODS 👑

💜 log

💜 default_load_path(['/default/path'])

💜 load

💜 load('/path', '/another/path')

💜 roots

💜 root

💜 config

💜 config($config)

💜 default_store

💜 store([NAME])

💜 default_fixer

💜 fixer(NAME) / fixer(FIX,FIX) / fixer([FIX])

💜 default_importer

💜 default_importer_package

💜 importer(NAME)

💜 default_exporter

💜 default_exporter_package

💜 exporter([NAME])

💜 validator([NAME])

💜 export($data,[NAME])

💜 export_to_string

💜 import_from_string

💜 define_importer

💜 define_exporter

💜 define_store

💜 define_fixer

✨ EXPORTS ✨

🫶 the -load / :load moment

🫶 the `-load` / `:load` moment