NAME

Catmandu - a data toolkit

DESCRIPTION

Importing, transforming, storing and indexing data should be easy.

Catmandu provides a suite of Perl modules to ease the import, storage, retrieval, export and transformation of metadata records. Combine Catmandu modules with web application frameworks such as PSGI/Plack, document stores such as MongoDB and full text indexes such as Solr to create a rapid development environment for digital library services such as institutional repositories and search engines.

In the LibreCat project it is our goal to provide in open source a set of programming components to build up digital libraries services suited to your local needs.

Read an in depth introduction into Catmandu programming in Catmandu::Introduction.

VERSION

Version 0.1003

SYNOPSIS

    use Catmandu;

    Catmandu->load;
    Catmandu->load('/config/path', '/another/config/path');

    Catmandu->store->bag('projects')->count;

    Catmandu->config;
    Catmandu->config->{foo} = 'bar';

    use Catmandu -all;
    use Catmandu qw(config store);
    use Catmandu -load;
    use Catmandu -all -load => [qw(/config/path' '/another/config/path)];

CONFIG

Catmandu configuration options can be stored in a file in the root directory of your programming project. The file can be YAML, JSON or Perl and is called catmandu.yml, catmandu.json or catmandu.pl. In this file you can set the default Catmandu stores and exporters to be used. Here is an example of a catmandu.yml file:

    store:
      default:
        package: ElasticSearch
        options:
          index_name: myrepository

    exporter:
      default:
        package: YAML

Split config

For large configs it's more convenient to split the config into several files. You can do so by including the config hash key in the file name.

    catmandu.yaml
    catmandu.store.yaml
    catmandu.foo.bar.json

Config files are processed in alphabetical order. To keep things simple, values are not merged. The contents of catmandu.store.yml will overwrite Catmandu->config->{store} if it already exists.

EXPORTS

config

Same as Catmandu->config.

store

Same as Catmandu->store.

importer

Same as Catmandu->importer.

exporter

Same as Catmandu->exporter.

export

Same as Catmandu->export.

export_to_string

Same as Catmandu->export_to_string.

-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');

METHODS

log

Return the current logger (the Log::Any::Adapter for category Catmandu::Env).

default_load_path('/default/path')

Set the location of the default configuration file to a new path.

load

Load all the configuration options in the catmandu.yml configuration file.

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

Load all the configuration options stored at alternative paths.

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.

default_store

Return the name of the default store.

store([NAME])

Return an instance of a store with name NAME or use the default store when no name is provided. The NAME is set in the configuration file. E.g.

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

In your program:

    # This will use ElasticSearch
    Catmandu->store->bag->each(sub {  ... });
    Catmandu->store('default')->bag->each(sub {  ... });
    # This will use Mock
    Catmandu->store('test')->bag->search(...);

default_fixer

Return the name of the default fixer.

fixer(NAME)

Return an instance of Catmandu::Fix with name NAME (or 'default' when no name is given). The NAME is set in the config. E.g.

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

In your program:

    my $clean_data = Catmandu->fixer('cleanup')->fix($data);
    # or inline
    my $clean_data = Catmandu->fixer('do_this()', 'do_that()')->fix($data);
    my $clean_data = Catmandu->fixer(['do_this()', 'do_that()'])->fix($data);

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 a Catmandu::Importer with name NAME (or the default when no name is given). The NAME is set in the configuration file. E.g.

  importer:
    oai:
      package: OAI
      options:
        url: http://www.instute.org/oai/
    feed:
      package: Atom
      options:
        url: http://www.mysite.org/blog/atom

In your program:

    Catmandu->importer('oai')->each(sub { ... } );
    Catmandu->importer('oai', url => 'http://override')->each(sub { ... } );
    Catmandu->importer('feed')->each(sub { ... } );

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 is set in the configuration file (see 'importer').

export($data,[NAME])

Export data using a default or named exporter.

    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', foo => $bar);

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);

SEE ALSO

Catmandu::Introduction

AUTHOR

Nicolas Steenlant, <nicolas.steenlant at ugent.be>

CONTRIBUTORS

Patrick Hochstenbach, <patrick.hochstenbach at ugent.be>

Vitali Peil, vitali.peil at uni-bielefeld.de

Christian Pietsch, christian.pietsch at uni-bielefeld.de

Dave Sherohman, dave.sherohman at ub.lu.se

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

cpanm Catmandu

perl -MCPAN -e shell
install Catmandu