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.hochstenb...@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

_______________________________________________
Pkg-perl-cvs-commits mailing list
Pkg-perl-cvs-commits@lists.alioth.debian.org
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-perl-cvs-commits

Reply via email to