crossmate

PUZToXDConverter.swift (17366B)

---

 import Foundation
 
 /// Converts Across Lite `.puz` files to Crossmate's `.xd` source format.
 enum PUZToXDConverter {
     struct ConversionError: LocalizedError {
         let message: String
         var errorDescription: String? { message }
     }
 
     private struct ClueEntry {
         let number: Int
         let direction: Direction
         let cells: [Int]
         let text: String
     }
 
     private enum Direction {
         case across
         case down
 
         var prefix: String {
             switch self {
             case .across: "A"
             case .down: "D"
             }
         }
     }
 
     /// Upper bound on raw `.puz` bytes accepted by `convert`. Real Across
     /// Lite files are tens of kilobytes. Independent of `XD.maxSourceBytes`
     /// because a `.puz` can hide a large ignored tail (string table,
     /// extensions) behind a small grid; enforcing it here covers every call
     /// site before any header parsing or string-table walk.
     static let maxSourceBytes = 262_144
 
     static func convert(puzData data: Data) throws -> String {
         guard data.count <= maxSourceBytes else {
             throw ConversionError(message: "Across Lite file is too large.")
         }
         // The offsets below are absolute, but a Data slice keeps its parent's
         // indices, so re-base a slice onto fresh zero-based storage first.
         // (The extension parsers already index relative to startIndex — they
         // receive slices of this data — but the header/string-table walk here
         // assumes zero-based subscripts throughout.)
         let data = data.startIndex == 0 ? data : Data(data)
         guard data.count >= 0x34 else {
             throw ConversionError(message: "Across Lite file is too short.")
         }
         guard asciiString(in: data, range: 0x02..<0x0D) == "ACROSS&DOWN" else {
             throw ConversionError(message: "Not an Across Lite puzzle.")
         }
 
         let width = Int(data[0x2C])
         let height = Int(data[0x2D])
         let clueCount = Int(littleEndianUInt16(in: data, at: 0x2E))
         guard width > 0, height > 0 else {
             throw ConversionError(message: "Across Lite puzzle has invalid dimensions.")
         }
 
         let cellCount = width * height
         let solutionStart = 0x34
         let fillStart = solutionStart + cellCount
         let stringsStart = fillStart + cellCount
         guard data.count >= stringsStart else {
             throw ConversionError(message: "Across Lite grid is incomplete.")
         }
 
         let solutionBytes = Array(data[solutionStart..<fillStart])
         let stringTable = try parseNullTerminatedStrings(
             in: data,
             from: stringsStart,
             count: clueCount + 4
         )
         guard stringTable.strings.count >= clueCount + 3 else {
             throw ConversionError(message: "Across Lite string table is incomplete.")
         }
 
         let title = displayTitle(fromPUZTitle: stringTable.strings[0])
         let author = displayAuthor(fromPUZAuthor: stringTable.strings[1])
         let copyright = stringTable.strings[2]
         let clueTexts = Array(stringTable.strings[3..<(3 + clueCount)])
         let extensions = parseExtensions(in: data, from: stringTable.endOffset)
         let rebus = parseRebus(extensions: extensions, cellCount: cellCount)
         let circledCells = parseCircledCells(extensions: extensions, cellCount: cellCount)
 
         let entries = try buildClues(
             solutionBytes: solutionBytes,
             width: width,
             height: height,
             clueTexts: clueTexts
         )
 
         // Each distinct rebus fill claims one grid placeholder from
         // `XD.rebusPlaceholders`; cells sharing a fill reuse the same key
         // (mirrors `NYTToXDConverter`). Circling is no longer part of that
         // identity — it rides in the `## Decorations` section keyed by position —
         // so a circled and an uncircled occurrence of one fill now share a key.
         // Keying by cell index instead would burn a fresh character per cell and
         // walk straight into the grid/header reserved set (`=`, `@`, ...) and,
         // past ~200 cells, off the end of the alphabet — hence the bounds check
         // rather than raw arithmetic.
         var rebusKeys: [Int: Character] = [:]
         var rebusEntries: [(Character, String)] = []
         var rebusLookup: [String: Character] = [:]
         for index in 0..<cellCount where isOpen(solutionBytes[index]) {
             guard let value = rebus[index], !value.isEmpty else { continue }
             let normalized = value.uppercased()
             let key: Character
             if let existing = rebusLookup[normalized] {
                 key = existing
             } else {
                 guard rebusLookup.count < XD.rebusPlaceholders.count else {
                     throw ConversionError(
                         message: "Across Lite puzzle has too many distinct rebus fills (\(rebusLookup.count + 1)); ran out of grid placeholders."
                     )
                 }
                 key = XD.rebusPlaceholders[rebusLookup.count]
                 rebusLookup[normalized] = key
                 rebusEntries.append((key, normalized))
             }
             rebusKeys[index] = key
         }
 
         var metadata: [String] = []
         if !title.isEmpty { metadata.append("Title: \(title)") }
         metadata.append("ConVer: \(XD.currentConverterVersion)")
         if !author.isEmpty { metadata.append("Author: \(author)") }
         if !copyright.isEmpty { metadata.append("Copyright: \(copyright)") }
         if !rebusEntries.isEmpty {
             let header = rebusEntries.map { "\($0.0)=\($0.1)" }.joined(separator: " ")
             metadata.append("Rebus: \(header)")
         }
 
         let gridLines = (0..<height).map { row -> String in
             var line = ""
             for col in 0..<width {
                 let index = row * width + col
                 let byte = solutionBytes[index]
                 guard isOpen(byte) else {
                     line += "#"
                     continue
                 }
                 if let key = rebusKeys[index] {
                     line.append(key)
                     continue
                 }
                 // A circled cell keeps its letter now that the circle is
                 // expressed in `## Decorations` rather than displacing the fill.
                 line += String(UnicodeScalar(byte)).uppercased()
             }
             return line
         }
 
         let acrossLines = entries
             .filter { $0.direction == .across }
             .map { clueLine($0, solutionBytes: solutionBytes, rebus: rebus) }
         let downLines = entries
             .filter { $0.direction == .down }
             .map { clueLine($0, solutionBytes: solutionBytes, rebus: rebus) }
 
         var sections = [
             metadata.joined(separator: "\n"),
             gridLines.joined(separator: "\n"),
             (acrossLines + [""] + downLines).joined(separator: "\n")
         ]
         var decorations: [GridPosition: [Puzzle.Decoration]] = [:]
         for index in circledCells {
             decorations[GridPosition(row: index / width, col: index % width)] = [
                 Puzzle.Decoration(content: .mark(.circled), phase: .before)
             ]
         }
         if let decorationSection = try XDDecorationWriter.section(
             decorations: decorations,
             width: width,
             height: height
         ) {
             sections.append(decorationSection)
         }
         return sections.joined(separator: "\n\n\n")
     }
 
     private static func buildClues(
         solutionBytes: [UInt8],
         width: Int,
         height: Int,
         clueTexts: [String]
     ) throws -> [ClueEntry] {
         var entries: [ClueEntry] = []
         var clueIndex = 0
         var number = 1
 
         for row in 0..<height {
             for col in 0..<width {
                 let index = row * width + col
                 guard isOpen(solutionBytes[index]) else { continue }
 
                 let startsAcross = !isOpen(solutionBytes, row: row, col: col - 1, width: width, height: height)
                     && isOpen(solutionBytes, row: row, col: col + 1, width: width, height: height)
                 let startsDown = !isOpen(solutionBytes, row: row - 1, col: col, width: width, height: height)
                     && isOpen(solutionBytes, row: row + 1, col: col, width: width, height: height)
 
                 if startsAcross || startsDown {
                     if startsAcross {
                         guard clueTexts.indices.contains(clueIndex) else {
                             throw ConversionError(message: "Across Lite clue table ended early.")
                         }
                         entries.append(ClueEntry(
                             number: number,
                             direction: .across,
                             cells: wordCells(fromRow: row, col: col, deltaRow: 0, deltaCol: 1, width: width, height: height, solutionBytes: solutionBytes),
                             text: clueTexts[clueIndex]
                         ))
                         clueIndex += 1
                     }
                     if startsDown {
                         guard clueTexts.indices.contains(clueIndex) else {
                             throw ConversionError(message: "Across Lite clue table ended early.")
                         }
                         entries.append(ClueEntry(
                             number: number,
                             direction: .down,
                             cells: wordCells(fromRow: row, col: col, deltaRow: 1, deltaCol: 0, width: width, height: height, solutionBytes: solutionBytes),
                             text: clueTexts[clueIndex]
                         ))
                         clueIndex += 1
                     }
                     number += 1
                 }
             }
         }
 
         guard clueIndex == clueTexts.count else {
             throw ConversionError(message: "Across Lite clue table has unused clues.")
         }
         return entries
     }
 
     private static func clueLine(
         _ entry: ClueEntry,
         solutionBytes: [UInt8],
         rebus: [Int: String]
     ) -> String {
         let answer = entry.cells.map { index -> String in
             if let rebusValue = rebus[index], !rebusValue.isEmpty {
                 return rebusValue
             }
             return String(UnicodeScalar(solutionBytes[index]))
         }.joined().uppercased()
         return "\(entry.direction.prefix)\(entry.number). \(entry.text) ~ \(answer)"
     }
 
     private static func wordCells(
         fromRow row: Int,
         col: Int,
         deltaRow: Int,
         deltaCol: Int,
         width: Int,
         height: Int,
         solutionBytes: [UInt8]
     ) -> [Int] {
         var cells: [Int] = []
         var r = row
         var c = col
         while isOpen(solutionBytes, row: r, col: c, width: width, height: height) {
             cells.append(r * width + c)
             r += deltaRow
             c += deltaCol
         }
         return cells
     }
 
     private static func parseNullTerminatedStrings(
         in data: Data,
         from start: Int,
         count: Int
     ) throws -> (strings: [String], endOffset: Int) {
         var strings: [String] = []
         var offset = start
         while strings.count < count && offset < data.count {
             guard let end = data[offset...].firstIndex(of: 0) else { break }
             strings.append(decodeString(data[offset..<end]))
             offset = data.index(after: end)
         }
         guard strings.count == count else {
             throw ConversionError(message: "Across Lite string table is incomplete.")
         }
         return (strings, offset)
     }
 
     private static func displayTitle(fromPUZTitle title: String) -> String {
         let letters = title.unicodeScalars.filter { CharacterSet.letters.contains($0) }
         guard !letters.isEmpty,
               letters.allSatisfy({ CharacterSet.uppercaseLetters.contains($0) })
         else { return title }
 
         var result = ""
         var startOfWord = true
         for scalar in title.unicodeScalars {
             if CharacterSet.letters.contains(scalar) {
                 let string = String(scalar)
                 result += startOfWord ? string.uppercased() : string.lowercased()
                 startOfWord = false
             } else {
                 result += String(scalar)
                 startOfWord = !CharacterSet.decimalDigits.contains(scalar)
             }
         }
         return result
     }
 
     /// `.puz` author strings frequently embed the credit phrasing
     /// ("by Jane Doe", "Edited by John Smith"). Strip a leading
     /// "by"/"edited by" and surrounding whitespace so the stored
     /// `Author:` metadata is a clean name, matching the NYT path; the
     /// credits view supplies the "By " label at render time.
     private static func displayAuthor(fromPUZAuthor author: String) -> String {
         var result = author.trimmingCharacters(in: .whitespacesAndNewlines)
         for prefix in ["edited by ", "by "] where result.lowercased().hasPrefix(prefix) {
             result = String(result.dropFirst(prefix.count))
                 .trimmingCharacters(in: .whitespacesAndNewlines)
             break
         }
         return result
     }
 
     private static func parseExtensions(in data: Data, from start: Int) -> [String: Data] {
         var extensions: [String: Data] = [:]
         var offset = start
         while offset + 8 <= data.count {
             guard let code = String(data: data[offset..<(offset + 4)], encoding: .ascii) else { break }
             let length = Int(littleEndianUInt16(in: data, at: offset + 4))
             let payloadStart = offset + 8
             let payloadEnd = payloadStart + length
             guard payloadEnd <= data.count else { break }
             extensions[code] = data[payloadStart..<payloadEnd]
             offset = payloadEnd
             if offset < data.count, data[offset] == 0 {
                 offset += 1
             }
         }
         return extensions
     }
 
     private static func parseCircledCells(
         extensions: [String: Data],
         cellCount: Int
     ) -> Set<Int> {
         guard let data = extensions["GEXT"], data.count >= cellCount else { return [] }
         var cells: Set<Int> = []
         for offset in 0..<cellCount {
             let dataIndex = data.index(data.startIndex, offsetBy: offset)
             if data[dataIndex] & 0x80 != 0 {
                 cells.insert(offset)
             }
         }
         return cells
     }
 
     private static func parseRebus(
         extensions: [String: Data],
         cellCount: Int
     ) -> [Int: String] {
         guard let grid = extensions["GRBS"], grid.count >= cellCount else { return [:] }
         let table = parseRebusTable(extensions["RTBL"])
         var rebus: [Int: String] = [:]
         for offset in 0..<cellCount {
             let gridIndex = grid.index(grid.startIndex, offsetBy: offset)
             // The grid byte is 1-indexed: 0 means "no rebus" and `1 + n` refers
             // to `RTBL` key `n` (see the .puz FileFormat reference). Subtract one
             // to recover the table key.
             let gridByte = Int(grid[gridIndex])
             guard gridByte > 0, let value = table[gridByte - 1] else { continue }
             rebus[offset] = value
         }
         return rebus
     }
 
     private static func parseRebusTable(_ data: Data?) -> [Int: String] {
         guard let data else { return [:] }
         let source = decodeString(data)
         var table: [Int: String] = [:]
         for rawEntry in source.split(separator: ";") {
             let entry = rawEntry.trimmingCharacters(in: .whitespacesAndNewlines)
             guard let colon = entry.firstIndex(of: ":"),
                   let key = Int(entry[..<colon].trimmingCharacters(in: .whitespaces))
             else { continue }
             let value = entry[entry.index(after: colon)...].trimmingCharacters(in: .whitespaces)
             if !value.isEmpty {
                 table[key] = value
             }
         }
         return table
     }
 
     private static func isOpen(_ byte: UInt8) -> Bool {
         byte != UInt8(ascii: ".") && byte != 0
     }
 
     private static func isOpen(
         _ solutionBytes: [UInt8],
         row: Int,
         col: Int,
         width: Int,
         height: Int
     ) -> Bool {
         guard row >= 0, row < height, col >= 0, col < width else { return false }
         return isOpen(solutionBytes[row * width + col])
     }
 
     private static func littleEndianUInt16(in data: Data, at offset: Int) -> UInt16 {
         UInt16(data[offset]) | (UInt16(data[offset + 1]) << 8)
     }
 
     private static func asciiString(in data: Data, range: Range<Int>) -> String? {
         guard data.count >= range.upperBound else { return nil }
         return String(data: data[range], encoding: .ascii)
     }
 
     private static func decodeString(_ data: Data) -> String {
         if let value = String(data: data, encoding: .windowsCP1252) {
             return value.trimmingCharacters(in: .newlines)
         }
         if let value = String(data: data, encoding: .isoLatin1) {
             return value.trimmingCharacters(in: .newlines)
         }
         return String(decoding: data, as: UTF8.self).trimmingCharacters(in: .newlines)
     }
 }