[libcatmandu-perl] 13/85: better document and extend Importer

[Jonas Smedegaard]

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 198d750f7a1be5b0ac6a39f7b7aa8066bbe440b9
Author: Jakob Voss <voss at gbv.de>
Date:   Fri May 9 12:28:10 2014 +0200

    better document and extend Importer
---
 lib/Catmandu/Importer.pm | 77 +++++++++++++++++++++++++++++++++---------------
 t/Catmandu-Importer.t    | 18 +++++++++--
 2 files changed, 70 insertions(+), 25 deletions(-)

diff --git a/lib/Catmandu/Importer.pm b/lib/Catmandu/Importer.pm
index b1d25f3..6fc0fc3 100644
--- a/lib/Catmandu/Importer.pm
+++ b/lib/Catmandu/Importer.pm
@@ -27,65 +27,96 @@ has file => (
 has fh => (
     is      => 'ro',
     lazy    => 1,
-    default => sub { io($_[0]->file, mode => 'r', binmode => $_[0]->encoding) },
+    builder => 1,
 );
 
 has encoding => (
     is       => 'ro',
-    builder  => 'default_encoding',
+    builder  => 1,
 );
 
-sub default_encoding {
+sub _build_encoding {
     ':utf8';
 }
 
+sub _build_fh {
+    # build from file. may be build from URL in a future version
+    io($_[0]->file, mode => 'r', binmode => $_[0]->encoding);
+}
+
+sub readline {
+    $_[0]->fh->getline;
+}
+
+sub readall {
+    join '', $_[0]->fh->getlines;
+}
+
 =head1 NAME
 
 Catmandu::Importer - Namespace for packages that can import
 
 =head1 SYNOPSIS
 
-    use Catmandu::Importer::JSON;
+    package Catmandu::Importer::Hello;
 
-    my $importer = Catmandu::Importer::JSON->new(file => "/foo/bar.json");
+    use Catmandu::Sane;
+    use Moo;
 
-    my $n = $importer->each(sub {
-        my $hashref = $_[0];
-        # ...
-    });
+    with 'Catmandu::Importer';
 
+    sub generator {
+        my ($self) = @_;
+        state $fh = $self->fh;
+        return sub {
+            my $name = $self->readline;
+            return defined $name ? { "hello" => $name } : undef;
+        };
+    } 
 
 =head1 DESCRIPTION
 
-A Catmandu::Importer is a stub for Perl packages that can import data from
-an external source (a file, the network, ...).
+A Catmandu::Importer is a Perl packages that can import data from an external
+source (a file, the network, ...). Most importers read from an input stream, 
+such as STDIN, a given file, or an URL to fetch data from, so this base class
+provides helper method for consuming the input stream once.
 
 Every Catmandu::Importer is a L<Catmandu::Fixable> and thus provides a 'fix'
 parameter that can be set in the constructor. For every item returned by the
 generator the given fixes will be applied first.
 
-=head1 METHODS
+Every Catmandu::Importer is a L<Catmandu::Iterable> and its methods (C<first>,
+C<each>, C<to_array>...) should be used to access items from the importer.
+
+=head1 CONFIGURATION
+
+=over
 
-=head2 new(file => $file , encoding => $encoding )
+=item file
 
-Create a new importer reading input from a local file: $file is a string containing the path to
-the file.
+Read input from a local file given by its path. Alternatively a scalar
+reference can be passed to read from a string.
 
-=head2 new(fh => $fh , encoding => $encoding)
+=item fh
 
-Create a new importer by reading from a IO::Handle. Optionally use Catmandu::Util::io to create IO::Handles.
+Read input from an L<IO::Handle>. If not specified, L<Catmandu::Util::io> is used to
+create the input stream from the C<file> argument or by using STDIN.
 
-=head2 count
+=item encoding
 
-=head2 each(&callback)
+Binmode of the input stream C<fh>. Set to C<:utf8> by default.
+
+=back
+
+=head1 METHODS
 
-=head2 ...
+=head2 readline
 
-Every Catmandu::Importer is a L<Catmandu::Iterable> all its methods are inherited.
+Read a line from the input stream. Equivalent to C<< $importer->fh->getline >>.
 
-=head2 log
+=head2 readall
 
-Return the current logger.
+Read the whole input stream as string.
 
 =head1 SEE ALSO
 
diff --git a/t/Catmandu-Importer.t b/t/Catmandu-Importer.t
index 246f94f..f9c560e 100644
--- a/t/Catmandu-Importer.t
+++ b/t/Catmandu-Importer.t
@@ -2,6 +2,7 @@
 
 use strict;
 use warnings;
+use v5.10.1;
 use Test::More;
 use Test::Exception;
 
@@ -17,11 +18,24 @@ require_ok $pkg;
     use Moo;
     with $pkg;
 
-    sub generator { sub {} }
+    sub generator {
+        my ($self) = @_;
+        state $fh = $self->fh;
+        return sub {
+            my $name = $self->readline;
+            return defined $name ? { "hello" => $name } : undef;
+        };
+    }
 }
 
 my $i = T::Importer->new;
 ok $i->does('Catmandu::Iterable');
 
-done_testing 3;
+$i = T::Importer->new( file => \"World" );
+is_deeply $i->to_array, [{ hello => "World"}], 'import from string reference';
+
+$i = T::Importer->new( file => \"Hello\nWorld" );
+is $i->readall, "Hello\nWorld", "import all";
+
+done_testing;
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libcatmandu-perl.git