.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Catmandu::PerlAPI 3pm"
.TH Catmandu::PerlAPI 3pm "2023-03-03" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catmandu::PerlAPI \- A short overview of the current Catmandu Perl API
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Catmandu;
\&
\&    # If you have Catmandu::OAI and Catmandu::MongoDB installed
\&    my $importer = Catmandu\->importer(\*(AqOAI\*(Aq,url => \*(Aqhttps://biblio.ugent.be/oai\*(Aq)
\&    my $store    = Catmandu\->store(\*(AqMongoDB\*(Aq,database_name => \*(Aqtest\*(Aq);
\&
\&    # 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,\*(Aq; \*(Aq)
\&    #   join_field(subject,\*(Aq\-\- \*(Aq)
\&    my $fixer    = Catmandu\->fixer(\*(Aqmyfixes.txt\*(Aq);
\&    my $exporter = Catmandu\->exporter(\*(AqYAML\*(Aq);
\&
\&    $exporter\->add_many( $fixer\->fix($store) );
\&    $exporter\->commit;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This document provides a short overview of the Perl \s-1API\s0 of the 1.X version of
Catmandu. The Perl \s-1API\s0 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.
.SH "USE"
.IX Header "USE"
To include Catmandu in a Perl script it should be loaded with a \f(CW\*(C`use\*(C'\fR command:
.PP
.Vb 1
\&    use Catmandu;
.Ve
.PP
By default no methods are imported into the Perl context. To import all or some Catmandu methods,
provide them as a list to the \f(CW\*(C`use\*(C'\fR command:
.PP
.Vb 2
\&    use Catmandu \-all;
\&    use Catmandu qw(config store exporter);
.Ve
.PP
Catmandu can load configuration options for exports, importers, fixers via configuration
files (see the \s-1CONFIG\s0 section below). When adding the \-\-load option (optionally with a path) to the
\&\f(CW\*(C`use\*(C'\fR command, these configuration files will be loaded at the start of your script.
.PP
.Vb 2
\&    use Catmandu \-load;
\&    use Catmandu \-load => [\*(Aq/my/config/directory\*(Aq];
\&
\&    # or use all the options
\&    use Catmandu \-all, \-load => [qw(/config/path\*(Aq \*(Aq/another/config/path)];
.Ve
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.SS "log"
.IX Subsection "log"
Return the current Log::Any logger.
.PP
.Vb 3
\&    use Catmandu;
\&    use Log::Any::Adapter;
\&    use Log::Log4perl;
\&
\&    Log::Any::Adapter\->set(\*(AqLog4perl\*(Aq); # requires Log::Any::Adapter::Log4perl
\&    Log::Log4perl::init(\*(Aq./log4perl.conf\*(Aq);
\&
\&    my $logger = Catmandu\->log;
\&    $logger\->info("Starting main program");
.Ve
.PP
with log4perl.conf like:
.PP
.Vb 2
\&    # 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
.Ve
.SS "default_load_path(['/default/path'])"
.IX Subsection "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 \f(CW\*(C`bin\*(C'\fR.
.SS "load"
.IX Subsection "load"
Load all the configuration options in the catmandu.yml configuration file.
See \s-1CONFIG\s0 below for extended examples of configuration options.
.SS "load('/path', '/another/path')"
.IX Subsection "load('/path', '/another/path')"
Load all the configuration options stored at alternative paths.
.PP
A load path \f(CW\*(Aq:up\*(Aq\fR will search upwards from your program for configuration.
.PP
See \s-1CONFIG\s0 below for extended examples of configuration options.
.SS "roots"
.IX Subsection "roots"
Returns an \s-1ARRAYREF\s0 of paths where configuration was found. Note that this list
is empty before \f(CW\*(C`load\*(C'\fR.
.SS "root"
.IX Subsection "root"
Returns the first path where configuration was found. Note that this is
\&\f(CW\*(C`undef\*(C'\fR before \f(CW\*(C`load\*(C'\fR.
.SS "config"
.IX Subsection "config"
Returns the current configuration as a \s-1HASHREF.\s0
.SS "config($config)"
.IX Subsection "config($config)"
Set a new configuration and reload the environment.
.SS "default_store"
.IX Subsection "default_store"
Return the name of the default store.
.SS "store([\s-1NAME\s0])"
.IX Subsection "store([NAME])"
Return an instance of Catmandu::Store. The \s-1NAME\s0 is a name of a Catmandu::Store or the
name of a store configured in a catmandu.yml configuration file. When no \s-1NAME\s0 is given, the
\&'default' store in the configuration file will be used.
.PP
E.g. if the configuration file 'catmandu.yml' contains:
.PP
.Vb 7
\& store:
\&  default:
\&   package: ElasticSearch
\&   options:
\&     index_name: blog
\&  test:
\&   package: Mock
.Ve
.PP
then in your program:
.PP
.Vb 2
\&    # This will use ElasticSearch
\&    my $store = Catmandu\->store(\*(AqElasticSearch\*(Aq, index_name => \*(Aqblog\*(Aq);
\&
\&    # or because we have a \*(Aqdefault\*(Aq set in the configuration file
\&
\&    my $store = Catmandu\->store(\*(Aqdefault\*(Aq);
\&
\&    # or because \*(Aqdefault\*(Aq will be used when no name was provided
\&
\&    my $store = Catmandu\->store;
\&
\&    # This will use Mock
\&    my $store = Catmandu\->store(\*(Aqtest\*(Aq);
.Ve
.PP
Configuration settings can be overwritten by the store command:
.PP
.Vb 1
\&  my $store2 = Catmandu\->store(\*(Aqdefault\*(Aq, index_name => \*(Aqtest2\*(Aq);
.Ve
.SS "default_fixer"
.IX Subsection "default_fixer"
Return the name of the default fixer.
.SS "fixer(\s-1NAME\s0)"
.IX Subsection "fixer(NAME)"
.SS "fixer(\s-1FIX,FIX\s0)"
.IX Subsection "fixer(FIX,FIX)"
.SS "fixer([\s-1FIX\s0])"
.IX Subsection "fixer([FIX])"
Return an instance of Catmandu::Fix. \s-1NAME\s0 can be the name of a fixer section
in a catmandu.yml file. Or, one or more Catmandu::Fix\-es can be provided inline.
.PP
E.g. if the configuration file 'catmandu.yml' contains:
.PP
.Vb 4
\& fixer:
\&  default:
\&    \- do_this()
\&    \- do_that()
.Ve
.PP
then in your program al these lines below will create the same fixer:
.PP
.Vb 4
\&    my $fixer = Catmandu\->fixer(\*(Aqdo_this()\*(Aq, \*(Aqdo_that()\*(Aq);
\&    my $fixer = Catmandu\->fixer([\*(Aqdo_this()\*(Aq, \*(Aqdo_that()\*(Aq]);
\&    my $fixer = Catmandu\->fixer(\*(Aqdefault\*(Aq);
\&    my $fixer = Catmandu\->fixer(); # The default name is \*(Aqdefault\*(Aq
.Ve
.PP
FIX-es can be also written to a Fix script. E.g. if myfixes.txt contains:
.PP
.Vb 2
\& do_this()
\& do_that()
.Ve
.PP
then the above code will even be equivalent to:
.PP
.Vb 1
\&   my $fixer = Catmandu\->fixer(\*(Aqmyfixes.txt\*(Aq);
.Ve
.SS "default_importer"
.IX Subsection "default_importer"
Return the name of the default importer.
.SS "default_importer_package"
.IX Subsection "default_importer_package"
Return the name of the default importer package if no
package name is given in the config or as a param.
.SS "importer(\s-1NAME\s0)"
.IX Subsection "importer(NAME)"
Return an instance of Catmandu::Importer. The \s-1NAME\s0 is a name of a Catmandu::Importer or the
name of a importer configured in a catmandu.yml configuration file. When no \s-1NAME\s0 is given, the
\&'default' importer in the configuration file will be used.
.PP
E.g. if the configuration file 'catmandu.yml' contains:
.PP
.Vb 5
\&  importer:
\&    default:
\&      package: OAI
\&      options:
\&        url: http://www.instute.org/oai/
.Ve
.PP
then in your program all these lines will be equivalent:
.PP
.Vb 3
\&  my $importer = Catmandu\->importer(\*(AqOAI\*(Aq, url => \*(Aqhttp://www.instute.org/oai/\*(Aq);
\&  my $importer = Catmandu\->importer(\*(Aqdefault\*(Aq);
\&  my $importer = Catmandu\->importer(); # The default name is \*(Aqdefault\*(Aq
.Ve
.PP
Configuration settings can be overwritten by the importer command:
.PP
.Vb 1
\&  my $importer2 = Catmandu\->importer(\*(Aqdefault\*(Aq, url => \*(Aqhttp://other.institute.org\*(Aq);
.Ve
.SS "default_exporter"
.IX Subsection "default_exporter"
Return the name of the default exporter.
.SS "default_exporter_package"
.IX Subsection "default_exporter_package"
Return the name of the default exporter package if no
package name is given in the config or as a param.
.SS "exporter([\s-1NAME\s0])"
.IX Subsection "exporter([NAME])"
Return an instance of Catmandu::Exporter with name \s-1NAME\s0 (or the default when
no name is given).  The \s-1NAME\s0 can be in a configuration file (see 'importer').
.SS "validator([\s-1NAME\s0])"
.IX Subsection "validator([NAME])"
Return an instance of Catmandu::Validator with name \s-1NAME\s0 (or the default when
no name is given).  The \s-1NAME\s0 can be in a configuration file (see 'importer').
.SS "export($data,[\s-1NAME\s0])"
.IX Subsection "export($data,[NAME])"
Export data using a default or named exporter or exporter instance.
.PP
.Vb 1
\&    Catmandu\->export({ foo=>\*(Aqbar\*(Aq});
\&
\&    my $importer = Catmandu::Importer::Mock\->new;
\&    Catmandu\->export($importer, \*(AqYAML\*(Aq, file => \*(Aq/my/file\*(Aq);
\&    Catmandu\->export($importer, \*(Aqmy_exporter\*(Aq);
\&    Catmandu\->export($importer, \*(Aqmy_exporter\*(Aq, exporter_option => \*(Aq...\*(Aq , ...);
\&    Catmantu\->export($importer, Catmandu::Exporter::YAML\->new);
.Ve
.SS "export_to_string"
.IX Subsection "export_to_string"
Export data using a default or named exporter to a string.
.PP
.Vb 5
\&    my $importer = Catmandu::Importer::Mock\->new;
\&    my $yaml = Catmandu\->export_to_string($importer, \*(AqYAML\*(Aq);
\&    # is the same as
\&    my $yaml = "";
\&    Catmandu\->export($importer, \*(AqYAML\*(Aq, file => \e$yaml);
.Ve
.SS "import_from_string"
.IX Subsection "import_from_string"
Import data from a string using a default or named importer.
Return value should be an array of hashes.
.PP
.Vb 8
\&    my $json = qq([{"name":"Nicolas"}]);
\&    {
\&        my $record = Catmandu\->import_from_string( $json, "JSON" );
\&    }
\&    # is the same as
\&    {
\&        my $record = Catmandu\->importer(\*(AqJSON\*(Aq, file => \e$json)\->to_array()
\&    }
.Ve
.SS "define_importer"
.IX Subsection "define_importer"
Configure a new named importer.
.PP
.Vb 5
\&    Catmandu\->define_importer(books => CSV => (fields => \*(Aqtitle,author,publisher\*(Aq));
\&    Catmandu\->importer(books => (file => \*(Aqmybooks.csv\*(Aq))\->each(sub {
\&        my $book = shift;
\&        say $book\->{title};
\&    });
\&
\&    # this is equivalent to
\&
\&    Catmandu\->config\->{importer}{books} = {
\&        package => \*(AqCSV\*(Aq,
\&        options => {
\&            fields => \*(Aqtitle,author,publisher\*(Aq,
\&        },
\&    }
.Ve
.SS "define_exporter"
.IX Subsection "define_exporter"
Configure a new named exporter.
.PP
.Vb 2
\&    Catmandu\->define_exporter(\*(Aqbooks\*(Aq, \*(AqCSV\*(Aq, fix => \*(Aqcapitalize(title)\*(Aq);
\&    my $csv = Catmandu\->export_to_string({title => \*(Aqnexus\*(Aq}, \*(Aqbooks\*(Aq);
\&
\&    # this is equivalent to
\&
\&    Catmandu\->config\->{exporter}{books} = {
\&        package => \*(AqCSV\*(Aq,
\&        options => {
\&            fix => \*(Aqcapitalize(title)\*(Aq,
\&        },
\&    }
.Ve
.SS "define_store"
.IX Subsection "define_store"
Configure a new named store.
.PP
.Vb 2
\&    Catmandu\->define_store(mydb => MongoDB => (database_name => \*(Aqmydb\*(Aq));
\&    Catmandu\->store\->bag(\*(Aqbooks\*(Aq)\->get(1234);
\&
\&    # this is equivalent to
\&
\&    Catmandu\->config\->{store}{mydb} = {
\&        package => \*(AqMongoDB\*(Aq,
\&        options => {
\&            database_name => \*(Aqmydb\*(Aq,
\&        },
\&    }
.Ve
.SS "define_fixer"
.IX Subsection "define_fixer"
Configure a new named fixer.
.PP
.Vb 7
\&    Catmandu\->define_fixer(\*(Aqcleanup\*(Aq, [
\&        \*(Aqtrim(title)\*(Aq,
\&        \*(Aqcapitalize(title)\*(Aq,
\&        \*(Aqremove_field(junk)\*(Aq,
\&        # ...
\&    ]);
\&    Catmandu\->fixer(\*(Aqcleanup\*(Aq)\->fix($record);
.Ve
.SH "EXPORTS"
.IX Header "EXPORTS"
.IP "config" 4
.IX Item "config"
Same as \f(CW\*(C`Catmandu\->config\*(C'\fR.
.IP "store" 4
.IX Item "store"
Same as \f(CW\*(C`Catmandu\->store\*(C'\fR.
.IP "importer" 4
.IX Item "importer"
Same as \f(CW\*(C`Catmandu\->importer\*(C'\fR.
.IP "exporter" 4
.IX Item "exporter"
Same as \f(CW\*(C`Catmandu\->exporter\*(C'\fR.
.IP "validator" 4
.IX Item "validator"
Same as \f(CW\*(C`Catmandu\->validator\*(C'\fR.
.IP "export" 4
.IX Item "export"
Same as \f(CW\*(C`Catmandu\->export\*(C'\fR.
.IP "export_to_string" 4
.IX Item "export_to_string"
Same as \f(CW\*(C`Catmandu\->export_to_string\*(C'\fR.
.IP "import_from_string" 4
.IX Item "import_from_string"
Same as \f(CW\*(C`Catmandu\->import_from_string\*(C'\fR.
.IP "fixer" 4
.IX Item "fixer"
Same as \f(CW\*(C`Catmandu\->fixer\*(C'\fR.
.IP "log" 4
.IX Item "log"
Same as \f(CW\*(C`Catmandu\->log\*(C'\fR.
.IP "\-all/:all" 4
.IX Item "-all/:all"
Import everything.
.IP "\-load/:load" 4
.IX Item "-load/:load"
.Vb 4
\&    use Catmandu \-load;
\&    use Catmandu \-load => [];
\&    # is the same as
\&    Catmandu\->load;
\&
\&    use Catmandu \-load => [\*(Aq/config/path\*(Aq];
\&    # is the same as
\&    Catmandu\->load(\*(Aq/config/path\*(Aq);
.Ve