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.
[{"hello":"world"}]
Null
hello
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:
to
$ 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.
Importer
Exporter
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
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:
pretty
$ 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.
Fix
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.
--fix
Fix Script
$ 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.
example.fix
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.
marc_map
245
title
retain
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
To install Catmandu, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Catmandu
CPAN shell
perl -MCPAN -e shell install Catmandu
For more information on module installation, please visit the detailed CPAN module installation guide.