.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Catmandu::Introduction 3pm" .TH Catmandu::Introduction 3pm "2023-03-03" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Catmandu::Introduction \- A 5 minute introduction to Catmandu .SH "HELLO WORLD" .IX Header "HELLO WORLD" .Vb 2 \& $ catmandu convert Null \-\-fix \*(Aqadd_field(hello,world)\*(Aq \& [{"hello":"world"}] .Ve .PP The example above generates the \s-1JSON\s0 output \f(CW\*(C`[{"hello":"world"}]\*(C'\fR on the standard output. We asked the Catmandu processor to convert an empty input (\f(CW\*(C`Null\*(C'\fR) and add one property \f(CW\*(C`hello\*(C'\fR with value \&\f(CW\*(C`world\*(C'\fR. .PP We can ask Catmandu not to generate the default \s-1JSON\s0 output but convert to a \s-1YAML\s0 output: .PP .Vb 4 \& $ catmandu convert Null \-\-fix \*(Aqadd_field(hello,world)\*(Aq to YAML \& \-\-\- \& hello: world \& ... .Ve .SH "FORMAT to FORMAT" .IX Header "FORMAT to FORMAT" Catmandu can be used to convert an input format to an output format. Use the keyword \f(CW\*(C`to\*(C'\fR on the command line: .PP .Vb 6 \& $ cat file.yaml \& \-\-\- \& hello: world \& ... \& $ catmandu convert YAML to JSON < file.yaml \& [{"hello":"world"}] .Ve .PP The left part of the \f(CW\*(C`to\*(C'\fR keyword is called the \f(CW\*(C`Importer\*(C'\fR, the right part of the \f(CW\*(C`to\*(C'\fR keyword is called the \f(CW\*(C`Exporter\*(C'\fR. Catmandu provides Importers and Exports for many formats. .SH "OPTIONS" .IX Header "OPTIONS" Each Importer and Exporter can have options that change the behavior of conversion. The options can be read using the \f(CW\*(C`perldoc\*(C'\fR command on each Importer and Exports: .PP .Vb 2 \& perldoc Catmandu::Importer::YAML \& perldoc Catmandu::Exporter::JSON .Ve .PP Note, many formats are available as Importer and Exporter. .PP As an example, we can use a \s-1JSON\s0 Exporter option \f(CW\*(C`pretty\*(C'\fR to provide a pretty printed version of the \s-1JSON:\s0 .PP .Vb 4 \& $ catmandu convert YAML to JSON \-\-pretty 1 < file.yaml \& [{ \& "hello" : "world" \& }] .Ve .SH "FIX LANGUAGE" .IX Header "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 \f(CW\*(C`Fix\*(C'\fR language to assist in these mappings. A full list Fix functon is available at . .PP Fixes can be provided inline as text argument of the command line \f(CW\*(C`\-\-fix\*(C'\fR argument, or as a pointer to a \f(CW\*(C`Fix Script\*(C'\fR. A Fix Scripts groups one or more fixes in a file. .PP .Vb 4 \& $ cat example.fix \& add_field(\*(Aqaddress.street\*(Aq,\*(AqWalker Street\*(Aq) \& add_field(\*(Aqaddress.number\*(Aq,\*(Aq15\*(Aq) \& copy_field(\*(Aqcolors.2\*(Aq,\*(Aqbest_color\*(Aq) \& \& $ cat data.yaml \& \-\-\- \& colors: \& \- Red \& \- Green \& \- Blue \& ... \& \& $ catmandu convert YAML \-\-fix example.fix to YAML < data.yaml \& \-\-\- \& address: \& number: \*(Aq15\*(Aq \& street: Walker Street \& best_color: Blue \& colors: \& \- Red \& \- Green \& \- Blue \& ... .Ve .PP In the example we created the Fix Script \f(CW\*(C`example.fix\*(C'\fR that contains a combination of mappings and data conversion on (nested) data. We run a \s-1YAML\s0 to \s-1YAML\s0 conversion using the \f(CW\*(C`example.fix\*(C'\fR Fix Script. .SH "SPECIALIZATIONS" .IX Header "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 \s-1MARC\s0 files. .PP For instance, to extract all the titles from an \s-1ISO MARC\s0 file one could write: .PP .Vb 3 \& $ cat titles.fix \& marc_map(\*(Aq245\*(Aq,title) \& retain(title) \& \& $ catmandu convert MARC \-\-type ISO \-\-fix titles.fix to CSV < data.mrc .Ve .PP The \f(CW\*(C`marc_map\*(C'\fR is a specialized Fix function for \s-1MARC\s0 data. In the example above the \f(CW245\fR field of each \s-1MARC\s0 record is mapped to the \f(CW\*(C`title\*(C'\fR field. The \f(CW\*(C`retain\*(C'\fR Fix function keeps only the \f(CW\*(C`title\*(C'\fR field in the output. .SH "TUTORIAL" .IX Header "TUTORIAL" A 18 day tutorial on Catmandu and the Fix language is available at . .PP More information is also available in our wiki