--- name: "Catmandu::PerlAPI" section: "3pm" platform: "linux" package: "libcatmandu-perl" version: "1.2024-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Catmandu::PerlAPI" --- # Catmandu::PerlAPI(3pm) A short overview of the current Catmandu Perl API ## NAME Catmandu::PerlAPI - A short overview of the current Catmandu Perl API ## 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; ``` ## DESCRIPTION This document provides a short overview of the Perl API of the 1.X version of Catmandu. The Perl API is provided as-is and might change in the future. For a stable implementation of Catmandu we refer to the command line interface of our tool. ## USE To include Catmandu in a Perl script it should be loaded with a `"use"` command: ``` use Catmandu; ``` By default no methods are imported into the Perl context. To import all or some Catmandu methods, provide them as a list to the `"use"` command: ``` use Catmandu -all; use Catmandu qw(config store exporter); ``` Catmandu can load configuration options for exports, importers, fixers via configuration files (see the CONFIG section below). When adding the --load option (optionally with a path) to the `"use"` command, these configuration files will be loaded 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)]; ``` ## CLASS METHODS ### log Return 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 ``` ### default\_load\_path(\['/default/path'\]) Returns the default location where Catmandu looks for configuration and lib when called with no argument. Sets the default location if a path is given. The default load path is the script directory or it's parent if the script directory is `"bin"`. ### load Load all the configuration options in the catmandu.yml configuration file. See CONFIG below for extended examples of configuration options. ### load('/path', '/another/path') Load all the configuration options stored at alternative paths. A load path `':up'` will search upwards from your program for configuration. See CONFIG below for extended examples of configuration options. ### roots Returns an ARRAYREF of paths where configuration was found. Note that this list is empty before `"load"`. ### root Returns the first path where configuration was found. Note that this is `"undef"` before `"load"`. ### config Returns the current configuration as a HASHREF. ### config($config) Set a new configuration and reload the environment. ### default\_store Return the name of the default store. ### store(\[NAME\]) Return an instance of Catmandu::Store. The NAME is a 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 will be 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'); ``` ### default\_fixer Return the name of the default fixer. ### fixer(NAME) ### fixer(FIX,FIX) ### fixer(\[FIX\]) Return 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 al 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 be also 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'); ``` ### default\_importer Return the name of the default importer. ### default\_importer\_package Return the name of the default importer package if no package name is given in the config or as a param. ### importer(NAME) Return an instance of Catmandu::Importer. The NAME is a name of a Catmandu::Importer or the name of a importer configured in a catmandu.yml configuration file. When no NAME is given, the 'default' importer in the configuration file will be 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 Return the name of the default exporter. ### default\_exporter\_package Return the name of the default exporter package if no package name is given in the config or as a param. ### exporter(\[NAME\]) Return an instance of Catmandu::Exporter with name NAME (or the default when no name is given). The NAME can be in a configuration file (see 'importer'). ### validator(\[NAME\]) Return an instance of Catmandu::Validator with name NAME (or the default when no name is given). The NAME can be in a configuration file (see 'importer'). ### export($data,\[NAME\]) Export data using a default or named exporter or 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); ``` ### export\_to\_string Export data using a default or named exporter to 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. 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); ``` ## EXPORTS - config Same 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 Import everything. - \-load/:load ``` 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'); ```