Font::TTF::Cmap(3)

💖 NAME 💖

Font::TTF::Cmap — the character map table, aka the girl who knows which codepoint goes with which glyph 💅

Like, hi bestie! Welcome to the manpage for Font::TTF::Cmap, a Perl module. Yes it's a real manual page, yes we're doing this, and yes you're gonna understand it. Slay. ✨

---

🦋 DESCRIPTION 🦋

Okay so this module looks after the character map. That's its whole job and it ate, no cap.

And because it wants your life to be easy, the actual cmap is held in a hash against codepoint. So for a given table you just do:

$gid = $font->{'cmap'}{'Tables'}[0]{'val'}{$code};

One thing though, real talk: $code should be a true value (0x1234) rather than a string representation. Not me warning you twice, but like… I am. 😭

---

🌸 INSTANCE VARIABLES 🌸

So the instance variables listed down here are not preceded by a space, and that's on purpose — it's because they're emulating structural information in the font. Iconic behaviour honestly.

• Num — the number of subtables in this table
• Tables — an array of subtables ([0..Num-1])

And each subtable also has its own instance variables, which are, again, not preceded by a space:

• Platform — the platform number for this subtable
• Encoding — the encoding number for this subtable
• Format — gives the stored format of this subtable
• Ver — gives the version (or language) information for this subtable
• val — a hash keyed by the codepoint value (not a string) storing the glyph id

Then there are the following cmap options, and these ones are controlled by instance variables that do start with a space:

• allowholes — by default, when generating format 4 cmap subtables, character codes that point to glyph zero (normally called .notdef) are not included in the subtable. But sometimes including some of these character codes can result in a smaller format 4 subtable, which is lowkey a glow-up. To enable this behavior, set allowholes to non-zero. 🫶

---

🌈 METHODS 🌈

$t->read

Reads the cmap into memory. Format 4 subtables read the whole subtable and fill in the segmented array accordingly. She's thorough, we love that for her. 💖

$t->ms_lookup($uni)

Finds a Unicode table — giving preference to the MS one — and looks up the given Unicode codepoint in it to find the glyph id. Main character energy: it goes straight for the Microsoft table first. 👑

$t->find_ms

Finds the a Unicode table, giving preference to the Microsoft one, and sets the mstable instance variable to it if found. Returns the table it finds. (Yes, the original says "the a Unicode table" — I'm not fixing it, that's just her vibe.) 🙈

$t->ms_enc

Returns the encoding of the microsoft table (0 => symbol, etc.). Returns undef if there is no Microsoft cmap. Sad but fair. 💀

$t->out($fh)

Writes out a cmap table to a filehandle. And if it has not been read yet? It just copies from input file to output. Effortless. ⭐

$t->XML_element($context, $depth, $name, $val)

Outputs the elements of the cmap in XML. We only need to process val here — that's it, that's the whole assignment. 🎀

$t->minsize()

Returns the minimum size this table can be in bytes. And if it's smaller than this, then the table must be bad and should be deleted or whatever. Not me being dramatic, that's literally what it says. 😭

$t->update

Tidies the cmap table. Spring cleaning, cmap edition 🧹✨

• Removes MS Fmt12 cmap if it is no longer needed.
• Removes from all cmaps any codepoint that map to GID=0. And heads up: such entries will be re-introduced as necessary depending on the cmap format. So like, they come back. It's giving resurrection. 🦋

@map = $t->reverse(%opt)

Returns a reverse map of the Unicode cmap. I.e. given a glyph gives the Unicode value for it. Flip it and reverse it 💜 Options are:

tnum

Table number to use rather than the default Unicode table

array

Returns each element of reverse as an array since a glyph may be mapped by more than one Unicode value. The arrays are unsorted. Otherwise store any one unicode value for a glyph. Pick your fighter. 🍓

is_unicode($index)

Returns whether the table of a given index is known to be a unicode table (as specified in the specifications). She said trust the specs, bestie. 📜

---

💀 BUGS 💀

• Format 14 (Unicode Variation Sequences) cmaps are not supported. Ngl, she simply does not do those. 🙈

---

👑 AUTHOR 👑

Martin Hosken <http://scripts.sil.org/FontUtils>.

---

🎀 LICENSING 🎀

Copyright (c) 1998-2016, SIL International (http://www.sil.org)

This module is released under the terms of the Artistic License 2.0. For details, see the full text of the license in the file LICENSE. Read it, bestie, it's giving responsible. 💖

---

Okay that's the whole page, ily, go map some characters 💅✨

perl v5.42.0 🦋 2016-08-28 🦋 Font::TTF::Cmap(3) — mwah, that's the sign-off, bye bestie! 🫶🌸