---
name: "Catmandu::Exporter"
section: "3pm"
platform: "linux"
package: "libcatmandu-perl"
version: "1.2024-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Catmandu::Exporter"
---

# Catmandu::Exporter(3pm)

Namespace for packages that can export

## NAME

Catmandu::Exporter - Namespace for packages that can export

## SYNOPSIS

```
    # From the command line
    # JSON is an importer and YAML an exporter
    $ catmandu convert JSON to YAML < data.json
    # OAI is an importer and JSON an exporter
    $ catmandu convert OAI --url http://biblio.ugent.be/oai to JSON
    # From Perl
    use Catmandu;
    my $importer = Catmandu->importer('JSON', file => 'data.json');
    my $exporter = Catmandu->exporter('YAML');
    $exporter->add({ record => "one"});
    $exporter->add_many([ { record => "one" } , { record => "two" } ]);
    $exporter->add_many($importer);
    $exporter->commit;
    undef($exporter); # Clean up memory
```

## DESCRIPTION

A Catmandu::Exporter is a Perl package that can export data into JSON, YAML, XML or many other formats. By default, data is to STDOUT. Optionally provide a `"file"` or `"fh"` parameter to write to a file, string, or handle.

Every Catmandu::Exporter is a Catmandu::Fixable thus provides a `"fix"` parameter and method to apply fixes to exported items:

```
    my $exporter = Catmandu->exporter('JSON', fix => ['upcase(title)']);
    # This will be printed to STDOUT like: {"title":"MY TITLE"}
    $exporter->add({ title => "my title"});
```

Every Catmandu::Exporter is a Catmandu::Addable thus inherits the methods `"add"` and `"add_many"`.

## CONFIGURATION

- file

  Write output to a local file given by its path or file handle.  Alternatively a scalar reference can be passed to write to a string and a code reference can be used to write to a callback function.

- fh

  Write the output to an IO::Handle. If not specified, Catmandu::Util::io is used to create the output handle from the `"file"` argument or by using STDOUT.

  It is the task of the Perl programmer to close any opened IO::Handles. Catmandu will not do this by itself.

- encoding

  Binmode of the output stream `"fh"`. Set to "`":utf8"`" by default.

- fix

  An ARRAY of one or more fixes or file scripts to be applied to exported items.

## METHODS

### add

Adds one item to be exported.

### add\_many

Adds many items to be exported. This can be either an ARRAY-ref or an Catmandu::Iterator. Returns a true value when the export was successful or undef on error.

### count

Returns the number of items exported by this Catmandu::Exporter.

### log

Returns the current logger.

### commit

Commit all buffers to the output handle.

## CODING

Create your own exporter by creating a Perl package in the Catmandu::Exporter namespace that implements `"Catmandu::Exporter"`. Basically, you need to create a method add which writes a Perl hash to a file handle:

```
    package Catmandu::Exporter::Foo;
    use Catmandu::Sane;
    use Moo;
    with 'Catmandu::Exporter'
    sub add {
        my ($self, $data) = @_;
        my $fh = $self->fh;
        $fh->print( "Hello, World!");
    }
    sub commit {
        my ($self) = @_;
        # this will be called at the end of the record stream
    }
    1;
```

This exporter can be called from the command line as:

```
    $ catmandu convert JSON to Foo < data.json
```

Or, via Perl

```
    use Catmandu;
    my $exporter = Catmandu->exporter('Foo', file => "/tmp/output.txt");
    $exporter->add({test => 123});
    $exporter->commit;
    undef($exporter);
```

## SEE ALSO

See function export\_to\_string in module Catmandu.

The exporters Catmandu::Exporter::JSON, Catmandu::Exporter::YAML, Catmandu::Exporter::CSV, and Catmandu::Exporter::Text are included in Catmandu core.

See Catmandu::Importer for the opposite action.