Catmandu::Introduction(3pm)

NAME
Catmandu::Introduction - A 5 minute introduction to Catmandu

HELLO WORLD
    $ catmandu convert Null --fix 'add_field(hello,world)'
    [{"hello":"world"}]

The example above generates the JSON output "[{"hello":"world"}]" on the standard output. We asked the Catmandu processor to convert an empty input ("Null") and add one property "hello" with value "world".

We can ask Catmandu not to generate the default JSON output but convert to a YAML output:

    $ catmandu convert Null --fix 'add_field(hello,world)' to YAML
    ---
    hello: world
    ...

FORMAT to FORMAT
Catmandu can be used to convert an input format to an output format. Use the keyword "to" on the command line:

    $ cat file.yaml
    ---
    hello: world
    ...
    $ catmandu convert YAML to JSON < file.yaml
    [{"hello":"world"}]

The left part of the "to" keyword is called the "Importer", the right part of the "to" keyword is called the "Exporter". Catmandu provides Importers and Exports for many formats.

OPTIONS
Each Importer and Exporter can have options that change the behavior of conversion. The options can be read using the "perldoc" command on each Importer and Exports:

    perldoc Catmandu::Importer::YAML
    perldoc Catmandu::Exporter::JSON

Note, many formats are available as Importer and Exporter.

As an example, we can use a JSON Exporter option "pretty" to provide a pretty printed version of the JSON:

    $ catmandu convert YAML to JSON --pretty 1 < file.yaml
    [{
        "hello" : "world"
    }]

FIX LANGUAGE
Many data conversions need a mapping from one field to another field plus optional conversions of the data inside these fields. Catmandu provides the "Fix" language to assist in these mappings. A full list Fix functon is available at <https://librecat.org/assets/catmandu_cheat_sheet.pdf>.

Fixes can be provided inline as text argument of the command line "--fix" argument, or as a pointer to a "Fix Script". A Fix Scripts groups one or more fixes in a file.

    $ cat example.fix
    add_field('address.street','Walker Street')
    add_field('address.number','15')
    copy_field('colors.2','best_color')

    $ cat data.yaml
    ---
    colors:
    - Red
    - Green
    - Blue
    ...

    $ catmandu convert YAML --fix example.fix to YAML < data.yaml
    ---
    address:
        number: '15'
        street: Walker Street
    best_color: Blue
    colors:
        - Red
        - Green
        - Blue
    ...

In the example we created the Fix Script "example.fix" that contains a combination of mappings and data conversion on (nested) data. We run a YAML to YAML conversion using the "example.fix" Fix Script.

SPECIALIZATIONS
Catmandu was mainly created for data conversions of specialized metadata languages in the field of libraries, archives and museums. One of the specialized Importers (and Export) is the Catmandu::MARC package. This package can read, write and convert MARC files.

For instance, to extract all the titles from an ISO MARC file one could write:

    $ cat titles.fix
    marc_map('245',title)
    retain(title)

    $ catmandu convert MARC --type ISO --fix titles.fix to CSV < data.mrc

The "marc_map" is a specialized Fix function for MARC data. In the example above the 245 field of each MARC record is mapped to the "title" field. The "retain" Fix function keeps only the "title" field in the output.

TUTORIAL
A 18 day tutorial on Catmandu and the Fix language is available at <https://librecatproject.wordpress.com/tutorial/>.

More information is also available in our wiki <https://github.com/LibreCat/Catmandu/wiki>