@cj-tech-master/excelts 8.0.0 → 8.1.0

package/dist/esm/modules/pdf/reader/cmap-parser.js

@@ -0,0 +1,321 @@
+/**
+ * CMap parser for PDF text extraction.
+ *
+ * Parses /ToUnicode CMap programs to build character code → Unicode mappings.
+ * This is essential for extracting text from PDFs that use CIDFonts or
+ * custom encodings.
+ *
+ * Supports:
+ * - beginbfchar / endbfchar (single character mappings)
+ * - beginbfrange / endbfrange (range mappings, including array form)
+ * - begincodespacerange / endcodespacerange
+ * - Multi-byte character codes (1-4 bytes)
+ * - UTF-16BE encoded target strings (including surrogate pairs)
+ *
+ * @see PDF Reference 1.7, §5.9 - ToUnicode CMaps
+ * @see Adobe Technical Note #5411 - CMap Resources
+ */
+import { PdfTokenizer, TokenType } from "./pdf-tokenizer.js";
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * A parsed CMap that maps character codes to Unicode strings.
+ */
+export class CMap {
+    constructor() {
+        this.codeSpaceRanges = [];
+        this.bfChars = new Map();
+        this.bfRanges = [];
+        this.bytesPerCode = 1;
+    }
+    /**
+     * Look up the Unicode string for a character code.
+     * Uses binary search over sorted bfRanges for efficient lookup.
+     */
+    lookup(code) {
+        // Check bfchar mappings first (exact match)
+        const charMapping = this.bfChars.get(code);
+        if (charMapping !== undefined) {
+            return charMapping;
+        }
+        // Check bfrange mappings using binary search
+        const ranges = this.bfRanges;
+        let lo = 0;
+        let hi = ranges.length - 1;
+        while (lo <= hi) {
+            const mid = (lo + hi) >>> 1;
+            const range = ranges[mid];
+            if (code < range.low) {
+                hi = mid - 1;
+            }
+            else if (code > range.high) {
+                lo = mid + 1;
+            }
+            else {
+                // code is within this range
+                if (typeof range.mapping === "string") {
+                    // Single base string — offset the code point
+                    const offset = code - range.low;
+                    const baseCode = stringToCodePoint(range.mapping);
+                    return String.fromCodePoint(baseCode + offset);
+                }
+                // Array mapping
+                const index = code - range.low;
+                if (index < range.mapping.length) {
+                    return range.mapping[index];
+                }
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Add a code space range.
+     */
+    addCodeSpaceRange(low, high, bytes) {
+        this.codeSpaceRanges.push({ low, high, bytes });
+        if (bytes > this.bytesPerCode) {
+            this.bytesPerCode = bytes;
+        }
+    }
+    /**
+     * Add a bfchar mapping.
+     */
+    addBfChar(code, unicode) {
+        this.bfChars.set(code, unicode);
+    }
+    /**
+     * Add a bfrange mapping.
+     */
+    addBfRange(low, high, mapping) {
+        this.bfRanges.push({ low, high, mapping });
+    }
+    /**
+     * Sort bfRanges by low value for binary search.
+     * Should be called after all ranges have been added.
+     */
+    sortRanges() {
+        this.bfRanges.sort((a, b) => a.low - b.low);
+    }
+    /**
+     * Determine the code length (in bytes) for a given first byte,
+     * using the codespace ranges. When multiple ranges match (e.g. a 1-byte
+     * range covering 0x00-0xFF and a 2-byte range whose first byte overlaps),
+     * returns the longest match per the PDF spec's greedy matching rule.
+     * Falls back to bytesPerCode if no range matches.
+     */
+    getCodeLength(firstByte) {
+        let bestLen = 0;
+        for (const range of this.codeSpaceRanges) {
+            if (range.bytes === 1) {
+                if (firstByte >= (range.low & 0xff) && firstByte <= (range.high & 0xff)) {
+                    if (bestLen < 1) {
+                        bestLen = 1;
+                    }
+                }
+            }
+            else if (range.bytes === 2) {
+                const highByteLow = (range.low >> 8) & 0xff;
+                const highByteHigh = (range.high >> 8) & 0xff;
+                if (firstByte >= highByteLow && firstByte <= highByteHigh) {
+                    if (bestLen < 2) {
+                        bestLen = 2;
+                    }
+                }
+            }
+            else {
+                // For multi-byte ranges (3+ bytes), check the high byte
+                const hiLow = range.low >>> ((range.bytes - 1) * 8);
+                const hiHigh = range.high >>> ((range.bytes - 1) * 8);
+                if (firstByte >= hiLow && firstByte <= hiHigh) {
+                    if (range.bytes > bestLen) {
+                        bestLen = range.bytes;
+                    }
+                }
+            }
+        }
+        return bestLen > 0 ? bestLen : this.bytesPerCode; // fallback
+    }
+    /**
+     * Check if this CMap has any mappings.
+     */
+    get isEmpty() {
+        return this.bfChars.size === 0 && this.bfRanges.length === 0;
+    }
+    /**
+     * Check if this CMap has codespace ranges defined.
+     */
+    get hasCodeSpaceRanges() {
+        return this.codeSpaceRanges.length > 0;
+    }
+}
+// =============================================================================
+// CMap Parser
+// =============================================================================
+/**
+ * Parse a CMap program (typically from a /ToUnicode stream).
+ */
+export function parseCMap(data) {
+    const cmap = new CMap();
+    const tokenizer = new PdfTokenizer(data);
+    while (true) {
+        const token = tokenizer.next();
+        if (token.type === TokenType.EOF) {
+            break;
+        }
+        if (token.type === TokenType.Keyword) {
+            const kw = token.strValue;
+            if (kw === "begincodespacerange") {
+                parseCodeSpaceRange(tokenizer, cmap);
+            }
+            else if (kw === "beginbfchar") {
+                parseBfChar(tokenizer, cmap);
+            }
+            else if (kw === "beginbfrange") {
+                parseBfRange(tokenizer, cmap);
+            }
+        }
+    }
+    // Sort bfRanges for binary search lookup
+    cmap.sortRanges();
+    return cmap;
+}
+/**
+ * Parse codespacerange section.
+ */
+function parseCodeSpaceRange(tokenizer, cmap) {
+    while (true) {
+        const token = tokenizer.next();
+        if (token.type === TokenType.EOF) {
+            break;
+        }
+        if (token.type === TokenType.Keyword && token.strValue === "endcodespacerange") {
+            break;
+        }
+        // Expect two hex strings: low high
+        if (token.type === TokenType.HexString) {
+            const lowBytes = token.rawBytes;
+            const highToken = tokenizer.next();
+            if (highToken.type === TokenType.HexString) {
+                const highBytes = highToken.rawBytes;
+                const low = bytesToInt(lowBytes);
+                const high = bytesToInt(highBytes);
+                cmap.addCodeSpaceRange(low, high, lowBytes.length);
+            }
+        }
+    }
+}
+/**
+ * Parse bfchar section.
+ * Format: <srcCode> <dstString>
+ */
+function parseBfChar(tokenizer, cmap) {
+    while (true) {
+        const token = tokenizer.next();
+        if (token.type === TokenType.EOF) {
+            break;
+        }
+        if (token.type === TokenType.Keyword && token.strValue === "endbfchar") {
+            break;
+        }
+        if (token.type === TokenType.HexString) {
+            const code = bytesToInt(token.rawBytes);
+            const target = tokenizer.next();
+            if (target.type === TokenType.HexString) {
+                const unicode = decodeUtf16BE(target.rawBytes);
+                cmap.addBfChar(code, unicode);
+            }
+        }
+    }
+}
+/**
+ * Parse bfrange section.
+ * Formats:
+ *   <low> <high> <dstString>           — sequential mapping
+ *   <low> <high> [<str1> <str2> ...]   — array mapping
+ */
+function parseBfRange(tokenizer, cmap) {
+    while (true) {
+        const token = tokenizer.next();
+        if (token.type === TokenType.EOF) {
+            break;
+        }
+        if (token.type === TokenType.Keyword && token.strValue === "endbfrange") {
+            break;
+        }
+        if (token.type === TokenType.HexString) {
+            const low = bytesToInt(token.rawBytes);
+            const highToken = tokenizer.next();
+            if (highToken.type !== TokenType.HexString) {
+                continue;
+            }
+            const high = bytesToInt(highToken.rawBytes);
+            const mappingToken = tokenizer.next();
+            if (mappingToken.type === TokenType.HexString) {
+                // Sequential mapping from base string
+                const unicode = decodeUtf16BE(mappingToken.rawBytes);
+                cmap.addBfRange(low, high, unicode);
+            }
+            else if (mappingToken.type === TokenType.ArrayBegin) {
+                // Array of individual mappings
+                const mappings = [];
+                while (true) {
+                    const elem = tokenizer.next();
+                    if (elem.type === TokenType.ArrayEnd || elem.type === TokenType.EOF) {
+                        break;
+                    }
+                    if (elem.type === TokenType.HexString) {
+                        mappings.push(decodeUtf16BE(elem.rawBytes));
+                    }
+                }
+                cmap.addBfRange(low, high, mappings);
+            }
+        }
+    }
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Convert a byte array to a big-endian integer.
+ * Uses multiplication instead of bitshift to avoid overflow for large codes.
+ */
+function bytesToInt(bytes) {
+    let result = 0;
+    for (let i = 0; i < bytes.length; i++) {
+        result = result * 256 + bytes[i];
+    }
+    return result;
+}
+/**
+ * Decode a UTF-16BE byte array to a JavaScript string.
+ */
+function decodeUtf16BE(bytes) {
+    let result = "";
+    for (let i = 0; i + 1 < bytes.length; i += 2) {
+        const code = (bytes[i] << 8) | bytes[i + 1];
+        // Handle surrogate pairs
+        if (code >= 0xd800 && code <= 0xdbff && i + 3 < bytes.length) {
+            const low = (bytes[i + 2] << 8) | bytes[i + 3];
+            if (low >= 0xdc00 && low <= 0xdfff) {
+                const cp = 0x10000 + ((code - 0xd800) << 10) + (low - 0xdc00);
+                result += String.fromCodePoint(cp);
+                i += 2;
+                continue;
+            }
+        }
+        result += String.fromCharCode(code);
+    }
+    // Single-byte code: treat as direct character code
+    if (bytes.length === 1) {
+        return String.fromCharCode(bytes[0]);
+    }
+    return result;
+}
+/**
+ * Get the first code point from a string.
+ */
+function stringToCodePoint(str) {
+    return str.codePointAt(0) ?? 0;
+}