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>