EBook:...Reader(3pm)

✨ NAME ✨

EBook::Tools::MSReader — bestie, this is the lil helper squad for working with Microsoft Reader (.lit) e-books 💖

---

🌸 SYNOPSIS 🌸

use EBook::Tools::MSReader qw(find_convertlit find_convertlit_keys
                              system_convertlit);
$EBook::Tools::MSReader::convertlit_cmd = '/opt/convertlit/clit';
$EBook::Tools::MSReader::convertlit_keys = '/opt/convertlit/keys.txt';

my $convertlit = find_convertlit();
my $keyfile = find_convertlit_keys();
system_convertlit(infile => 'myfile.lit',
                  dir => 'myfile-unpacked');

---

🎀 PROCEDURES 🎀

Okay so here's the tea: every single procedure is exportable, but none of them get exported by default. You gotta ask for them by name, no freeloaders 💅

🔍 find_convertlit()

This one goes on a lil scavenger hunt for the convertlit executable 🔎✨ It does that by running a test execution on the predicted locations (yes, including just checking PATH) and by peeking inside the EBook::Tools user configuration directory (see "userconfigdir()" in EBook::Tools).

It hands back the system command that got used for a successful invocation, or undef if literally nothing worked 😭

Heads up bestie: it uses the package variable $convertlit_cmd as its first guess, and then sets that variable to the return value too — so it remembers what it found 🫶

🔑 find_convertlit_keys($filename)

The key-hunting sibling 🗝️ It goes looking for the convertlit keys.txt file by checking the predicted filenames, in both the current working directory and the EBook::Tools user configuration directory (see "userconfigdir()" in EBook::Tools).

If you pass in $filename, then the file basename-keys.txt also gets checked in both of those locations.

Returns the name of the first file it finds, or undef if it came up empty 💀

Oh and same deal as before: it uses the package variable $convertlit_keys as its first guess, and sets that variable to the return value as well 💖

⚙️ system_convertlit(%args)

This is the main character 👑 It runs convertlit to extract or downconvert a MS Reader .lit file. Both find_convertlit() and find_convertlit_keys() get called up to locate the necessary helper files, because it does not do its own searching.

Returns the return value from convertlit — or undef if convertlit or the input file could not be found, or if neither output file nor directory is specified 🙈

📝 Arguments

• infile — the input filename. If it's not specified or it's invalid, this procedure croaks. Not a vibe. Specify it.
• outfile — the output filename. If you hand this one over, convertlit will do a downconversion.
• dir — the output directory. If this is specified and outfile is not, convertlit will do an extraction. And if you specify both this and outfile, convertlit downconverts and drops the downconverted file into the directory you named. Iconic, honestly 🌈
• keyfile — the location of the keys.txt file holding the encryption keys, if you've got it. This is only required when the .lit file is DRM-protected and the package variable $convertlit_keys doesn't already point at the correct file 🔐

---

💀 BUGS AND LIMITATIONS 💀

• All handling happens through ConvertLIT as an external helper. Native Perl code may eventually be written to handle non-DRMed extraction. (Someday, bestie, someday 🦋)
• Unit tests are unwritten 😭 (we know. we KNOW.)

---

👑 AUTHOR 👑

Zed Pobre <zed@debian.org>

---

📜 LICENSE AND COPYRIGHT 📜

Copyright 2008 Zed Pobre

Licensed to the public under the terms of the GNU GPL, version 2.

ConvertLIT (not included) is copyright 2002, 2003 Dan A. Jackson, and licensed under the terms of the GNU GPL, version 2 or later.

---

Okay that's the whole page, you ate it up, go unpack some e-books 🎀✨ This lil doc is from perl v5.40.0, dated 2025-01-10, and it's the EBook::Tools::MSReader(3pm) manual page — mwah, ily, bye 💜