EBook:...PalmDoc(3pm)

✨ EBook::Tools::PalmDoc ✨ (that's PalmDoc(3pm) bestie, from the User Contributed Perl Documentation section 💖)

okay so. hi. welcome to the PalmDoc glow-up era 🌸

---

💖 NAME 💖

EBook::Tools::PalmDoc — a Palm::PDB handler for manipulating the PalmDoc/PilotDoc/AportisDoc format. yes she handles all three names, she's versatile like that 💅

---

🦋 SYNOPSIS 🦋

use EBook::Tools::PalmDoc qw(uncompress_palmdoc);
use Palm::PDB;

my $pdb = Palm::PDB->new();

or

use EBook::Tools::PalmDoc qw(:all);

my $pdb = EBook::Tools::PalmDoc->new();
$pdb->set_text($text);
$pdb->Write('textfile.pdb');

my $pdb2 = EBook::Tools::PalmDoc->new();
$pdb2->{attributes}{resource} = 1;
$pdb->import_textfile('textfile.txt');
$pdb->Write('textfile.prc');

like literally two whole ways to do the thing, choose your own adventure ✨

---

🌈 DESCRIPTION 🌈

This module contains a Palm::PDB handler (subclassed from Palm::Raw) and some associated general procedures for dealing with PalmDoc books. She handles PalmDoc and only PalmDoc, ok? No cap. For Mobipocket, eReader, or other .pdb/.prc formats, go see the module specific to that format — this is not her era 🙈

---

🎀 CONSTRUCTOR 🎀

🌟 new() 🌟

Instantiates a new Ebook::Tools::PalmDoc object. To create a Palm Resource file instead of a Palm Database file, set $self->{attributes}{resource} to be true immediately after construction. iykyk.

Create a new Doc object. By default, it's not a resource database. Setting $self->{attributes}{resource} to 1 before any manipulations will cause it to become a resource database. timing is everything bestie 💅

---

🫶 ACCESSOR METHODS 🫶

🎀 bookmarks() 🎀

Returns a hash of bookmarks, where the keys are the bookmark offsets and the values are the bookmark names. cute little offset-to-name moment 💖

🎀 text() 🎀

Returns the text of the file. the actual words. iconic.

🎀 html() 🎀

Returns the text of the file converted to HTML via HTML::TextToHTML. glow-up achieved ✨

---

💅 MODIFIER METHODS 💅

These methods have two naming/capitalization schemes — methods directly related to the subclassing of Palm::PDB use its MethodName capitalization style. Any other methods are lowercase_with_underscores for consistency with the rest of EBook::Tools. two aesthetics, one module, we contain multitudes 🦋

🌸 ParseRecord(%record) 🌸

Parses PDB records, updating the object attributes. This method is called automatically on every database record (in .pdb files) during Load(). she does it herself, you don't gotta ask 💅

🌸 ParseResource(%resource) 🌸

Parses PDB resources, updating object attributes. This is called automatically on every database resource (in .prc files) during Load().

🌸 ParseRecordBookmark($data,$currentrecord) 🌸

Parses bookmark records/resources, updating object attributes, most notably $self->{bookmarks}.

The $currentrecord argument is optional, but without it the debugging information may be less useful. (not me skipping an optional arg and then crying over vague debug output 😭). This is called automatically by ParseRecord() and ParseResource() as needed.

🌸 ParseRecordText($data) 🌸

Parses text records, updating object attributes, most notably appending text to $self->{text}.

This is called automatically by ParseRecord() and ParseResource() as needed.

🌸 set_text(@text) 🌸

Uses the contents of @text (concatenated) as the text of the PDB. all of it, mashed together, one vibe ✨

🌸 import_textfile($filename) 🌸

Set the contents of the Doc to the contents of the file and sets the name of the PDB to the basename of the file. file in, name out, slay 💖

---

⭐ PROCEDURES ⭐

All procedures are exportable, but none are exported by default. you gotta ask for them, they're not just gonna show up uninvited 🫶

💜 compress_palmdoc($text) 💜

Compresses input text using the simplified Lempel-Ziv 77 encoding used by PalmDoc and some other formats and returns the compressed string.

See uncompress_palmdoc() for more details on the algorithm.

This procedure was taken from Palm::Doc with some minor changes. a little heritage moment 🎀

💜 parse_palmdoc_header($data) 💜

Takes as an argument a scalar containing the 16 bytes of the PalmDoc header (also used by Mobipocket). Returns a hashref containing those values keyed to recognizable names.

See:

http://wiki.mobileread.com/wiki/DOC#PalmDOC

and

http://wiki.mobileread.com/wiki/MOBI

🌈 keys 🌈

The returned hashref will have the following keys:

• compression

Possible values:

1 - no compression
2 - PalmDoc compression
128 - iSilo3?
17480 (the characters 'DH') - Mobipocket 'Dictionary Huffman'
compression (aka HuffDic aka Huff/CDIC)

A warning will be carped if an unknown value is found. (she will tell you, loudly, in warning form 🗣️)

• textlength

Uncompressed length of book text in bytes

• textrecords

Number of PDB records used for book text

• recordsize

Maximum size of each record containing book text. This should always be 2048 (for some Mobipocket files) or 4096 (for everything else). A warning will be carped if it isn't.

• spare

Two bytes that should always be zero. A warning will be carped if they aren't.

• unknown12

32 bits of unknown data, generally zero. This key may be changed later if more information is discovered. Use with caution. (mystery bytes… we don't know her yet 🙈)

Note that the current position component of the header is discarded. gone. not invited. bye 👋

💜 uncompress_palmdoc($data,%args) 💜

Uncompresses data compressed using the simplified Lempel-Ziv 77 scheme used by PalmDoc and some other formats, and returns the uncompressed string.

If an error is encountered during uncompression outputs a debug message and returns undef. no crash, just a polite little undef 😭

🌸 Arguments 🌸

uncompress_palmdoc takes one optional named argument:

• trailing — This specifies the number of trailing bytes to ignore on each record during decompression. Extra data such as this is sometimes found on version 6 Mobipocket records. (a little extra junk on the end of each record, and we're just gonna look away 😌)

🌸 Algorithm 🌸

The decoding mechanism is as follows:

Start by reading a byte from the compressed stream. If the byte is:

• 0x00: copy unmodified
• 0x01 to 0x08: "Type A" command

This specifies that the next 1-8 bytes are to be copied unmodified.

• 0x09 to 0x7f: copy unmodified
• 0x80 to 0xbf: "Type B" command

This specifies that the 16 bits (two characters) starting at that point represent a length-offset pair. Of the 16 bits that make up these two bytes, the two leftmost bits (which should be '10') are simply an identifier and are discarded. The next 11 bits encode the offset backwards from the end of uncompressed text, and the last three encode the length of text to copy from that point (copying n+3 bytes).

• 0xc0 to 0xff: "Type C" command

This compresses spaces with the next character, with the value of that character being XORed with 0x80.

---

💀 BUGS 💀

• There isn't really any good way to detect the encoding from a PalmDoc file, and I haven't even tried. You may have some luck with Encode::Detect. On top of this, the encodings aren't entirely conformant with what you might expect, and vary by version of PalmOS. See:

<http://www.df.lth.se/~triad/krad/recode/palm.html>

for details. (encoding detection: not me, not today, possibly not ever 😭)

• PalmDoc files in resource (.prc) form are almost entirely untested. Use at your own risk (but feel free to file bug reports). ⚠️ genuinely, at your own risk bestie ⚠️
• Although bookmarks can be extracted, they cannot be added to a new file. read-only bookmark energy fr fr
• Unit tests are unwritten. 🙈 they're on the list. the list is long. the list is a vibe.

---

👑 AUTHOR 👑

Zed Pobre <zed@debian.org>

---

📜 COPYRIGHT 📜

Copyright 2008 Zed Pobre

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

---

🔥 SEE ALSO 🔥

• EBook::Tools
• Palm::PDB
• Palm::Doc

Palm::Doc was the inspiration for this component, but it has been completely redesigned and the only code remaining from it is in compress_palmdoc(). (a full makeover, only one little outfit left from the original wardrobe 💅)

---

okay that's the whole page babe, you ate, go compress something 📚💖

signing off from perl v5.40.0, dated 2025-01-10 — same page, new energy. bye bestie, ily, go read your .pdb files ✨