Repository files navigation

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 convertan empty input (Null) and add one propertyhello with valueworld.

We can ask Catmandu not to generate the default JSON output butconvert 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 keywordto on the command line:

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

The left part of theto keyword is called theImporter, theright part of theto keyword is called theExporter. Catmanduprovides Importers and Exports for many formats.

Each Importer and Exporter can have options that change the behaviorof conversion. The options can be read using theperldoc commandon each Importer and Exports:

perldoc Catmandu::Importer::YAMLperldoc Catmandu::Exporter::JSON

Note, many formats are available as Importer and Exporter.

As an example, we can use a JSON Exporter optionpretty to providea 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 plusoptional conversions of the data inside these fields. Catmandu providestheFix language to assist in these mappings. A full list Fixfuncton is available athttps://librecat.org/assets/catmandu_cheat_sheet.pdf.

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

$ cat example.fixadd_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 Streetbest_color: Bluecolors:    - Red    - Green    - Blue...

In the example we created the Fix Scriptexample.fix that containsa combination of mappings and data conversion on (nested) data. Werun a YAML to YAML conversion using theexample.fix Fix Script.

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

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

$ cat titles.fixmarc_map('245',title)retain(title)$ catmandu convert MARC --type ISO --fix titles.fix to CSV < data.mrc

Themarc_map is a specialized Fix function for MARC data. In the exampleabove the245 field of each MARC record is mapped to thetitle field.Theretain Fix function keeps only thetitle field in the output.

A 18 day tutorial on Catmandu and the Fix language is available athttps://librecatproject.wordpress.com/tutorial/.

More information is also available in our wikihttps://github.com/LibreCat/Catmandu/wiki