.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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::Fix::marc_spec 3pm"
.TH Catmandu::Fix::marc_spec 3pm "2019-02-25" "perl v5.28.1" "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::Fix::marc_spec \- reference MARC values via
MARCspec \- A common MARC record path language <http://marcspec.github.io/MARCspec/>
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In a fix file e.g. 'my.fix':
.PP
.Vb 2
\&    # Assign value of MARC leader to my.ldr.all
\&    marc_spec(\*(AqLDR\*(Aq, my.ldr.all)
\&
\&    # Assign values of all subfields of field 245 as a joined string
\&    marc_spec(\*(Aq245\*(Aq, my.title.all)
\&
\&    # If field 245 exists, set string \*(Aqthe title\*(Aq as the value of my.title.default
\&    marc_spec(\*(Aq245\*(Aq, my.title.default, value:\*(Aqthe title\*(Aq)
\&
\&    # Assign values of all subfields of every field 650 to my.subjects.all
\&    # as a joined string
\&    marc_spec(\*(Aq650\*(Aq, my.subjects.all)
\&
\&    # Same as above with joining characters \*(Aq###\*(Aq
\&    marc_spec(\*(Aq650\*(Aq, my.subjects.all, join:\*(Aq###\*(Aq)
\&
\&    # Same as above but added as an element to the array my.append.subjects
\&    marc_spec(\*(Aq650\*(Aq, my.append.subjects.$append, join:\*(Aq###\*(Aq)
\&
\&    # Every value of a subfield will be an array element
\&    marc_spec(\*(Aq650\*(Aq, my.split.subjects, split:1)
\&
\&    # Assign values of all subfields of all fields having indicator 1 = 1
\&    # and indicator 2 = 0 to the my.fields.indicators10 array.
\&    marc_spec(\*(Aq...{^1=\e1}{^2=\e0}\*(Aq, my.fields.indicators10.$append)
\&
\&    # Assign first four characters of leader to my.firstcharpos.ldr
\&    marc_spec(\*(AqLDR/0\-3\*(Aq, my.firstcharpos.ldr)
\&
\&    # Assign last four characters of leader to my.lastcharpos.ldr
\&    marc_spec(\*(AqLDR/#\-3\*(Aq, my.lastcharpos.ldr)
\&
\&    # Assign value of subfield a of field 245 to my.title.proper
\&    marc_spec(\*(Aq245$a\*(Aq, my.title.proper)
\&
\&    # Assign first two characters of subfield a of field 245 to my.title.proper
\&    marc_spec(\*(Aq245$a/0\-1\*(Aq, my.title.charpos)
\&
\&    # Assign all subfields of second field 650 to my.second.subject
\&    marc_spec(\*(Aq650[1]\*(Aq, my.second.subject)
\&
\&    # Assign values of all subfields of last field 650 to my.last.subject
\&    marc_spec(\*(Aq650[#]\*(Aq, my.last.subject)
\&
\&    # Assign an array of values of all subfields of the first two fields 650
\&    # to my.two.split.subjects
\&    marc_spec(\*(Aq650[0\-1]\*(Aq, my.two.split.subjects, split:1)
\&
\&    # Assign a joined string of values of all subfields of the last two fields 650
\&    # to my.two.join.subjects
\&    marc_spec(\*(Aq650[#\-1]\*(Aq, my.two.join.subjects, join:\*(Aq###\*(Aq)
\&
\&    # Assign value of first subfield a of all fields 020 to my.isbn.number
\&    marc_spec(\*(Aq020$a[0]\*(Aq, my.isbn.number)
\&
\&    # Assign value of first subfield q of first field 020 to my.isbn.qual.one
\&    marc_spec(\*(Aq020[0]$q[0]\*(Aq, my.isbn.qual.none)
\&
\&    # Assign values of subfield q and a in the order stated as an array
\&    # to  my.isbns.pluck.all
\&    # without option \*(Aqpluck:1\*(Aq the elments will be in \*(Aqnatural\*(Aq order
\&    # see example below
\&    marc_spec(\*(Aq020$q$a\*(Aq, my.isbns.pluck.all, split:1, pluck:1)
\&
\&    # Assign value of last subfield q and second subfield a
\&    # in \*(Aqnatural\*(Aq order of last field 020 as an array to my.isbn.qual.other
\&    marc_spec(\*(Aq020[#]$q[#]$a[1]\*(Aq, my.isbn.qual.other, split:1)
\&
\&    # Assign first five characters of value of last subfield q and last character
\&    # of value of second subfield a in \*(Aqnatural\*(Aq order of all fields 020
\&    # as an array to  my.isbn.qual.substring.other
\&    marc_spec(\*(Aq020$q[#]/0\-4$a[1]/#\*(Aq, my.isbn.qual.substring.other, split:1)
\&
\&    # Assign values of of all other subfields than a of field 020
\&    # to my.isbn.other.subfields
\&    marc_spec(\*(Aq020$a\*(Aq, my.isbn.other.subfields, invert:1)
\&
\&    # Assign value of subfield a of field 245 only, if subfield a of field 246
\&    # with value 1 for indicator1 exists
\&    marc_spec(\*(Aq245$a{246^1=\e1}\*(Aq, my.var.title)
.Ve
.PP
And then on command line:
.PP
.Vb 1
\&    catmandu convert MARC to YAML \-\-fix my.fix < perl_books.mrc
.Ve
.PP
See Catmandu Importers <http://librecat.org/Catmandu/#importers> and
Catmandu Fixes <http://librecat.org/Catmandu/#fixes> for a deeper
understanding of how Catmandu <http://librecat.org/> works.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Catmandu::Fix::marc_spec is a fix for the
famous Catmandu Framework.
.PP
For the most part it behaves like
Catmandu::Fix::marc_map , but has a more fine
grained method to reference \s-1MARC\s0 data content.
.PP
See MARCspec \- A common \s-1MARC\s0 record path language <http://marcspec.github.io/MARCspec/>
for documentation on the path syntax.
.SH "METHODS"
.IX Header "METHODS"
.SS "marc_spec(MARCspec, \s-1JSON_PATH, OPT:VAL, OPT2:VAL,...\s0)"
.IX Subsection "marc_spec(MARCspec, JSON_PATH, OPT:VAL, OPT2:VAL,...)"
First parameter must be a string, following the syntax of
MARCspec \- A common \s-1MARC\s0 record path language <http://marcspec.github.io/MARCspec/>.
Do always use single quotes with this first parameter.
.PP
Second parameter is a string describing the variable or the variable path
to assign referenced values to
(see Catmandu Paths <http://librecat.org/Catmandu/#paths>).
.PP
You may use one of \f(CW$first\fR, \f(CW$last\fR, \f(CW$prepend\fR or \f(CW$append\fR to add
referenced data values to a specific position of an array
(see Catmandu Wildcards <http://librecat.org/Catmandu/#wildcards> and
mapping rules at <https://github.com/LibreCat/Catmandu\-MARC/wiki/Mapping\-rules>).
.PP
.Vb 2
\&    # INPUT
\&    [245,1,0,"a","Cross\-platform Perl /","c","Eric F. Johnson."]
\&
\&    # CALL
\&    marc_spec(\*(Aq245\*(Aq, my.title.$append)
\&
\&    # OUTPUT
\&    {
\&      my {
\&        title [
\&            [0] "Cross\-platform Perl /Eric F. Johnson."
\&        ]
\&      }
\&
\&    }
.Ve
.PP
Third and every other parameters are optional and must
be in the form of key:value (see \*(L"\s-1OPTONS\*(R"\s0 for a deeper
understanding of options).
.SH "OPTIONS"
.IX Header "OPTIONS"
.SS "split: 0|1"
.IX Subsection "split: 0|1"
If split is set to 1, every fixed fields value or every subfield will be
an array element.
.PP
.Vb 3
\&    # INPUT
\&    [650," ",0,"a","Perl (Computer program language)"],
\&    [650," ",0,"a","Web servers."]
\&
\&    # CALL
\&    marc_spec(\*(Aq650\*(Aq, my.subjects, split:1)
\&
\&    # OUTPUT
\&    {
\&      my {
\&        subjects [
\&            [0] "Perl (Computer program language)",
\&            [1] "Web servers."
\&        ]
\&      }
\&    }
.Ve
.PP
See split mapping rules at <https://github.com/LibreCat/Catmandu\-MARC/wiki/Mapping\-rules>.
.SS "nested_arrays: 0|1"
.IX Subsection "nested_arrays: 0|1"
Using the nested_array
option the output will be an array of array of strings (one array item for
each matched field, one array of strings for each matched subfield).
.PP
.Vb 3
\&    # INPUT
\&    [650," ",0,"a","Perl (Computer program language)"],
\&    [650," ",0,"a","Web servers."]
\&
\&    # CALL
\&    marc_spec(\*(Aq650\*(Aq, my.subjects, nested_arrays:1)
\&
\&    # OUTPUT
\&    {
\&      my {
\&        subjects [
\&            [0] [
\&                [0] "Perl (Computer program language)"
\&            ]
\&            [1] [
\&                [0] "Web servers."
\&            ]
\&        ]
\&      }
\&    }
.Ve
.PP
See nested_array mapping rules at <https://github.com/LibreCat/Catmandu\-MARC/wiki/Mapping\-rules>.
.SS "join: Str"
.IX Subsection "join: Str"
If set, value of join will be used to join the referenced data content.
This will only have an effect if option split is undefined (not set or set to 0).
.PP
.Vb 3
\&    # INPUT
\&    [650," ",0,"a","Perl (Computer program language)"],
\&    [650," ",0,"a","Web servers."]
\&
\&    # CALL
\&    marc_spec(\*(Aq650\*(Aq, my.subjects, join:\*(Aq###\*(Aq)
\&
\&    # OUTPUT
\&    {
\&      my {
\&        subjects "Perl (Computer program language)###Web servers."
\&      }
\&    }
.Ve
.SS "pluck: 0|1"
.IX Subsection "pluck: 0|1"
This has only an effect on subfield values. By default subfield reference
happens in 'natural' order (first number 0 to 9 and then letters a to z).
.PP
.Vb 2
\&    # INPUT
\&    ["020"," ", " ","a","0491001304","q","black leather"]
\&
\&    # CALL
\&    marc_spec(\*(Aq020$q$a\*(Aq, my.isbn, split:1)
\&
\&    # OUTPUT
\&    {
\&      my {
\&        isbn [
\&            [0] 0491001304,
\&            [1] "black leather"
\&        ]
\&      }
\&    }
.Ve
.PP
If pluck is set to 1, values will be referenced by the order stated in the
MARCspec.
.PP
.Vb 2
\&    # INPUT
\&    ["020"," ", " ","a","0491001304","q","black leather"]
\&
\&    # CALL
\&    marc_spec(\*(Aq020$q$a\*(Aq, my.plucked.isbn, split:1, pluck:1)
\&
\&    # OUTPUT
\&    {
\&      my {
\&        isbn [
\&            [0] "black leather",
\&            [1] 0491001304
\&        ]
\&      }
\&    }
.Ve
.SS "value: Str"
.IX Subsection "value: Str"
If set to a value, this value will be assigned to \f(CW$var\fR if MARCspec references
data content (if the field or subfield exists).
.PP
In case two or more subfields are referenced, the value will be assigned to \f(CW$var\fR if
at least one of them exists:
.PP
.Vb 2
\&    # INPUT
\&    ["020"," ", " ","a","0491001304"]
\&
\&    # CALL
\&    marc_spec(\*(Aq020$a$q\*(Aq, my.isbn, value:\*(Aqone subfield exists\*(Aq)
\&
\&    # OUTPUT
\&    {
\&      my {
\&        isbn "one subfield exists"
\&      }
\&    }
.Ve
.SS "invert: 0|1"
.IX Subsection "invert: 0|1"
This has only an effect on subfields (values). If set to 1 it will invert the
last pattern for every subfield. E.g.
.PP
.Vb 2
\&   # references all subfields but not subfield a and q
\&   marc_spec(\*(Aq020$a$q\*(Aq my.other.subfields, invert:1)
\&
\&   # references all subfields but not subfield a and not the last repetition
\&   # of subfield q
\&   marc_spec(\*(Aq020$a$q[#]\*(Aq my.other.subfields, invert:1)
\&
\&   # references all but not the last two characters of first subfield a
\&   marc_spec(\*(Aq020$a[0]/#\-1\*(Aq my.other.subfields, invert:1)
.Ve
.PP
Invert will not work with subspecs.
.SH "INLINE"
.IX Header "INLINE"
This Fix can be used inline in a Perl script:
.PP
.Vb 1
\&    use Catmandu::Fix::marc_spec as => \*(Aqmarc_spec\*(Aq;
\&
\&    my $data = { record => [...] };
\&
\&    $data = marc_spec($data,\*(Aq245$a\*(Aq,\*(Aqtitle\*(Aq);
\&
\&    print $data\->{title} , "\en";
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Catmandu::Fix
Catmandu::Fix::marc_map
.SH "AUTHOR"
.IX Header "AUTHOR"
Carsten Klee <klee@cpan.org>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
Johann Rolschewski, \f(CW\*(C`<jorol at cpan>\*(C'\fR,
.IP "\(bu" 4
Patrick Hochstenbach, \f(CW\*(C`<patrick.hochstenbach at ugent.be>\*(C'\fR,
.IP "\(bu" 4
Nicolas Steenlant, \f(CW\*(C`<nicolas.steenlant at ugent.be>\*(C'\fR
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
MARCspec \- A common \s-1MARC\s0 record path language <http://marcspec.github.io/MARCspec/>
.IP "\(bu" 4
Catmandu <http://librecat.org/>
.IP "\(bu" 4
Catmandu Importers <http://librecat.org/Catmandu/#importers>
.IP "\(bu" 4
Catmandu Importers <http://librecat.org/Catmandu/#importers>
.IP "\(bu" 4
Catmandu Fixes <http://librecat.org/Catmandu/#fixes>
.IP "\(bu" 4
Catmandu::MARC::Fix::marc_map
.IP "\(bu" 4
Catmandu Paths <http://librecat.org/Catmandu/#paths>
.IP "\(bu" 4
Catmandu Wildcards <http://librecat.org/Catmandu/#wildcards>
.IP "\(bu" 4
MARC::Spec
.IP "\(bu" 4
Catmandu::Fix
.IP "\(bu" 4
Catmandu::MARC