.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "MARC::File::XML 3pm"
.TH MARC::File::XML 3pm "2022-01-20" "perl v5.32.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"
MARC::File::XML \- Work with MARC data encoded as XML
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    ## Loading with USE options
\&    use MARC::File::XML ( BinaryEncoding => \*(Aqutf8\*(Aq, RecordFormat => \*(AqUNIMARC\*(Aq );
\&
\&    ## Setting the record format without USE options
\&    MARC::File::XML\->default_record_format(\*(AqUSMARC\*(Aq);
\&    
\&    ## reading with MARC::Batch
\&    my $batch = MARC::Batch\->new( \*(AqXML\*(Aq, $filename );
\&    my $record = $batch\->next();
\&
\&    ## or reading with MARC::File::XML explicitly
\&    my $file = MARC::File::XML\->in( $filename );
\&    my $record = $file\->next();
\&
\&    ## serialize a single MARC::Record object as XML
\&    print $record\->as_xml();
\&
\&    ## write a bunch of records to a file
\&    my $file = MARC::File::XML\->out( \*(Aqmyfile.xml\*(Aq );
\&    $file\->write( $record1 );
\&    $file\->write( $record2 );
\&    $file\->write( $record3 );
\&    $file\->close();
\&
\&    ## instead of writing to disk, get the xml directly 
\&    my $xml = join( "\en", 
\&        MARC::File::XML::header(),
\&        MARC::File::XML::record( $record1 ),
\&        MARC::File::XML::record( $record2 ),
\&        MARC::File::XML::footer()
\&    );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The MARC-XML distribution is an extension to the MARC-Record distribution for 
working with \s-1MARC21\s0 data that is encoded as \s-1XML.\s0 The \s-1XML\s0 encoding used is the
MARC21slim schema supplied by the Library of Congress. More information may 
be obtained here: http://www.loc.gov/standards/marcxml/
.PP
You must have MARC::Record installed to use MARC::File::XML. In fact 
once you install the MARC-XML distribution you will most likely not use it 
directly, but will have an additional file format available to you when you
use MARC::Batch.
.PP
This version of MARC-XML supersedes an the versions ending with 0.25 which 
were used with the \s-1MARC\s0.pm framework. MARC-XML now uses MARC::Record 
exclusively.
.PP
If you have any questions or would like to contribute to this module please
sign on to the perl4lib list. More information about perl4lib is available
at <http://perl4lib.perl.org>.
.SH "METHODS"
.IX Header "METHODS"
When you use MARC::File::XML your MARC::Record objects will have two new
additional methods available to them:
.SS "MARC::File::XML\->default_record_format([$format])"
.IX Subsection "MARC::File::XML->default_record_format([$format])"
Sets or returns the default record format used by MARC::File::XML.  Valid
formats are \fB\s-1MARC21\s0\fR, \fB\s-1USMARC\s0\fR, \fB\s-1UNIMARC\s0\fR and \fB\s-1UNIMARCAUTH\s0\fR.
.PP
.Vb 1
\&    MARC::File::XML\->default_record_format(\*(AqUNIMARC\*(Aq);
.Ve
.SS "\fBas_xml()\fP"
.IX Subsection "as_xml()"
Returns a MARC::Record object serialized in \s-1XML.\s0 You can pass an optional format
parameter to tell MARC::File::XML what type of record (\s-1USMARC, UNIMARC, UNIMARCAUTH\s0) you are
serializing.
.PP
.Vb 1
\&    print $record\->as_xml([$format]);
.Ve
.SS "as_xml_record([$format])"
.IX Subsection "as_xml_record([$format])"
Returns a MARC::Record object serialized in \s-1XML\s0 without a collection wrapper.
You can pass an optional format parameter to tell MARC::File::XML what type of
record (\s-1USMARC, UNIMARC, UNIMARCAUTH\s0) you are serializing.
.PP
.Vb 1
\&    print $record\->as_xml_record(\*(AqUNIMARC\*(Aq);
.Ve
.ie n .SS "new_from_xml([$encoding, $format])"
.el .SS "new_from_xml([$encoding, \f(CW$format\fP])"
.IX Subsection "new_from_xml([$encoding, $format])"
If you have a chunk of \s-1XML\s0 and you want a record object for it you can use 
this method to generate a MARC::Record object.  You can pass an optional
encoding parameter to specify which encoding (\s-1UTF\-8\s0 or \s-1MARC\-8\s0) you would like
the resulting record to be in.  You can also pass a format parameter to specify
the source record type, such as \s-1UNIMARC, UNIMARCAUTH, USMARC\s0 or \s-1MARC21.\s0
.PP
.Vb 1
\&    my $record = MARC::Record\->new_from_xml( $xml, $encoding, $format );
.Ve
.PP
Note: only works for single record \s-1XML\s0 chunks.
.PP
If you want to write records as \s-1XML\s0 to a file you can use \fBout()\fR with \fBwrite()\fR
to serialize more than one record as \s-1XML.\s0
.SS "\fBout()\fP"
.IX Subsection "out()"
A constructor for creating a MARC::File::XML object that can write \s-1XML\s0 to a
file. You must pass in the name of a file to write \s-1XML\s0 to.  If the \f(CW$encoding\fR
parameter or the DefaultEncoding (see above) is set to \s-1UTF\-8\s0 then the binmode
of the output file will be set appropriately.
.PP
.Vb 1
\&    my $file = MARC::File::XML\->out( $filename [, $encoding] );
.Ve
.SS "\fBwrite()\fP"
.IX Subsection "write()"
Used in tandem with \fBout()\fR to write records to a file.
.PP
.Vb 3
\&    my $file = MARC::File::XML\->out( $filename );
\&    $file\->write( $record1 );
\&    $file\->write( $record2 );
.Ve
.SS "\fBclose()\fP"
.IX Subsection "close()"
When writing records to disk the filehandle is automatically closed when you
the MARC::File::XML object goes out of scope. If you want to close it explicitly
use the \fBclose()\fR method.
.PP
If you want to generate batches of records as \s-1XML,\s0 but don't want to write to
disk you'll have to use \fBheader()\fR, \fBrecord()\fR and \fBfooter()\fR to generate the
different portions.
.PP
.Vb 7
\&    $xml = join( "\en",
\&        MARC::File::XML::header(),
\&        MARC::File::XML::record( $record1 ),
\&        MARC::File::XML::record( $record2 ),
\&        MARC::File::XML::record( $record3 ),
\&        MARC::File::XML::footer()
\&    );
.Ve
.SS "\fBheader()\fP"
.IX Subsection "header()"
Returns a string of \s-1XML\s0 to use as the header to your \s-1XML\s0 file.
.SS "\fBfooter()\fP"
.IX Subsection "footer()"
Returns a string of \s-1XML\s0 to use at the end of your \s-1XML\s0 file.
.SS "\fBrecord()\fP"
.IX Subsection "record()"
Returns a chunk of \s-1XML\s0 suitable for placement between the header and the footer.
.SS "\fBdecode()\fP"
.IX Subsection "decode()"
You probably don't ever want to call this method directly. If you do 
you should pass in a chunk of \s-1XML\s0 as the argument.
.PP
It is normally invoked by a call to \fBnext()\fR, see MARC::Batch or MARC::File.
.SS "MARC::File::XML\->set_parser($parser)"
.IX Subsection "MARC::File::XML->set_parser($parser)"
Pass a XML::LibXML parser to MARC::File::XML
for it to use.  This is optional, meant for
use by applications that maintain a shared
parser object or which require that external
entities be processed.  Note that the latter
is a potential security risk; see
<https://www.owasp.org/index.php/XML_External_Entity_(\s-1XXE\s0)_Processing>.
.SS "\fBencode()\fP"
.IX Subsection "encode()"
You probably want to use the \fBas_xml()\fR method on your MARC::Record object
instead of calling this directly. But if you want to you just need to 
pass in the MARC::Record object you wish to encode as \s-1XML,\s0 and you will be
returned the \s-1XML\s0 as a scalar.
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
Support for callback filters in \fBdecode()\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "<http://www.loc.gov/standards/marcxml/>" 4
.IX Item "<http://www.loc.gov/standards/marcxml/>"
.PD 0
.IP "MARC::File::USMARC" 4
.IX Item "MARC::File::USMARC"
.IP "MARC::Batch" 4
.IX Item "MARC::Batch"
.IP "MARC::Record" 4
.IX Item "MARC::Record"
.PD
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Ed Summers <ehs@pobox.com>