[libcatmandu-perl] 30/101: TabularExporter pod

[Jonas Smedegaard]

This is an automated email from the git hooks/post-receive script.

js pushed a commit to branch master
in repository libcatmandu-perl.

commit e4b9154d13c0ed40f4e27b2f6c9586b8e331029e
Author: Nicolas Steenlant <nicolas.steenlant at ugent.be>
Date:   Fri Dec 11 16:13:21 2015 +0100

    TabularExporter pod
---
 lib/Catmandu/Exporter.pm        |  4 ++--
 lib/Catmandu/Exporter/CSV.pm    | 24 ++++++++++++++----------
 lib/Catmandu/TabularExporter.pm | 39 ++++++++++++++++++++++++++++++++++-----
 3 files changed, 50 insertions(+), 17 deletions(-)

diff --git a/lib/Catmandu/Exporter.pm b/lib/Catmandu/Exporter.pm
index 9ab3d54..8cc9b30 100644
--- a/lib/Catmandu/Exporter.pm
+++ b/lib/Catmandu/Exporter.pm
@@ -68,8 +68,8 @@ Catmandu::Exporter - Namespace for packages that can export
 
 A Catmandu::Exporter is a Perl package that can export data. By default, data
 items are written to STDOUT. Optionally provide a C<file> or C<fh> parameter to
-write to a file, string, or handle. New exporter modules are expected to use the 
-C<print> method of C<fh>.
+write to a file, string, or handle. New exporter modules are expected to use
+the C<print> method of C<fh>.
 
 Every Catmandu::Exporter is a L<Catmandu::Fixable> thus provides a C<fix>
 parameter and method to apply fixes to exported items.
diff --git a/lib/Catmandu/Exporter/CSV.pm b/lib/Catmandu/Exporter/CSV.pm
index 0672417..ac67698 100644
--- a/lib/Catmandu/Exporter/CSV.pm
+++ b/lib/Catmandu/Exporter/CSV.pm
@@ -86,9 +86,9 @@ Catmandu::Exporter::CSV - a CSV exporter
 
 This C<Catmandu::Exporter> exports items as rows with comma-separated values
 (CSV). Serialization is based on L<Text::CSV>. A header line with field names
-will be included if option C<header> is set. Field names can be read from the
-first item exported or set by option C<fields>. Newlines and tabulator values
-are in field values are escaped as C<\n>, C<\r>, and C<\t>.
+will be included if option C<header> is set. See L<Catmandu::TabularExporter>
+on how to configure the field mapping and column names. Newlines and tabulator
+values in field values are escaped as C<\n>, C<\r>, and C<\t>.
 
 =head1 CONFIGURATION
 
@@ -128,21 +128,25 @@ Character for escaping inside quoted field (C<"> by default)
 
 =item fields
 
-List of fields to be used as columns, given as array reference, comma-separated
-string, or hash reference.
+See L<Catmandu::TabularExporter>.
+
+=item columns
+
+See L<Catmandu::TabularExporter>.
 
 =item header
 
-Include a header line with the column names, if set to C<1> (the default).
-Custom field names can be supplied as hash reference. By default field names
-are used as as column names.
+Includes a header line with the column names, if set to C<1> (the default).
+See L<Catmandu::TabularExporter> on how to configure the field mapping and
+column names.
 
 =back
 
 =head1 METHODS
 
-See L<Catmandu::Exporter>, L<Catmandu::Addable>, L<Catmandu::Fixable>,
-L<Catmandu::Counter>, and L<Catmandu::Logger> for a full list of methods.
+See L<Catmandu::TabularExporter>, L<Catmandu::Exporter>, L<Catmandu::Addable>,
+L<Catmandu::Fixable>, L<Catmandu::Counter>, and L<Catmandu::Logger> for a full
+list of methods.
 
 =head1 SEE ALSO
 
diff --git a/lib/Catmandu/TabularExporter.pm b/lib/Catmandu/TabularExporter.pm
index ff85952..9a68557 100644
--- a/lib/Catmandu/TabularExporter.pm
+++ b/lib/Catmandu/TabularExporter.pm
@@ -34,7 +34,7 @@ has collect_fields => (
 
 around add => sub {
     my ($orig, $self, $data) = @_;
-    $self->_set_fields([sort keys %$data]) unless $self->fields;
+    $self->_set_fields($data) unless $self->fields;
     $orig->($self, $data);
 };
 
@@ -59,13 +59,13 @@ around add_many => sub {
             }
         }
 
-        my %keys;
+        my $keys = {};
         for my $data (@$coll) {
             for my $key (keys %$data) {
-                $keys{$key} ||= 1;
+                $keys->{$key} ||= 1;
             }
         }
-        $self->_set_fields([sort keys %keys]);
+        $self->_set_fields($keys);
 
         $many = $coll;
     }
@@ -81,6 +81,35 @@ __END__
 
 =head1 NAME
 
-Catmandu::TabularExporter - base role for exporters that export a tabular format like CSV
+Catmandu::TabularExporter - base role for tabular exporters like CSV
+
+=head1 DESCRIPTION
+
+See L<Catmandu::Exporter> for the base functionality of this role. This role
+adds some functionality tailored to tabular or columnar exporters.
+
+=head1 CONFIGURATION
+
+=over
+
+=item fields
+
+The fields to be mapped. Can be an arrayref, example hashref or comma separated
+string. If missing, the fields of the first record encountered will be used. If
+C<collect_fields> is true, all fields names in the record stream will be
+collected first.
+
+=item columns
+
+Optional custom column labels. Can be an arrayref, example hashref or comma
+separated string.
+
+=item collect_fields
+
+See C<fields> for a description. Note that this option will cause all records
+in the stream to be buffered in memory.
+
+=back
 
 =cut
+

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