[libcatmandu-perl] 66/85: Reorganized the main Catmandu.pm documentation and added some up-to-date examples
Jonas Smedegaard
dr at jones.dk
Tue May 20 09:56:20 UTC 2014
This is an automated email from the git hooks/post-receive script.
js pushed a commit to tag 0.91
in repository libcatmandu-perl.
commit 56be27f2260d209c3b67486d2cb0a6317858fc8e
Author: Patrick Hochstenbach <patrick.hochstenbach at ugent.be>
Date: Sun May 18 10:22:50 2014 +0200
Reorganized the main Catmandu.pm documentation and added some up-to-date
examples
---
META.json | 2 +-
README.md | 6 +-
lib/Catmandu.pm | 274 +++++++++++++++++++++++++++++++-------------------------
3 files changed, 158 insertions(+), 124 deletions(-)
diff --git a/META.json b/META.json
index ffd4af5..8dd8aca 100644
--- a/META.json
+++ b/META.json
@@ -4,7 +4,7 @@
"Nicolas Steenlant, C<< <nicolas.steenlant at ugent.be> >>"
],
"dynamic_config" : 0,
- "generated_by" : "Dist::Milla version v1.0.5, Dist::Zilla version 5.016, CPAN::Meta::Converter version 2.132830",
+ "generated_by" : "Dist::Milla version v1.0.5, Dist::Zilla version 5.016, CPAN::Meta::Converter version 2.141170",
"license" : [
"perl_5"
],
diff --git a/README.md b/README.md
index 3ed8dec..d5a7315 100644
--- a/README.md
+++ b/README.md
@@ -320,7 +320,9 @@ Nicolas Steenlant, `<nicolas.steenlant at ugent.be>`
# CONTRIBUTORS
-Patrick Hochstenbach, `<patrick.hochstenbach at ugent.be>`
+Nicolas Franck, `nicolas.franck at ugent.be`
+
+Patrick Hochstenbach, `patrick.hochstenbach at ugent.be`
Vitali Peil, `vitali.peil at uni-bielefeld.de`
@@ -328,6 +330,8 @@ Christian Pietsch, `christian.pietsch at uni-bielefeld.de`
Dave Sherohman, `dave.sherohman at ub.lu.se`
+Jakob Voss, `nichtich at cpan.org`
+
# LICENSE AND COPYRIGHT
This program is free software; you can redistribute it and/or modify it
diff --git a/lib/Catmandu.pm b/lib/Catmandu.pm
index e23c438..4b3541e 100644
--- a/lib/Catmandu.pm
+++ b/lib/Catmandu.pm
@@ -5,10 +5,44 @@ use Catmandu::Env;
use Catmandu::Util qw(:is);
use File::Spec;
+our $VERSION = '0.9';
+
=head1 NAME
Catmandu - a data toolkit
+=head1 SYNOPSIS
+
+ use Catmandu -all;
+ use Catmandu qw(config store);
+ use Catmandu -load;
+ use Catmandu -all -load => [qw(/config/path' '/another/config/path)];
+
+ # If you have Catmandu::OAI and Catmandu::MongoDB installed
+ my $importer = Catmandu->importer('OAI',url => 'https://biblio.ugent.be/oai')
+ my $store = Catmandu->exporter('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;
+
+ # Or be very lazy and do this via the command line
+ $ catmandu import OAI --url https://biblio.ugent.be/oai to MongoDB --database_name test
+ $ catmandu export MongoDB --database_name test --fix myfixes.txt to YAML
+
=head1 DESCRIPTION
Importing, transforming, storing and indexing data should be easy.
@@ -29,87 +63,17 @@ L<https://github.com/LibreCat/Catmandu/wiki/Introduction>.
=head1 ONE STEP INSTALL
-To install all Catmandu components in one easy step:
+To install all Catmandu components in one step:
cpan Task::Catmandu
# or
cpanm --interactive Task::Catmandu
-or read our wiki for more installation hints:
+Read our wiki for more installation hints:
https://github.com/LibreCat/Catmandu/wiki/Install
=cut
-
-our $VERSION = '0.9';
-
-=head1 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)];
-
-=head1 CONFIG
-
-Catmandu configuration options can be stored in files in the root directory of
-your programming project. The file can be YAML, JSON or Perl and is called
-C<catmandu.yml>, C<catmandu.json> or C<catmandu.pl>. In this file you can set
-the default Catmandu stores and exporters to be used. Here is an example of a
-C<catmandu.yml> file:
-
- store:
- default:
- package: ElasticSearch
- options:
- index_name: myrepository
-
- exporter:
- default:
- package: YAML
-
-=head2 Split config
-
-For large configs it's more convenient to split the config into several files.
-You can do so by having multiple config files starting with catmandu*.
-
- catmandu.general.yml
- catmandu.db.yml
- ...
-
-Split config files are processed and merged by L<Config::Onion>.
-
-=head2 Deeply nested config structures
-
-Config files can indicate a path under which their keys will be nested. This
-makes your configuration more readable by keeping indentation to a minimum.
-
-A config file containing
-
- _prefix:
- foo:
- bar:
- baz: 1
-
-will be loaded as
-
- foo:
- bar:
- baz: 1
-
-See L<Config::Onion> for more information on how this works.
-=cut
-
use Sub::Exporter::Util qw(curry_method);
use Sub::Exporter -setup => {
exports => [config => curry_method,
@@ -149,30 +113,8 @@ sub _env {
Return the current logger (the L<Log::Any::Adapter> for category
L<Catmandu::Env>). See L<Log::Any#Logging> for how to send messages to the
-logger.
-
-E.g. turn on Log4perl logging in your application;
-
- package main;
- use Catmandu;
- use Log::Any::Adapter;
- use Log::Log4perl;
-
- Log::Log4perl::init('./log4perl.conf');
- Log::Any::Adapter->set('Log4perl');
-
- my $importer = Catmandu::Importer::JSON->new(...);
- ...
-
-With log4perl.conf something like:
-
- log4perl.rootLogger=DEBUG,STDOUT
- log4perl.appender.STDOUT=Log::Log4perl::Appender::Screen
- log4perl.appender.STDOUT.stderr=1
- log4perl.appender.STDOUT.utf8=1
-
- log4perl.appender.STDOUT.layout=PatternLayout
- log4perl.appender.STDOUT.layout.ConversionPattern=%d [%P] - %p %l time=%r : %m%n
+logger. Read our L<https://github.com/LibreCat/Catmandu/wiki/Cookbook>
+"See some debug messages" for some hints on logging.
=cut
@@ -204,6 +146,7 @@ sub default_load_path { # TODO move to Catmandu::Env
=head2 load
Load all the configuration options in the catmandu.yml configuration file.
+See CONFIG below for extended examples of configuration options.
=head2 load('/path', '/another/path')
@@ -211,6 +154,8 @@ Load all the configuration options stored at alternative paths.
A load path C<':up'> will search upwards from your program for configuration.
+See CONFIG below for extended examples of configuration options.
+
=cut
sub load {
@@ -263,8 +208,11 @@ sub default_store { $_[0]->_env->default_store }
=head2 store([NAME])
-Return an instance of L<Catmandu::Store> with name NAME or use the default store
-when no name is provided. The NAME is set in the configuration file. E.g.
+Return an instance of L<Catmandu::Store>. The NAME is a name of a L<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:
@@ -274,13 +222,25 @@ when no name is provided. The NAME is set in the configuration file. E.g.
test:
package: Mock
-In your program:
+then in your program:
# This will use ElasticSearch
- Catmandu->store->bag->each(sub { ... });
- Catmandu->store('default')->bag->each(sub { ... });
+ 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
- Catmandu->store('test')->bag->search(...);
+ my $store = Catmandu->store('test');
+
+Configuration settings can be overwritten by the store command:
+
+ my $store2 = Catmandu->store('default', index_name => 'test2');
=cut
@@ -299,20 +259,35 @@ sub default_fixer { $_[0]->_env->default_fixer }
=head2 fixer(NAME)
-Return an instance of L<Catmandu::Fix> with name NAME (or 'default' when no
-name is given). The NAME is set in the config. E.g.
+=head2 fixer(FIX,FIX)
+
+=head2 fixer([FIX])
+
+Return an instance of L<Catmandu::Fix>. NAME can be the name of a fixer section
+in a catmandu.yml file. Or, one or more L<Catmandu::Fix>-es can be provided inline.
+
+E.g. if the configuration file 'catmandu.yml' contains:
fixer:
default:
- do_this()
- do_that()
-In your program:
+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'
- 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);
+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');
=cut
@@ -340,25 +315,27 @@ sub default_importer_package { $_[0]->_env->default_importer_package }
=head2 importer(NAME)
-Return an instance of a L<Catmandu::Importer> with name NAME
-(or the default when no name is given).
-The NAME is set in the configuration file. E.g.
+Return an instance of L<Catmandu::Importer>. The NAME is a name of a L<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:
- oai:
+ default:
package: OAI
options:
url: http://www.instute.org/oai/
- feed:
- package: Atom
- options:
- url: http://www.mysite.org/blog/atom
-In your program:
+then in your program all these lines will be equivalent:
- Catmandu->importer('oai')->each(sub { ... } );
- Catmandu->importer('oai', url => 'http://override')->each(sub { ... } );
- Catmandu->importer('feed')->each(sub { ... } );
+ 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');
=cut
@@ -491,9 +468,62 @@ Import everything.
=back
+=head1 CONFIG
+
+Catmandu configuration options can be stored in files in the root directory of
+your programming project. The file can be YAML, JSON or Perl and is called
+C<catmandu.yml>, C<catmandu.json> or C<catmandu.pl>. In this file you can set
+the default Catmandu stores and exporters to be used. Here is an example of a
+C<catmandu.yml> file:
+
+ store:
+ default:
+ package: ElasticSearch
+ options:
+ index_name: myrepository
+
+ exporter:
+ default:
+ package: YAML
+
+=head2 Split config
+
+For large configs it's more convenient to split the config into several files.
+You can do so by having multiple config files starting with catmandu*.
+
+ catmandu.general.yml
+ catmandu.db.yml
+ ...
+
+Split config files are processed and merged by L<Config::Onion>.
+
+=head2 Deeply nested config structures
+
+Config files can indicate a path under which their keys will be nested. This
+makes your configuration more readable by keeping indentation to a minimum.
+
+A config file containing
+
+ _prefix:
+ foo:
+ bar:
+ baz: 1
+
+will be loaded as
+
+ foo:
+ bar:
+ baz: 1
+
+See L<Config::Onion> for more information on how this works.
+
=head1 SEE ALSO
-L<https://github.com/LibreCat/Catmandu/wiki>.
+L<https://github.com/LibreCat/Catmandu/wiki>,
+L<Catmandu::Importer>,
+L<Catmandu::Exporter>,
+L<Catmandu::Store>,
+L<Catmandu::Fix>
=head1 AUTHOR
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libcatmandu-perl.git
More information about the Pkg-perl-cvs-commits
mailing list