MARC::Batch(3pm)

💖 NAME 💖

MARC::Batch — bestie, this is a Perl module for handling whole files of MARC::Record objects ✨

(and yes, it's the MARC::Batch(3pm) page from User Contributed Perl Documentation, we're all friends here 🫶)

---

🌸 SYNOPSIS 🌸

okay so real talk: MARC::Batch hides literally ALL the file handling for files full of MARC::Records. MARC::Record is still the one doing the actual file I/O, but MARC::Batch is the one juggling the multiple-file drama 💅

use MARC::Batch;

# If you have weird control fields...
use MARC::Field;
MARC::Field->allow_controlfield_tags('FMT', 'LDX');

my $batch = MARC::Batch->new( 'USMARC', @files );
while ( my $marc = $batch->next ) {
    print $marc->subfield(245,"a"), "\n";
}

---

🎀 EXPORT 🎀

None. Periodt. Everything in here is a class method 🫶

---

🔥 METHODS 🔥

💫 new( $type, @files )

Makes you a MARC::Batch object that's gonna process @files 🦋

$type has to be either "USMARC" or "MicroLIF". And if you'd rather say "MARC::File::USMARC" or "MARC::File::MicroLIF", that's totally fine too, no cap. new() hands you back a new MARC::Batch object ✨

@files can just be a list of filenames:

my $batch = MARC::Batch->new( 'USMARC', 'file1.marc', 'file2.marc' );

But your @files can ALSO hold filehandles 👀 so if you've got a big file that's gzipped, you can open a pipe to gzip and pass that in:

my $fh = IO::File->new( 'gunzip -c marc.dat.gz |' );
my $batch = MARC::Batch->new( 'USMARC', $fh );

And bestie you can mix and match if you rly really want to:

my $batch = MARC::Batch->new( 'USMARC', $fh, 'file1.marc' );

💫 next()

Reads the next record out of that batch and gives it back to you as a MARC::Record object 💖 If the current file is at EOF, it closes it and opens the next one. next() returns undef when there's no more data to be read from any of the batch files.

By default, next() ALSO returns undef if it runs into an error while reading from the batch 😭 and if you don't check for that, your iteration can terminate prematurely — it's giving silent betrayal, fr fr. To change that behavior, go look at strict_off(). You can grab the warning messages with the warnings() method.

Optionally you can pass in a filter function as a subroutine reference if you're only interested in particular fields from the record 👑 This can boost performance. Slay.

💫 strict_off()

If you want MARC::Batch to keep going after it's encountered what it believes is bad MARC data, call this method and strict goes OFF 🙈 A call to strict_off() always returns true (1).

strict_off() is lowkey handy when you don't care about the quality of your MARC data and you just want to plow through it. But for safety: MARC::Batch strict is ON by default, no exceptions 💀

💫 strict_on()

Literally the opposite of strict_off(), and the default state. You shouldn't have to use this method unless you've previously used strict_off() and want it back on again. When strict is ON, calls to next() will return undef when an error is encountered while reading MARC data. strict_on() always returns true (1).

💫 warnings()

Returns a list of warnings that have accumulated while processing a particular batch file. Side effect alert 🚨 the warning buffer will be cleared.

my @warnings = $batch->warnings();

This method is also used internally to set warnings, so you probably don't want to be passing in anything, bc that will set warnings on your batch object 😬

warnings() will return the empty list when there are no warnings 🫶

💫 warnings_off()

Turns off the default behavior of printing warnings to STDERR. However, even with warnings off the messages can still be retrieved using the warnings() method if you wish to check for them 👀

warnings_off() always returns true (1).

💫 warnings_on()

Turns on warnings so that diagnostic information is printed to STDERR 📢 This is on by default so you shouldn't have to use it unless you've previously turned off warnings using warnings_off().

warnings_on() always returns true (1).

💫 filename()

Returns the currently open filename, or undef if there is not currently a file open on this batch object 🌸

---

🌈 RELATED MODULES 🌈

MARC::Record, MARC::Lint

---

⭐ TODO ⭐

None yet. Send me your ideas and needs, bestie — I'm listening 💌

---

💜 LICENSE 💜

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

Please note that these modules are not products of or supported by the employers of the various contributors to the code.

---

👑 AUTHOR 👑

Andy Lester, "<andy@petdance.com>"

---

and that's the whole page, we ate and left no crumbs 💅 this was MARC::Batch(3pm), written up back in 2022-10-13, shipping with perl v5.36.0 — bye bestie, go read some MARC records 🦋💖