File Coverage

blib/lib/Catmandu/Exporter.pm
Criterion Covered Total %
statement 13 13 100.0
branch n/a
condition n/a
subroutine 5 5 100.0
pod 1 1 100.0
total 19 19 100.0


line stmt bran cond sub pod time code
1              
2             use Catmandu::Sane;
3 23     23   102933  
  23         65  
  23         1408  
4             our $VERSION = '1.2019';
5              
6             use Catmandu::Util qw(io);
7 23     23   164 use Moo::Role;
  23         46  
  23         2363  
8 23     23   121 use namespace::clean;
  23         1104  
  23         158  
9 23     23   8571  
  23         44  
  23         146  
10             with 'Catmandu::Logger';
11             with 'Catmandu::Addable';
12             with 'Catmandu::Counter';
13              
14             has file => (is => 'ro', lazy => 1, default => sub {\*STDOUT},);
15              
16             has fh => (
17             is => 'ro',
18             lazy => 1,
19             default => sub {io($_[0]->file, mode => 'w', binmode => $_[0]->encoding)},
20             );
21              
22             after add => sub {
23             $_[0]->inc_count;
24             };
25              
26              
27 44     44 1 2036 1;
28              
29              
30             =pod
31              
32             =head1 NAME
33              
34             Catmandu::Exporter - Namespace for packages that can export
35              
36             =head1 SYNOPSIS
37              
38             # From the command line
39              
40             # JSON is an importer and YAML an exporter
41             $ catmandu convert JSON to YAML < data.json
42              
43             # OAI is an importer and JSON an exporter
44             $ catmandu convert OAI --url http://biblio.ugent.be/oai to JSON
45              
46             # From Perl
47             use Catmandu;
48              
49             my $importer = Catmandu->importer('JSON', file => 'data.json');
50             my $exporter = Catmandu->exporter('YAML');
51              
52             $exporter->add({ record => "one"});
53             $exporter->add_many([ { record => "one" } , { record => "two" } ]);
54             $exporter->add_many($importer);
55              
56             $exporter->commit;
57              
58             undef($exporter); # Clean up memory
59              
60             =head1 DESCRIPTION
61              
62             A Catmandu::Exporter is a Perl package that can export data into JSON, YAML, XML
63             or many other formats. By default, data is to STDOUT. Optionally provide a C<file>
64             or C<fh> parameter to write to a file, string, or handle.
65              
66             Every Catmandu::Exporter is a L<Catmandu::Fixable> thus provides a C<fix>
67             parameter and method to apply fixes to exported items:
68              
69             my $exporter = Catmandu->exporter('JSON', fix => ['upcase(title)']);
70              
71             # This will be printed to STDOUT like: {"title":"MY TITLE"}
72             $exporter->add({ title => "my title"});
73              
74             Every Catmandu::Exporter is a L<Catmandu::Addable> thus inherits the methods
75             C<add> and C<add_many>.
76              
77             =head1 CONFIGURATION
78              
79             =over
80              
81             =item file
82              
83             Write output to a local file given by its path or file handle. Alternatively a
84             scalar reference can be passed to write to a string and a code reference can be
85             used to write to a callback function.
86              
87             =item fh
88              
89             Write the output to an L<IO::Handle>. If not specified,
90             L<Catmandu::Util::io|Catmandu::Util/IO-functions> is used to create the output
91             handle from the C<file> argument or by using STDOUT.
92              
93             It is the task of the Perl programmer to close any opened IO::Handles.
94             Catmandu will not do this by itself.
95              
96             =item encoding
97              
98             Binmode of the output stream C<fh>. Set to "C<:utf8>" by default.
99              
100             =item fix
101              
102             An ARRAY of one or more fixes or file scripts to be applied to exported items.
103              
104             =back
105              
106             =head1 METHODS
107              
108             =head2 add
109              
110             Adds one item to be exported.
111              
112             =head2 add_many
113              
114             Adds many items to be exported. This can be either an ARRAY-ref or
115             an L<Catmandu::Iterator>. Returns a true value when the export was
116             successful or undef on error.
117              
118             =head2 count
119              
120             Returns the number of items exported by this Catmandu::Exporter.
121              
122             =head2 log
123              
124             Returns the current logger.
125              
126             =head2 commit
127              
128             Commit all buffers to the output handle.
129              
130             =head1 CODING
131              
132             Create your own exporter by creating a Perl package in the Catmandu::Exporter namespace
133             that implements C<Catmandu::Exporter>. Basically, you need to create a method add which
134             writes a Perl hash to a file handle:
135              
136              
137             package Catmandu::Exporter::Foo;
138              
139             use Catmandu::Sane;
140             use Moo;
141              
142             with 'Catmandu::Exporter'
143              
144             sub add {
145             my ($self, $data) = @_;
146             my $fh = $self->fh;
147             $fh->print( "Hello, World!");
148             }
149              
150             sub commit {
151             my ($self) = @_;
152             # this will be called at the end of the record stream
153             }
154              
155             1;
156              
157             This exporter can be called from the command line as:
158              
159             $ catmandu convert JSON to Foo < data.json
160              
161             Or, via Perl
162              
163             use Catmandu;
164              
165             my $exporter = Catmandu->exporter('Foo', file => "/tmp/output.txt");
166              
167             $exporter->add({test => 123});
168              
169             $exporter->commit;
170              
171             undef($exporter);
172              
173             =head1 SEE ALSO
174              
175             See function L<export_to_string|Catmandu/export_to_string> in module
176             L<Catmandu>.
177              
178             The exporters L<Catmandu::Exporter::JSON>, L<Catmandu::Exporter::YAML>,
179             L<Catmandu::Exporter::CSV>, and L<Catmandu::Exporter::Text> are included in
180             Catmandu core.
181              
182             See L<Catmandu::Importer> for the opposite action.
183              
184             =cut