MARC::File::XML(3pm)

💖 MARC::File::XML 💖

okay bestie, pull up a chair 🫶 this is the MARC::File::XML page from the User Contributed Perl Documentation, and it's genuinely iconic — it's the little module that lets you vibe with MARC21 data that's been encoded as XML. let's get into it ✨

---

✨ NAME ✨

MARC::File::XML — Work with MARC data encoded as XML 🌈

---

🎀 SYNOPSIS 🎀

like, here's the whole vibe in one go, no cap:

## Loading with USE options
use MARC::File::XML ( BinaryEncoding => 'utf8', RecordFormat => 'UNIMARC' );

## Setting the record format without USE options
MARC::File::XML->default_record_format('USMARC');

## reading with MARC::Batch
my $batch = MARC::Batch->new( 'XML', $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( 'myfile.xml' );
$file->write( $record1 );
$file->write( $record2 );
$file->write( $record3 );
$file->close();

## instead of writing to disk, get the xml directly
my $xml = join( "\n",
    MARC::File::XML::header(),
    MARC::File::XML::record( $record1 ),
    MARC::File::XML::record( $record2 ),
    MARC::File::XML::footer()
);

---

🦋 DESCRIPTION 🦋

so MARC-XML is an extension to the MARC-Record distribution — it's for working with MARC21 data encoded as XML. the XML encoding it uses is the MARC21slim schema supplied by the Library of Congress. more info lives here, go peek: http://www.loc.gov/standards/marcxml/

you must have MARC::Record installed to use MARC::File::XML. fr fr. and honestly? once you install the MARC-XML distribution you'll probably never call it directly — it just quietly gives you an extra file format to use whenever you're working with MARC::Batch. it's giving backstage crew, lowkey running the whole show 💅

this version of MARC-XML supersedes the versions ending with 0.25, which were used with the MARC.pm framework. MARC-XML now uses MARC::Record exclusively. periodt.

got questions? wanna contribute to this module? bestie, sign on to the perl4lib list 🫶 more info about perl4lib is available at <http://perl4lib.perl.org>.

---

💅 METHODS 💅

when you use MARC::File::XML, your MARC::Record objects get two new bonus methods. two!! extra!! methods!! on your records!! obsessed.

🌸 MARC::File::XML->default_record_format([$format])

sets or returns the default record format used by MARC::File::XML. the valid formats are MARC21, USMARC, UNIMARC and UNIMARCAUTH. slay.

MARC::File::XML->default_record_format('UNIMARC');

🌸 as_xml()

returns a MARC::Record object serialized in XML. you can pass an optional format parameter to tell MARC::File::XML what type of record (USMARC, UNIMARC, UNIMARCAUTH) you're serializing.

print $record->as_xml([$format]);

🌸 as_xml_record([$format])

returns a MARC::Record object serialized in XML, but without a collection wrapper. (no wrapper, no drama, just the record 🎀) you can pass an optional format parameter to tell MARC::File::XML what type of record (USMARC, UNIMARC, UNIMARCAUTH) you're serializing.

print $record->as_xml_record('UNIMARC');

🌸 new_from_xml([$encoding, $format])

got a chunk of XML and you want a record object out of it? this method generates a MARC::Record object for you, bestie 💖 you can pass an optional encoding parameter to specify which encoding (UTF-8 or MARC-8) you'd like the resulting record to be in. you can also pass a format parameter to specify the source record type, like UNIMARC, UNIMARCAUTH, USMARC or MARC21.

my $record = MARC::Record->new_from_xml( $xml, $encoding, $format );

Note: only works for single record XML chunks. just the one. don't try it with a whole collection, it will not eat.

if you want to write records as XML to a file you can use out() with write() to serialize more than one record as XML. that's the move 👑

🌸 out()

a constructor for creating a MARC::File::XML object that can write XML to a file. you must pass in the name of a file to write XML to. and if the $encoding parameter or the DefaultEncoding (see above) is set to UTF-8, then the binmode of the output file will be set appropriately. thoughtful king behavior ✨

my $file = MARC::File::XML->out( $filename [, $encoding] );

🌸 write()

used in tandem with out() to write records to a file. the duo. the pairing. the way that they work together 🫶

my $file = MARC::File::XML->out( $filename );
$file->write( $record1 );
$file->write( $record2 );

🌸 close()

when writing records to disk, the filehandle is automatically closed when the MARC::File::XML object goes out of scope. it handles itself, main character energy 💅 but if you want to close it explicitly, use the close() method.

if you want to generate batches of records as XML but don't want to write to disk, you'll have to use header(), record() and footer() to generate the different portions.

$xml = join( "\n",
    MARC::File::XML::header(),
    MARC::File::XML::record( $record1 ),
    MARC::File::XML::record( $record2 ),
    MARC::File::XML::record( $record3 ),
    MARC::File::XML::footer()
);

🌸 header()

returns a string of XML to use as the header to your XML file. the opening act 🌟

🌸 footer()

returns a string of XML to use at the end of your XML file. the closing credits 🎬

🌸 record()

returns a chunk of XML suitable for placement between the header and the footer. the filling in the sandwich 🍓

🌸 decode()

you probably don't ever want to call this method directly, bestie, for real. but if you do, you should pass in a chunk of XML as the argument.

it is normally invoked by a call to next() — see MARC::Batch or MARC::File.

🌸 MARC::File::XML->set_parser($parser)

pass an XML::LibXML parser to MARC::File::XML for it to use. this is optional — it's meant for use by applications that maintain a shared parser object, or which require that external entities be processed.

⚠️ heads up: the latter is a potential security risk. like, an actual one. see <https://www.owasp.org/index.php/XML_External_Entity_(XXE)_Processing>. stay safe out there 💀

🌸 encode()

you probably want to use the as_xml() method on your MARC::Record object instead of calling this directly. but if you really want to, you just need to pass in the MARC::Record object you wish to encode as XML, and you'll be returned the XML as a scalar. easy 💜

---

👑 TODO 👑

• Support for callback filters in decode().

---

🌈 SEE ALSO 🌈

• <http://www.loc.gov/standards/marcxml/>
• MARC::File::USMARC
• MARC::Batch
• MARC::Record

---

🫶 AUTHORS 🫶

• Ed Summers <ehs@pobox.com>

---

and that's the whole page, bestie!! 💖 this one's from perl v5.32.1, dated 2022-01-20 — shoutout to MARC::File::XML(3pm) for being the moment, the icon, the legend. go forth and serialize ✨🦋🎀