| 1 | package Catmandu::Exporter; | ||
| 2 | |||
| 3 | 20 | ▶ | use Catmandu::Sane; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 4 | |||
| 5 | 20 | our $VERSION = '1.0201_02'; | |
| 6 | |||
| 7 | 20 | ▶ | use Catmandu::Util qw(io); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 8 | 20 | ▶ | use Moo::Role; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 9 | 20 | ▶ | use namespace::clean; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 10 | |||
| 11 | 20 | with 'Catmandu::Logger'; | |
| 12 | 20 | with 'Catmandu::Addable'; | |
| 13 | 20 | with 'Catmandu::Counter'; | |
| 14 | |||
| 15 | 9 | ▶ | has file => (is => 'ro', lazy => 1, default => sub {\*STDOUT},); |
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||
| 16 | |||
| 17 | has fh => ( | ||
| 18 | is => 'ro', | ||
| 19 | lazy => 1, | ||
| 20 | 27 | ▶ | default => sub {io($_[0]->file, mode => 'w', binmode => $_[0]->encoding)}, |
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||
| 21 | 20 | ); | |
| 22 | |||
| 23 | after add => sub { | ||
| 24 | 265 | ▶ | $_[0]->inc_count; |
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||
| 25 | 20 | }; | |
| 26 | |||
| 27 | 28 | ▶ | sub encoding {':utf8'} |
|
Subroutine
encoding: called CC=1 SCAR=0.0
Pod
documented
| |||
| 28 | |||
| 29 | 20 | 1; | |
| 30 | |||
| 31 | __END__ | ||
| 32 | |||
| 33 | =pod | ||
| 34 | |||
| 35 | =head1 NAME | ||
| 36 | |||
| 37 | Catmandu::Exporter - Namespace for packages that can export | ||
| 38 | |||
| 39 | =head1 SYNOPSIS | ||
| 40 | |||
| 41 | # From the command line | ||
| 42 | |||
| 43 | # JSON is an importer and YAML an exporter | ||
| 44 | $ catmandu convert JSON to YAML < data.json | ||
| 45 | |||
| 46 | # OAI is an importer and JSON an exporter | ||
| 47 | $ catmandu convert OAI --url http://biblio.ugent.be/oai to JSON | ||
| 48 | |||
| 49 | # From Perl | ||
| 50 | use Catmandu; | ||
| 51 | |||
| 52 | my $importer = Catmandu->importer('JSON', file => 'data.json'); | ||
| 53 | my $exporter = Catmandu->exporter('YAML'); | ||
| 54 | |||
| 55 | $exporter->add({ record => "one"}); | ||
| 56 | $exporter->add_many([ { record => "one" } , { record => "two" } ]); | ||
| 57 | $exporter->add_many($importer); | ||
| 58 | |||
| 59 | =head1 DESCRIPTION | ||
| 60 | |||
| 61 | A Catmandu::Exporter is a Perl package that can export data into JSON, YAML, XML | ||
| 62 | or many other formats. By default, data is to STDOUT. Optionally provide a C<file> | ||
| 63 | or C<fh> parameter to write to a file, string, or handle. | ||
| 64 | |||
| 65 | Every Catmandu::Exporter is a L<Catmandu::Fixable> thus provides a C<fix> | ||
| 66 | parameter and method to apply fixes to exported items: | ||
| 67 | |||
| 68 | my $exporter = Catmandu->exporter('JSON', fix => ['upcase(title)']); | ||
| 69 | |||
| 70 | # This will be printed to STDOUT like: {"title":"MY TITLE"} | ||
| 71 | $exporter->add({ title => "my title"}); | ||
| 72 | |||
| 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 | =item encoding | ||
| 94 | |||
| 95 | Binmode of the output stream C<fh>. Set to "C<:utf8>" by default. | ||
| 96 | |||
| 97 | =item fix | ||
| 98 | |||
| 99 | An ARRAY of one or more fixes or file scripts to be applied to exported items. | ||
| 100 | |||
| 101 | =back | ||
| 102 | |||
| 103 | =head1 METHODS | ||
| 104 | |||
| 105 | =head2 add | ||
| 106 | |||
| 107 | Adds one object to be exported. | ||
| 108 | |||
| 109 | =head2 add_many | ||
| 110 | |||
| 111 | Adds many objects to be exported. This can be either an ARRAY-ref or | ||
| 112 | an L<Catmandu::Iterator>. Returns a true value when the export was | ||
| 113 | successful or undef on error. | ||
| 114 | |||
| 115 | =head2 count | ||
| 116 | |||
| 117 | Returns the number of items exported by this Catmandu::Exporter. | ||
| 118 | |||
| 119 | =head2 log | ||
| 120 | |||
| 121 | Returns the current logger. | ||
| 122 | |||
| 123 | =head1 CODING | ||
| 124 | |||
| 125 | Create your own exporter by creating a Perl package in the Catmandu::Exporter namespace | ||
| 126 | that implements C<Catmandu::Exporter>. Basically, you need to create a method add which | ||
| 127 | writes a Perl hash to a file handle: | ||
| 128 | |||
| 129 | |||
| 130 | package Catmandu::Exporter::Foo; | ||
| 131 | |||
| 132 | use Catmandu::Sane; | ||
| 133 | use Moo; | ||
| 134 | |||
| 135 | with 'Catmandu::Exporter' | ||
| 136 | |||
| 137 | sub add { | ||
| 138 | my ($self, $data) = @_; | ||
| 139 | my $fh = $self->fh; | ||
| 140 | $fh->print( "Hello, World!"); | ||
| 141 | } | ||
| 142 | |||
| 143 | 1; | ||
| 144 | |||
| 145 | This exporter can be called from the command line as: | ||
| 146 | |||
| 147 | $ catmandu convert JSON to Foo < data.json | ||
| 148 | |||
| 149 | Or, via Perl | ||
| 150 | |||
| 151 | use Catmandu; | ||
| 152 | |||
| 153 | my $exporter = Catmandu->exporter('Foo', file => "/tmp/output.txt"); | ||
| 154 | |||
| 155 | $exporter->add({test => 123}); | ||
| 156 | |||
| 157 | =head1 SEE ALSO | ||
| 158 | |||
| 159 | See function L<export_to_string|Catmandu/export_to_string> in module | ||
| 160 | L<Catmandu>. | ||
| 161 | |||
| 162 | The exporters L<Catmandu::Exporter::JSON>, L<Catmandu::Exporter::YAML>, | ||
| 163 | L<Catmandu::Exporter::CSV>, and L<Catmandu::Exporter::Text> are included in | ||
| 164 | Catmandu core. | ||
| 165 | |||
| 166 | See L<Catmandu::Importer> for the opposite action. | ||
| 167 | |||
| 168 | =cut | ||