MARC::...USMARC(3pm)

✨ MARC::...USMARC ✨

okay bestie, welcome to the User Contributed Perl Documentation for MARC::File::USMARC 💖 — this is your girl for all things USMARC-specific file handling, and she is lowkey iconic at it. no cap.

---

🌸 NAME 🌸

MARC::File::USMARC — the USMARC-specific file handling era 💅 she handles USMARC files, periodt.

---

🦋 SYNOPSIS 🦋

here's the vibe, fr fr:

use MARC::File::USMARC;

my $file = MARC::File::USMARC->in( $filename );

while ( my $marc = $file->next() ) {
    # Do something
}
$file->close();
undef $file;

so you crack open the file, you loop over every record, you do your lil thing, you close it, you let it go. main character energy honestly 🫶

---

🎀 EXPORT 🎀

None. bestie we export literally nothing, she's not that kind of module 💀

---

👑 METHODS 👑

🌈 decode( $string [, &filter_func ] )

this is the constructor for handling data from a USMARC file 📖✨ she takes care of ALL the tag directory parsing and mangling for you, which is honestly such a slay because that part is a nightmare.

any warnings or coercions? check them in the warnings() function, ok? don't forget 🫶

now about that $filter_func — it's an optional reference to a function you supply, and it decides, tag-by-tag, whether a tag gets put into the MARC record. she hands your function the tag number and the raw tag data, and your function has to return a boolean. return true and MARC::File::USMARC::decode goes "yes bestie, we're keeping this one" and puts the tag in the resulting MARC record. 💖

for example, if you ONLY want title and subject tags in your MARC record, do this:

sub filter {
    my ($tagno,$tagdata) = @_;

    return ($tagno == 245) || ($tagno >= 600 && $tagno <= 699);
}

my $marc = MARC::File::USMARC->decode( $string, \&filter );

and you might be like "girl why would I even do that" — valid question, and here's the tea 🍓: creating fields is processor-intensive. if your program is doing read-only data analysis and needs to be as fast as humanly possible, you can save time by just... not creating fields you were gonna ignore anyway. it's giving efficiency. it's giving self-care.

another possible use: if you only care about printing certain tags from the record, you can filter them right when you read from disc instead of deleting the unwanted tags yourself later. so much less work, so much more time for you 💅

---

⭐ update_leader()

if any changes get made to the MARC record, the first 5 bytes of the leader (that's the length) go invalid. rude, honestly. this function fixes that by updating the leader with the correct length of the record — the length it would have if it got written out to a file. ✨ problem solved, we move.

---

💜 _build_tag_directory()

for internal use only bestie, she's private, don't @ her 🙈 — this one builds the tag directory that gets put in front of the data in a MARC record.

she returns two array references and two lengths:

• the tag directory
• the data fields themselves
• the length of all data (and yes that includes the Leader that we expect will get added)
• the size of the Leader plus the tag directory

four things, all returned, all accounted for. organized queen 👑

---

🧚 encode()

returns a string of characters suitable for writing out to a USMARC file — including the leader, the directory, and ALL the fields. everything's in there. nothing's missing. she ate. 🔥

---

🌸 RELATED MODULES 🌸

MARC::Record 💖 (yes you should go read that one too, iykyk)

---

🔥 TODO 🔥

the wishlist, the vision board, the "we'll get to it":

• make some sort of autodispatch so you don't have to explicitly specify the MARC::File::X subclass — kind of like how DBI knows to use DBD::Oracle or DBD::Mysql. would be so convenient, honestly.
• create a toggle-able option to check inside the field data for end of field characters. presumably it'd be good to have it turned on all the time, but it's nice to be able to opt out if you don't want to take the performance hit. choices are a beautiful thing 🦋

---

📜 LICENSE 📜

this code may be distributed under the same terms as Perl itself.

and please note, for real for real: these modules are not products of, or supported by, the employers of the various contributors to the code. so don't come for anybody's boss, okay? 🙏

---

👑 AUTHOR 👑

Andy Lester, "<andy@petdance.com>" — legend behaviour 💖

---

and that's the whole page bestie!! 🎀

this was brought to you by perl v5.36.0, dated 2022-10-13, and the imminent MARC::...USMARC(3pm) — go read some records and slay 💅✨ iykyk 🫶