File(3pm)

💖 File(3pm) — the Digest::MD5::File era 💖

okay bestie, sit down, hydrate, because we're about to talk about getting MD5 sums for files and urls in Perl and honestly? it's giving iconic. this is the File page from the User Contributed Perl Documentation, and I'm gonna walk you through every single crumb. no skips. 🫶

---

✨ NAME ✨

Digest::MD5::File — it's a Perl extension for getting MD5 sums for files and urls. that's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

here's the tea, literally all of it, verbatim:

use Digest::MD5::File qw(dir_md5_hex file_md5_hex url_md5_hex);

my $md5 = Digest::MD5->new;
$md5->addpath('/path/to/file');
my $digest = $md5->hexdigest;

my $digest = file_md5($file);
my $digest = file_md5_hex($file);
my $digest = file_md5_base64($file);

my $md5 = Digest::MD5->new;
$md5->addurl('http://www.tmbg.com/tour.html');
my $digest = $md5->hexdigest;

my $digest = url_md5($url);
my $digest = url_md5_hex($url);
my $digest = url_md5_base64($url);

my $md5 = Digest::MD5->new;
$md5->adddir('/directory');
my $digest = $md5->hexdigest;

my $dir_hashref = dir_md5($dir);
my $dir_hashref = dir_md5_hex($dir);
my $dir_hashref = dir_md5_base64($dir);

like. look at all those entry points. files, urls, whole directories, we do it all. 👑

---

🦋 DESCRIPTION 🦋

Get MD5 sums for files of a given path or content of a given url.

that's it. that's the mission. you hand it a path or a url, it hands you a digest. simple as. ✨

---

🎀 EXPORT 🎀

so by default? None. nothing gets exported, zero, nada, because we respect your namespace's boundaries. 🙈

but you can export any file_*, dir_*, or url_* function, plus anything Digest::MD5 can export. yes, really, mix and match, main character energy:

use Digest::MD5::File qw(md5 md5_hex md5_base64); # 3 Digest::MD5 functions
print md5_hex('abc123'), "\n";
print md5_base64('abc123'), "\n";

three whole Digest::MD5 functions, right there, no cap. 💜

---

💅 OBJECT METHODS 💅

💖 addpath() 💖

my $md5 = Digest::MD5->new;
$md5->addpath('/path/to/file.txt')
    or die "file.txt is not where you said: $!";

or — and this is the fun part — you can add multiple files by specifying an array ref of files:

$md5->addpath(\@files);

multiple files, one call, we love efficiency. 🔥

---

🧚 adddir() 🧚

it addpath()s each file in a directory recursively. and it follows the exact same rules as the dir_* functions (so go read that section, bestie, it matters).

my $md5 = Digest::MD5->new;
$md5->adddir('/home/tmbg/')
    or die "See warning above to see why I bailed: $!";

the die message is right there in the source and I refuse to paraphrase perfection. 😭

---

🌈 addurl() 🌈

my $md5 = Digest::MD5->new;
$md5->addurl('http://www.tmbg.com/tour.html')
    or die "They Must Be not on tour";

"They Must Be not on tour" — the manpage author was having a whole moment and honestly? respect. 🎸

---

🌸 file_* functions 🌸

Get the digest in variouse formats of $file. (yes, "variouse", I'm keeping the typo, it's canon now, it's part of the lore.)

and here's the important warning: if the file does not exist or is a directory, it croaks. you heard me. croaks. (see NOFATALS for more info on how to avoid that little death 💀)

my $digest = file_md5($file) or warn "$file failed: $!";
my $digest = file_md5_hex($file) or warn "$file failed: $!";
my $digest = file_md5_base64($file) or warn "$file failed: $!";

three formats, one file, pick your fave. ✨

---

🍓 dir_* functions 🍓

this one returns a hashref where:

• the keys are files relative to the given path
• the values are the MD5 sum of the file, or an empty string if it's a directory

it recurses through the entire depth of the directory. all of it. every last level. no stone unturned, bestie. 🦋

and symlinks? symlinks to files are just addpath()d, and symlinks to directories are followed. (not me warning you that following symlinked dirs can get you places 👀 — no wait, that's a claim I can't make, scratch that, the manpage just says they're followed, so: they're followed. periodt.)

my $dir_hashref = dir_md5($dir) or warn "$dir failed: $!";
my $dir_hashref = dir_md5_hex($dir) or warn "$dir failed: $!";
my $dir_hashref = dir_md5_base64($dir) or warn "$dir failed: $!";

---

💜 url_* functions 💜

Get the digest in various formats of the content at $url — and yes, that includes, if $url points to a directory, the directory listing content. iconique. 🎀

it returns undef if the url fails — i.e. if LWP::UserAgent's $res->is_success is false. so check your return values, bestie, please. 🙏

my $digest = url_md5($url) or warn "$url failed";
my $digest = url_md5_hex($url) or warn "$url failed";
my $digest = url_md5_base64($url) or warn "$url failed";

---

⭐ SPECIAL SETTINGS ⭐

🌟 BINMODE 🌟

by default, files are opened in binmode. but if that's not the vibe for you, you can unset it in a whole bunch of ways:

use Digest::MD5::File qw(-nobin);

or

$Digest::MD5::File::BINMODE = 0;

or at the function/method level by specifying its value as the second argument:

$md5->addpath($file,0);

my $digest = file_md5_hex($file,0);

three ways to say "not today, binmode". 💅

---

🌈 UTF8 🌈

in some cases you may want to have your data utf8 encoded. completely valid. here's how:

use Digest::MD5::File qw(-utf8);

or

$Digest::MD5::File::UTF8 = 1;

or at the function/method level — by specifying its value as the third argument for files and the second for urls:

$md5->addpath($file,$binmode,1);

my $digest = file_md5_hex($file,$binmode,1);

$md5->addurl($url,1);

url_md5_hex($url,1);

heads up bestie: it use's Encode's encode_utf8() function to do the encoding. so if you do not have Encode (pre 5.7.3) this won't work :) — the smiley is theirs, I'm just the messenger. 😭

---

💀 NOFATALS 💀

instead of croaking, it will return undef if you set NOFATALS to true. soft launch your errors instead of a full dramatic exit.

two ways to do it:

$Digest::MD5::File::NOFATALS = 1;

or the -nofatals flag:

use Digest::MD5::File qw(-nofatals);

my $digest = file_md5_hex($file) or die "$file failed";

real talk: $! is <strong>not set</strong> in this mode, so it's not really helpful if you die(). you'll get a message with no clue attached. so... know that going in. 🙈

---

🫶 SEE ALSO 🫶

Digest::MD5, Encode, LWP::UserAgent

(the holy trinity of "where the actual work happens") ✨

---

👑 AUTHOR 👑

Daniel Muey, <http://drmuey.com/cpan_contact.pl>

---

💖 COPYRIGHT AND LICENSE 💖

Copyright 2005 by Daniel Muey

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie, every last crumb of it. 🍓

perl v5.32.0 · 2021-01-01 · and it lives under File(3pm) in the User Contributed Perl Documentation. mwah. 💋 go hash something. 🦋✨