MODS::Record(3pm)

📦
version 0.14 · 4 versions
, in ubuntu stonking

💖 MODS::Record — the manual, but make it slay 💖

okay bestie, gather round, because we're talking about MODS::Record — a Perl extension for handling MODS records. yes, the Perl thing. no, it's not scary. she's actually iconic. 🎀

✨ NAME ✨

MODS::Record — Perl extension for handling MODS records. that's it. that's the name. short, sweet, does what it says on the tin. 💅

🌸 SYNOPSIS 🌸

here's the vibe check — everything you can do, all in one place:

use MODS::Record qw(xml_string);
use open qw(:utf8);

my $mods = MODS::Record->new;

my $collection = MODS::Collection->new;

my $mods = $collection->add_mods(ID => '1234');

$mods->add_abstract("Hello", lang => 'eng');
$mods->add_abstract("Bonjour", lang => 'fra');

# Set a deeply nested field...
$mods->add_language()->add_languageTerm('eng');

# Set a list of deeply nested fields...
$mods->add_location(sub {
   $_[0]->add_physicalLocation('here');
   $_[0]->add_shelfLocator('here too');
   $_[0]->add_url('http://here.org/there');
});

# Set an inline XML extension...
$mods->add_accessCondition(xml_string("<x:foo><x:bar>21212</x:bar></x:foo>"));

# Retrieve a field by a filter...
$mods->get_abstract(lang => 'fra')->body("Bonjour :)");
$mods->get_abstract(lang => 'fra')->contentType('text/plain');

for ($mods->get_abstract(lang => 'fra')) {
   printf "%s\n" , $_->body;
}

# Set a field to a new value
my @newabstract;
for ($mods->get_abstract) {
   push @newabstract, $_ unless $_->lang eq 'fra';
}
$mods->set_abstract(@newabstract);

# Clear all abstracts;
$mods->set_abstract(undef);

# Serialize
print $mods->as_json(pretty => 1);
print $mods->as_xml;

# Deserialize
my $mods = MODS::Record->from_xml(IO::File->new('mods.xml'));
my $mods = MODS::Record->from_json(IO::File->new('mods.js'));

my $count = MODS::Record->from_xml(IO::File->new('mods.xml'), sub {
   my $mods = shift;
   ...
});

my $count = MODS::Record->from_json(IO::File->new('mods.js'), sub {
   my $mods = shift;
   ...
});

like. look at her go. 😭 she's doing SO much and she's doing it effortlessly.

🦋 DESCRIPTION 🦋

so what is this? this module provides MODS parsing and creation for MODS Schema 3.5. the MODS spec lives at http://www.loc.gov/standards/mods/ if you wanna go read the source material, bestie. 📚

👑 METHODS 👑

MODS::Record->new(%attribs)

MODS::Collection->new(%attribs)

create a brand new MODS record or collection. she's fresh, she's new, she's ready. ✨

optionally you can pass attributes as defined by the MODS specification. e.g.

$mods = MODS::Record->new(ID='123');

add_xxx()

add a new element to the record where xxx is the name of a MODS element (e.g. titleInfo, name, genre, etc). this method returns an instance of the added MODS element. e.g.

$titleInfo = $mods->add_titleInfo; # $titleInfo is a 'MODS::Element::TitleInfo'

add_xxx($text,%attribs)

add a new element to the record where xxx is the name of a MODS element. set the text content of the element to $text and optionally provide further attributes. this method returns an instance of the added MODS element. e.g.

$mods->add_abstract("My abstract", lang=>'eng');

add_xxx(sub { })

add a new element to the record where xxx is the name of a MODS element. the provided coderef gets as input an instance of the added MODS element. this method returns an instance of the added MODS element. e.g.

$mods->add_abstract(sub {
   my $o = shift;
   $o->body("My abstract");
   $o->lang("eng");
})

add_xxx($obj)

add a new element to the record where xxx is the name of a MODS element. the $obj is an instance of a MODS::Element::Xxx class (where Xxx is the corresponding MODS element). this method returns an instance of the added MODS element. e.g.

$mods->add_abstract(
    MODS::Element::Abstract->new(_body=>'My abstract', lang=>'eng')
);

get_xxx()

get_xxx(%filter)

get_xxx(sub { })

retrieve an element from the record where xxx is the name of a MODS element. these methods return in array context all the matching elements — yes, all of them, the whole squad — or the first match in scalar context. optionally provide a %filter or a coderef filter function. e.g.

@titles = $mods->get_titleInfo();
$alt    = $mods->get_titleInfo(type=>'alternate');
$alt    = $mods->get_titleInfo(sub { shift->type eq 'alternate'});

set_xxxx()

set_xxx(undef)

set_xxx($array_ref)

set_xxx($xxx1,$xxx2,...)

set an element of the record to a new value where xxx is the name of a MODS element.

  • when no arguments are provided, then this is a null operation — literally nothing happens, she's just standing there, existing. 🧍
  • when undef als argument is provided, then the element is deleted. gone. poof. 💀
  • to overwrite the existing content of the element an ARRAY (ref) of MODS::Element::Xxx can be provided (where Xxx is the corresponding MODS element).

e.g.

# Delete all abstracts
$mods->set_abstract(undef);

# Set all abstracts
$mods->set_abstract(MODS::Element::Abstract->new(), MODS::Element::Abstract->new(), ...);
$mods->set_abstract([ MODS::Element::Abstract->new(), MODS::Element::Abstract->new(), ... ]);

as_xml()

as_xml(xml_prolog=>1)

return the record as XML. that's the whole thing. she said what she said. 🎀

from_xml($string [, $callback])

from_xml(IO::Handle [, $callback])

parse an XML string or IO::Handle into a MODS::Record. this method return the parsed JSON. 👀 (yes, that's what the docs say, bestie, i'm just the messenger 🫶)

if a callback function is provided then for each MODS element in the XML stream the callback will be called. the method returns the number of parsed MODS elements.

e.g.

my $mods = MODS::Record->from_xml( IO::File->new(...) );

my $count = MODS::Record->from_xml( IO::File->new(...) , sub {
    my $mods = shift;
} );

as_json()

as_json(pretty=>1)

return the record as a JSON string. pretty => 1 means she's dressed up for the occasion. ✨

from_json($string [, $callback])

from_json(IO::Handle [, $callback])

parse and JSON string or JSON::Handle into a MODS::Record. this method return the parsed JSON.

if a callback function is provided then we expect as input a stream of JSON strings (each line one JSON string). for each MODS object in the JSON stream the callback will be called. the method returns the number of parsed strings.

e.g.

my $mods = MODS::Record->from_json( IO::File->new(...) );

my $count = MODS::Record->from_json( IO::File->new(...) , sub {
    my $mods = shift;
} );

🌈 SEE ALSO 🌈

💅 DESIGN NOTES 💅

okay so here's the ~behind the scenes~ tea, straight from the author's own keyboard. not me being honest about my own limits, we love a self-aware icon:

  • I'm not a MODS expert
  • I needed a MODS module to parse and create MODS records for our institutional repository
  • This module is part of the LibreCat/Catmandu project http://librecat.org
  • This module is not created for speed
  • This module doesn't have any notion of ordering of MODS elements themselves (e.g. first titleInfo, then name). But each sub-element keeps its original order (e.g. each title in titleInfo).
  • Heiko Jansen provides at GitHub a Moose-based MODS parser https://github.com/heikojansen/MODS--Record
fr fr bestie, that ordering note matters — she keeps the inner order but she does NOT police the outer one. don't come for her about it. 😌

🧚 AUTHOR 🧚

Patrick Hochstenbach <Patrick.Hochstenbach at UGent.be>

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

and that's the whole page, bestie!! 🫶 this little doc shipped as part of perl v5.40.1 back on 2026-02-20 — so yeah, she's been out here slaying in the wild since then. go write some MODS records, you've got this. 🦋💖⭐

📦 where this page comes from