Repository Public
1// ORIX Docs2// File: Packages/ORIXDocsKit/Sources/DocReferences/LaTeXText.swift3// Description: Decodes the LaTeX markup found in BibTeX field values to Unicode text (accents, symbols, dashes, simple formatting commands)4// and encodes Unicode text back to BibTeX-safe LaTeX. Math ($…$) and unknown commands are kept verbatim in both directions.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation910/// LaTeX ⇄ Unicode conversion for bibliography fields.11///12/// Decoded text uses the CSL-JSON rich-text convention for the little formatting a title can carry:13/// `<i>…</i>`, `<b>…</b>`, `<sup>…</sup>`, `<sub>…</sub>` and `<span style="font-variant:small-caps;">…</span>`.14public enum LaTeXText {15 static let smallCapsOpen = "<span style=\"font-variant:small-caps;\">"16 static let smallCapsClose = "</span>"1718 private static let combining: [Character: String] = [19 "'": "\u{0301}", "`": "\u{0300}", "^": "\u{0302}", "\"": "\u{0308}", "~": "\u{0303}", "=": "\u{0304}", ".": "\u{0307}",20 "u": "\u{0306}", "v": "\u{030C}", "H": "\u{030B}", "c": "\u{0327}", "k": "\u{0328}", "r": "\u{030A}", "b": "\u{0331}", "d": "\u{0323}",21 "t": "\u{0361}",22 ]23 /// What an accent command produces when it has no base letter (`\~{}`).24 private static let spacingAccent: [Character: String] = ["'": "\u{00B4}", "`": "`", "^": "^", "\"": "\u{00A8}", "~": "~", "=": "\u{00AF}", ".": "\u{02D9}"]2526 private static let symbols: [String: String] = [27 "ss": "ß", "SS": "ẞ", "ae": "æ", "AE": "Æ", "oe": "œ", "OE": "Œ", "aa": "å", "AA": "Å", "o": "ø", "O": "Ø", "l": "ł", "L": "Ł",28 "i": "ı", "j": "ȷ", "dh": "ð", "DH": "Ð", "th": "þ", "TH": "Þ", "dj": "đ", "DJ": "Đ", "ng": "ŋ", "NG": "Ŋ",29 "textendash": "–", "textemdash": "—", "dots": "…", "ldots": "…", "textellipsis": "…",30 "textquoteleft": "‘", "textquoteright": "’", "textquotedblleft": "“", "textquotedblright": "”", "textquotesingle": "'", "textquotedbl": "\"",31 "guillemotleft": "«", "guillemotright": "»", "guillemetleft": "«", "guillemetright": "»", "flqq": "«", "frqq": "»",32 "copyright": "©", "textcopyright": "©", "textregistered": "®", "texttrademark": "™", "S": "§", "P": "¶", "textsection": "§",33 "pounds": "£", "textsterling": "£", "euro": "€", "texteuro": "€", "textdegree": "°", "textperiodcentered": "·",34 "textasciitilde": "~", "textasciicircum": "^", "textbackslash": "\\", "textbraceleft": "{", "textbraceright": "}",35 "textunderscore": "_", "textdollar": "$", "textless": "<", "textgreater": ">", "textbar": "|", "slash": "/",36 "LaTeX": "LaTeX", "TeX": "TeX", "BibTeX": "BibTeX", "quad": " ", "qquad": " ", "space": " ", "newline": " ", "par": " ",37 "nobreakspace": "\u{00A0}", "textexclamdown": "¡", "textquestiondown": "¿", "textordfeminine": "ª", "textordmasculine": "º",38 "textnumero": "№", "textbullet": "•", "textdagger": "†", "textdaggerdbl": "‡", "textmu": "µ", "texttimes": "×",39 ]40 private static let punctuationCommands: [Character: String] = [41 "&": "&", "%": "%", "$": "$", "#": "#", "_": "_", "{": "{", "}": "}", " ": " ", ",": "\u{2009}", "-": "\u{00AD}", "/": "", "@": "",42 "\\": " ", "!": "", ";": " ", ":": " ", "\n": " ", "\t": " ",43 ]44 /// Commands whose single argument is wrapped in a tag pair.45 private static let wrappers: [String: (String, String)] = [46 "emph": ("<i>", "</i>"), "textit": ("<i>", "</i>"), "textsl": ("<i>", "</i>"), "mkbibemph": ("<i>", "</i>"), "mkbibitalic": ("<i>", "</i>"),47 "textbf": ("<b>", "</b>"), "mkbibbold": ("<b>", "</b>"),48 "textsuperscript": ("<sup>", "</sup>"), "textsubscript": ("<sub>", "</sub>"),49 "textsc": (smallCapsOpen, smallCapsClose),50 "mkbibquote": ("“", "”"), "enquote": ("“", "”"),51 "textrm": ("", ""), "texttt": ("", ""), "textsf": ("", ""), "textup": ("", ""), "textnormal": ("", ""), "textmd": ("", ""),52 "mbox": ("", ""), "hbox": ("", ""), "text": ("", ""), "url": ("", ""), "nolinkurl": ("", ""), "path": ("", ""), "protect": ("", ""),53 "relax": ("", ""), "noopsort": ("", ""),54 ]55 /// Old-style declarations that apply to the rest of the enclosing group (`{\em text}`).56 private static let declarations: [String: (String, String)] = [57 "em": ("<i>", "</i>"), "it": ("<i>", "</i>"), "itshape": ("<i>", "</i>"), "sl": ("<i>", "</i>"), "slshape": ("<i>", "</i>"),58 "bf": ("<b>", "</b>"), "bfseries": ("<b>", "</b>"), "sc": (smallCapsOpen, smallCapsClose), "scshape": (smallCapsOpen, smallCapsClose),59 "rm": ("", ""), "tt": ("", ""), "sf": ("", ""), "rmfamily": ("", ""), "ttfamily": ("", ""), "sffamily": ("", ""), "upshape": ("", ""),60 "normalfont": ("", ""), "small": ("", ""), "large": ("", ""), "footnotesize": ("", ""),61 ]6263 // MARK: Decoding6465 /// Converts a raw BibTeX value (outer delimiters already removed) to Unicode text.66 /// - Parameter collapseWhitespace: joins lines and collapses runs of white space, as BibTeX does for ordinary fields.67 public static func decode(_ raw: String, collapseWhitespace: Bool = true) -> String {68 var out: String69 if raw.unicodeScalars.contains(where: { isActive($0) }) {70 var d = Decoder(Array(raw))71 out = d.parse(inGroup: false)72 out = out.precomposedStringWithCanonicalMapping73 } else {74 out = raw75 }76 return collapseWhitespace ? collapse(out) : out.trimmingCharacters(in: .whitespacesAndNewlines)77 }7879 private static func isActive(_ u: Unicode.Scalar) -> Bool {80 switch u { case "\\", "{", "}", "~", "$", "-", "`", "'": return true; default: return false }81 }8283 static func collapse(_ s: String) -> String {84 var out = ""85 out.reserveCapacity(s.utf8.count)86 var pendingSpace = false87 for ch in s {88 if ch == " " || ch == "\n" || ch == "\t" || ch == "\r" || ch == "\r\n" {89 pendingSpace = !out.isEmpty90 } else {91 if pendingSpace { out.append(" "); pendingSpace = false }92 out.append(ch)93 }94 }95 return out96 }9798 private struct Decoder {99 let c: [Character]100 var i = 0101 init(_ c: [Character]) { self.c = c }102103 /// Parses until the end of input, or until the closing brace of the current group (which is left unconsumed).104 mutating func parse(inGroup: Bool) -> String {105 var out = ""106 while i < c.count {107 let ch = c[i]108 switch ch {109 case "}":110 if inGroup { return out }111 out.append("}"); i += 1112 case "{":113 i += 1114 out += parse(inGroup: true)115 if i < c.count, c[i] == "}" { i += 1 }116 case "\\":117 if let rest = command(&out, inGroup: inGroup) { out += rest; return out }118 case "$":119 if let end = LaTeXText.mathEnd(c, i) {120 out += String(c[i...end]); i = end + 1121 } else { out.append("$"); i += 1 }122 case "~":123 out.append("\u{00A0}"); i += 1124 case "-":125 var n = 0126 while i < c.count, c[i] == "-" { n += 1; i += 1 }127 while n >= 3 { out.append("—"); n -= 3 }128 if n == 2 { out.append("–") } else if n == 1 { out.append("-") }129 case "`":130 if i + 1 < c.count, c[i + 1] == "`" { out.append("“"); i += 2 } else { out.append("`"); i += 1 }131 case "'":132 if i + 1 < c.count, c[i + 1] == "'" { out.append("”"); i += 2 } else { out.append("'"); i += 1 }133 default:134 out.append(ch); i += 1135 }136 }137 return out138 }139140 mutating func skipSpaces() { while i < c.count, c[i] == " " || c[i] == "\n" || c[i] == "\t" { i += 1 } }141142 /// Reads one argument: a braced group (decoded), a command, or a single character.143 mutating func argument() -> String {144 guard i < c.count else { return "" }145 if c[i] == "{" {146 i += 1147 let s = parse(inGroup: true)148 if i < c.count, c[i] == "}" { i += 1 }149 return s150 }151 if c[i] == "\\" {152 var s = ""153 _ = command(&s, inGroup: false)154 return s155 }156 if c[i] == "}" { return "" }157 let s = String(c[i]); i += 1158 return s159 }160161 /// Raw balanced group starting at `i` (which must be "{"), or nil when unbalanced.162 func rawGroupEnd() -> Int? {163 var depth = 0, j = i164 while j < c.count {165 if c[j] == "{" { depth += 1 } else if c[j] == "}" { depth -= 1; if depth == 0 { return j } }166 j += 1167 }168 return nil169 }170171 /// Handles the command at `i`. Returns non-nil (the wrapped remainder of the group) when the command was a declaration that consumed the rest of the group.172 mutating func command(_ out: inout String, inGroup: Bool) -> String? {173 let start = i174 i += 1175 guard i < c.count else { out.append("\\"); return nil }176 let first = c[i]177 if !first.isASCIILetter {178 i += 1179 if first == "(" || first == "[" { // \( … \) and \[ … \] math, kept verbatim180 let close: Character = first == "(" ? ")" : "]"181 var j = i182 while j + 1 < c.count, !(c[j] == "\\" && c[j + 1] == close) { j += 1 }183 if j + 1 < c.count { out += String(c[start...(j + 1)]); i = j + 2 } else { out += String(c[start..<i]) }184 return nil185 }186 if let mark = LaTeXText.combining[first] {187 applyAccent(first, mark, &out)188 return nil189 }190 if let s = LaTeXText.punctuationCommands[first] { out += s } else { out.append("\\"); out.append(first) }191 return nil192 }193 var name = ""194 while i < c.count, c[i].isASCIILetter { name.append(c[i]); i += 1 }195 if name.count == 1, let mark = LaTeXText.combining[name.first!] {196 // Letter accents: `\c{c}`, `\v s`, `\H{o}`.197 skipSpaces()198 applyAccent(name.first!, mark, &out)199 return nil200 }201 if let s = LaTeXText.symbols[name] {202 swallowAfterName()203 out += s204 return nil205 }206 if let (open, close) = LaTeXText.wrappers[name] {207 skipSpaces()208 out += open + argument() + close209 return nil210 }211 if name == "href" {212 skipSpaces(); _ = argument(); skipSpaces()213 out += argument()214 return nil215 }216 if let (open, close) = LaTeXText.declarations[name] {217 skipSpaces()218 if inGroup {219 let rest = parse(inGroup: true)220 return open + rest + close221 }222 return nil223 }224 // Unknown command: kept verbatim, with its braced arguments.225 out += "\\" + name226 while i < c.count, c[i] == "{", let end = rawGroupEnd() {227 out += String(c[i...end]); i = end + 1228 }229 return nil230 }231232 mutating func swallowAfterName() {233 if i + 1 < c.count, c[i] == "{", c[i + 1] == "}" { i += 2; return }234 skipSpaces()235 }236237 mutating func applyAccent(_ cmd: Character, _ mark: String, _ out: inout String) {238 var arg = argument()239 if arg == "ı" { arg = "i" } else if arg == "ȷ" { arg = "j" }240 guard let base = arg.first else { out += LaTeXText.spacingAccent[cmd] ?? ""; return }241 out += (String(base) + mark).precomposedStringWithCanonicalMapping + arg.dropFirst()242 }243 }244245 // MARK: Encoding246247 /// Converts Unicode text to a BibTeX value body (without the outer braces). `decode(encode(x)) == x` for text with collapsed white space.248 /// - Parameter strict: escapes every `$` and backslash instead of passing math and unknown commands through (used when the lenient output would not be brace-balanced).249 public static func encode(_ text: String, strict: Bool = false) -> String {250 let c = Array(convertTags(text))251 var out = ""252 out.reserveCapacity(text.utf8.count + 8)253 var i = 0254 func emit(_ s: String) {255 if let l = out.last, let f = s.first, l == f, f == "-" || f == "`" || f == "'" { out += "{}" }256 out += s257 }258 while i < c.count {259 let ch = c[i]260 switch ch {261 case "\u{2}": out += "}" // structural markers produced by convertTags262 case "\u{3}": out += "\\textit{"263 case "\u{4}": out += "\\textbf{"264 case "\u{5}": out += "\\textsuperscript{"265 case "\u{6}": out += "\\textsubscript{"266 case "\u{7}": out += "\\textsc{"267 case "$":268 if !strict, let end = mathEnd(c, i) { out += String(c[i...end]); i = end }269 else { out += "\\$" }270 case "\\":271 if strict { out += "\\textbackslash{}" }272 else if i + 1 < c.count, c[i + 1].isASCIILetter {273 var j = i + 1274 while j < c.count, c[j].isASCIILetter { j += 1 }275 let name = String(c[(i + 1)..<j])276 if symbols[name] != nil || wrappers[name] != nil || declarations[name] != nil || name == "href"277 || (name.count == 1 && combining[name.first!] != nil) {278 out += "\\textbackslash{}" // would be reinterpreted on the way back: keep it a literal backslash279 } else {280 out += "\\" + name281 var k = j282 while k < c.count, c[k] == "{", let end = balancedEnd(c, k) { out += String(c[k...end]); k = end + 1 }283 i = k - 1284 }285 } else if i + 1 < c.count, c[i + 1] == "(" || c[i + 1] == "[", let end = displayMathEnd(c, i) {286 out += String(c[i...end]); i = end287 } else { out += "\\textbackslash{}" }288 case "{": out += "\\textbraceleft{}"289 case "}": out += "\\textbraceright{}"290 case "%": out += "\\%"291 case "&": out += "\\&"292 case "#": out += "\\#"293 case "_": out += "\\_"294 case "~": out += "\\textasciitilde{}"295 case "\u{00A0}": out += "~"296 case "\u{2009}": out += "\\,"297 case "\u{00AD}": out += "\\-"298 case "–": emit("--")299 case "—": emit("---")300 case "“": emit("``")301 case "”": emit("''")302 case "-", "`", "'": emit(String(ch))303 default: out.append(ch)304 }305 i += 1306 }307 return out308 }309310 /// Replaces balanced rich-text tags by structural markers (U+0003…U+0007 open, U+0002 close) that `encode` expands to LaTeX commands.311 private static func convertTags(_ s: String) -> String {312 // Text with math or raw commands is copied through in places, so its tags are left as literal text rather than risk unbalanced braces.313 guard s.contains("<"), !s.contains("$"), !s.contains("\\") else { return s }314 let pairs: [(String, String, String)] = [315 ("<i>", "</i>", "\u{3}"), ("<b>", "</b>", "\u{4}"), ("<sup>", "</sup>", "\u{5}"), ("<sub>", "</sub>", "\u{6}"),316 (smallCapsOpen, smallCapsClose, "\u{7}"),317 ]318 var out = s319 for (open, close, marker) in pairs {320 let opens = out.components(separatedBy: open).count - 1321 let closes = out.components(separatedBy: close).count - 1322 guard opens > 0, opens == closes, wellNested(out, open, close) else { continue }323 out = out.replacingOccurrences(of: open, with: marker).replacingOccurrences(of: close, with: "\u{2}")324 }325 return out326 }327328 private static func displayMathEnd(_ c: [Character], _ start: Int) -> Int? {329 let close: Character = c[start + 1] == "(" ? ")" : "]"330 var j = start + 2331 while j + 1 < c.count { if c[j] == "\\", c[j + 1] == close { return j + 1 }; j += 1 }332 return nil333 }334335 private static func wellNested(_ s: String, _ open: String, _ close: String) -> Bool {336 var depth = 0337 var rest = Substring(s)338 while true {339 let o = rest.range(of: open), c = rest.range(of: close)340 guard let c else { return depth == 0 && o == nil }341 if let o, o.lowerBound < c.lowerBound { depth += 1; rest = rest[o.upperBound...] }342 else { depth -= 1; if depth < 0 { return false }; rest = rest[c.upperBound...] }343 }344 }345346 private static func balancedEnd(_ c: [Character], _ start: Int) -> Int? {347 var depth = 0, j = start348 while j < c.count {349 if c[j] == "{" { depth += 1 } else if c[j] == "}" { depth -= 1; if depth == 0 { return j } }350 j += 1351 }352 return nil353 }354355 /// End index of a `$…$` segment that looks like math: non-empty, no white space next to the delimiters, not followed by a digit.356 fileprivate static func mathEnd(_ c: [Character], _ start: Int) -> Int? {357 guard start + 1 < c.count, !c[start + 1].isWhitespace, c[start + 1] != "$" else { return nil }358 var j = start + 1359 while j < c.count {360 if c[j] == "\\" { j += 2; continue }361 if c[j] == "$" { break }362 j += 1363 }364 guard j < c.count, !c[j - 1].isWhitespace else { return nil }365 if j + 1 < c.count, c[j + 1].isNumber { return nil }366 return j367 }368}369370extension Character {371 var isASCIILetter: Bool { ("a"..."z").contains(self) || ("A"..."Z").contains(self) }372}373