Catmandu::Introduction - A 5 minute introduction to Catmandu

$ 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
...  

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.

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"
}]

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.

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.

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