Repository Public
1// ORIX Docs2// File: Packages/ORIXDocsKit/Sources/DocReferences/BibTeXParser.swift3// Description: BibTeX / BibLaTeX syntax: entries, @string macros, # concatenation, @preamble, @comment, brace and quote delimiters,4// crossref and xdata inheritance. Produces raw entries that BibTeXMapping converts to BibEntry values.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import DocModel1011public enum BibTeXParser {12 /// Parses BibTeX or BibLaTeX source. Syntax errors are reported with their line number and the parser resumes at the next entry.13 public static func parse(_ text: String) -> BibliographyParseResult {14 var lexer = Lexer(text)15 lexer.run()16 var issues = lexer.issues17 let raws = Inheritance.resolve(lexer.entries, issues: &issues)18 var entries: [BibEntry] = []19 entries.reserveCapacity(raws.count)20 var used = Set<String>()21 for raw in raws where raw.type != "xdata" {22 var entry = BibTeXMapping.entry(from: raw, issues: &issues)23 if entry.key.isEmpty {24 entry.key = ReferenceChecks.suggestedKey(for: entry, existing: used)25 issues.append("Line \(raw.line): entry without a citation key; the key \"\(entry.key)\" was generated.")26 }27 used.insert(entry.key)28 entries.append(entry)29 }30 return BibliographyParseResult(entries: entries, issues: issues)31 }3233 struct RawEntry {34 var type: String // lower-cased, without "@"35 var key: String36 var line: Int37 var names: [String] = [] // field names, lower-cased, in source order38 var values: [String: String] = [:] // raw values (delimiters removed, macros expanded, LaTeX not decoded)3940 mutating func set(_ name: String, _ value: String) {41 if values[name] == nil { names.append(name) }42 values[name] = value43 }44 mutating func remove(_ name: String) {45 guard values.removeValue(forKey: name) != nil else { return }46 names.removeAll { $0 == name }47 }48 }4950 private struct SyntaxError: Error { var message: String; var position: Int }5152 private struct Lexer {53 let b: [UInt8]54 var i = 055 var lineStarts: [Int] = [0]56 var macros: [String: String] = [:]57 var entries: [RawEntry] = []58 var issues: [String] = []59 var seenKeys: [String: Int] = [:]6061 init(_ text: String) {62 b = Array(text.utf8)63 for (k, byte) in b.enumerated() where byte == 0x0A { lineStarts.append(k + 1) }64 for (k, m) in RefDate.bibMacros.enumerated() { macros[m] = RefDate.monthsEN[k] }65 }6667 func line(_ pos: Int) -> Int {68 var lo = 0, hi = lineStarts.count - 169 while lo < hi {70 let mid = (lo + hi + 1) / 271 if lineStarts[mid] <= pos { lo = mid } else { hi = mid - 1 }72 }73 return lo + 174 }7576 func str(_ r: Range<Int>) -> String { String(decoding: b[r], as: UTF8.self) }77 static func isSpace(_ c: UInt8) -> Bool { c == 0x20 || c == 0x0A || c == 0x0D || c == 0x09 }78 static func isAlpha(_ c: UInt8) -> Bool { (c >= 0x41 && c <= 0x5A) || (c >= 0x61 && c <= 0x7A) }79 static func isDigit(_ c: UInt8) -> Bool { c >= 0x30 && c <= 0x39 }80 /// Characters allowed in field and macro names.81 static func isNameChar(_ c: UInt8) -> Bool {82 if c >= 0x80 || isAlpha(c) || isDigit(c) { return true }83 switch c { case UInt8(ascii: "-"), UInt8(ascii: "_"), UInt8(ascii: ":"), UInt8(ascii: "."), UInt8(ascii: "+"), UInt8(ascii: "/"), UInt8(ascii: "!"),84 UInt8(ascii: "$"), UInt8(ascii: "&"), UInt8(ascii: "*"), UInt8(ascii: "?"), UInt8(ascii: "<"), UInt8(ascii: ">"), UInt8(ascii: "@"),85 UInt8(ascii: "["), UInt8(ascii: "]"), UInt8(ascii: "^"), UInt8(ascii: "`"), UInt8(ascii: "|"), UInt8(ascii: "~"): return true86 default: return false }87 }8889 mutating func skipSpace() {90 while i < b.count {91 if Lexer.isSpace(b[i]) { i += 1 }92 else if b[i] == UInt8(ascii: "%") { while i < b.count, b[i] != 0x0A { i += 1 } } // comment to end of line (between tokens only)93 else { break }94 }95 }9697 mutating func run() {98 while i < b.count {99 guard b[i] == UInt8(ascii: "@") else { i += 1; continue }100 let at = i101 i += 1102 skipSpace()103 let nameStart = i104 while i < b.count, Lexer.isAlpha(b[i]) { i += 1 }105 guard i > nameStart else { continue }106 let type = str(nameStart..<i).lowercased()107 skipSpace()108 guard i < b.count, b[i] == UInt8(ascii: "{") || b[i] == UInt8(ascii: "(") else { i = nameStart; continue } // "@" in free text109 let close: UInt8 = b[i] == UInt8(ascii: "{") ? UInt8(ascii: "}") : UInt8(ascii: ")")110 i += 1111 do {112 switch type {113 case "comment": try skipComment(open: b[i - 1], close: close, at: at)114 case "preamble":115 _ = try value(at: at)116 try expectClose(close, what: "@preamble", at: at)117 case "string": try stringDefinition(close: close, at: at)118 default: try entry(type: type, close: close, at: at)119 }120 } catch let e as SyntaxError {121 issues.append("Line \(line(e.position)): \(e.message)")122 resync(after: at)123 } catch {}124 }125 }126127 /// After an error, resumes at the next line that starts with "@".128 mutating func resync(after at: Int) {129 var j = at + 1130 while j < b.count {131 if b[j] == 0x0A {132 var k = j + 1133 while k < b.count, b[k] == 0x20 || b[k] == 0x09 { k += 1 }134 if k < b.count, b[k] == UInt8(ascii: "@") { i = k; return }135 }136 j += 1137 }138 i = b.count139 }140141 mutating func skipComment(open: UInt8, close: UInt8, at: Int) throws {142 var depth = 1143 while i < b.count {144 if b[i] == open { depth += 1 } else if b[i] == close { depth -= 1; if depth == 0 { i += 1; return } }145 i += 1146 }147 throw SyntaxError(message: "@comment is not closed.", position: at)148 }149150 mutating func expectClose(_ close: UInt8, what: String, at: Int) throws {151 skipSpace()152 guard i < b.count else { throw SyntaxError(message: "\(what) is not closed (end of file reached).", position: at) }153 guard b[i] == close else { throw SyntaxError(message: "unexpected \"\(Character(UnicodeScalar(b[i])))\" in \(what); expected \"\(Character(UnicodeScalar(close)))\".", position: i) }154 i += 1155 }156157 mutating func name() -> String {158 let start = i159 while i < b.count, Lexer.isNameChar(b[i]) { i += 1 }160 return str(start..<i)161 }162163 mutating func stringDefinition(close: UInt8, at: Int) throws {164 skipSpace()165 let n = name().lowercased()166 guard !n.isEmpty else { throw SyntaxError(message: "@string without a macro name.", position: i) }167 skipSpace()168 guard i < b.count, b[i] == UInt8(ascii: "=") else { throw SyntaxError(message: "@string \(n): missing \"=\".", position: min(i, b.count - 1)) }169 i += 1170 macros[n] = try value(at: at)171 try expectClose(close, what: "@string \(n)", at: at)172 }173174 /// A value expression: pieces joined by "#". Each piece is {braced}, "quoted", a number or a macro name.175 mutating func value(at: Int) throws -> String {176 var out = ""177 while true {178 skipSpace()179 guard i < b.count else { throw SyntaxError(message: "value expected, end of file reached.", position: at) }180 let c = b[i]181 if c == UInt8(ascii: "{") {182 let start = i + 1183 var depth = 1184 i += 1185 while i < b.count, depth > 0 {186 if b[i] == UInt8(ascii: "{") { depth += 1 } else if b[i] == UInt8(ascii: "}") { depth -= 1 }187 i += 1188 }189 guard depth == 0 else { throw SyntaxError(message: "unbalanced braces: the value opened here is never closed.", position: start - 1) }190 out += str(start..<(i - 1))191 } else if c == UInt8(ascii: "\"") {192 let start = i + 1193 var depth = 0194 i += 1195 while i < b.count, !(b[i] == UInt8(ascii: "\"") && depth == 0) {196 if b[i] == UInt8(ascii: "{") { depth += 1 } else if b[i] == UInt8(ascii: "}") { depth -= 1 }197 i += 1198 }199 guard i < b.count else { throw SyntaxError(message: "the quoted value opened here is never closed.", position: start - 1) }200 out += str(start..<i)201 i += 1202 } else if Lexer.isDigit(c) {203 let start = i204 while i < b.count, Lexer.isDigit(b[i]) { i += 1 }205 out += str(start..<i)206 } else {207 let pos = i208 let n = name()209 guard !n.isEmpty else { throw SyntaxError(message: "unexpected \"\(Character(UnicodeScalar(c)))\" where a value was expected.", position: pos) }210 if let m = macros[n.lowercased()] { out += m }211 else {212 issues.append("Line \(line(pos)): undefined macro \"\(n)\"; its name is kept as the value.")213 out += n214 }215 }216 skipSpace()217 if i < b.count, b[i] == UInt8(ascii: "#") { i += 1 } else { return out }218 }219 }220221 mutating func entry(type: String, close: UInt8, at: Int) throws {222 skipSpace()223 let keyStart = i224 while i < b.count, b[i] != UInt8(ascii: ","), b[i] != close, b[i] != 0x0A, b[i] != 0x0D { i += 1 }225 var key = str(keyStart..<i).trimmingCharacters(in: .whitespaces)226 var raw = RawEntry(type: type, key: "", line: line(at))227 if key.contains("=") { // "@article{title = {…}}": no key at all228 i = keyStart229 key = ""230 }231 raw.key = key232 var failure: SyntaxError?233 do {234 while true {235 skipSpace()236 guard i < b.count else { throw SyntaxError(message: "entry \"\(key)\" is not closed (end of file reached).", position: at) }237 if b[i] == close { i += 1; break }238 if b[i] == UInt8(ascii: ",") { i += 1; continue }239 let fieldPos = i240 let fname = name().lowercased()241 guard !fname.isEmpty else {242 throw SyntaxError(message: "entry \"\(key)\": unexpected \"\(Character(UnicodeScalar(b[i])))\" where a field name was expected.", position: i)243 }244 skipSpace()245 guard i < b.count, b[i] == UInt8(ascii: "=") else {246 throw SyntaxError(message: "entry \"\(key)\": field \"\(fname)\" has no \"=\" (a comma or a closing delimiter may be missing before it).", position: fieldPos)247 }248 i += 1249 let v = try value(at: fieldPos)250 if raw.values[fname] != nil {251 issues.append("Line \(line(fieldPos)): entry \"\(key)\": field \"\(fname)\" is given twice; the first value is kept.")252 } else {253 raw.set(fname, v)254 }255 skipSpace()256 if i < b.count, b[i] != UInt8(ascii: ","), b[i] != close {257 throw SyntaxError(message: "entry \"\(key)\": missing comma after field \"\(fname)\".", position: i)258 }259 }260 } catch let e as SyntaxError { failure = e }261262 if let failure, raw.names.isEmpty { throw failure }263 if !key.isEmpty, let previous = seenKeys[key] {264 issues.append("Line \(raw.line): duplicate key \"\(key)\" (first defined on line \(previous)); this entry is ignored.")265 } else {266 if !key.isEmpty { seenKeys[key] = raw.line }267 entries.append(raw)268 }269 if let failure {270 issues.append("Line \(line(failure.position)): \(failure.message) The fields read before the error are kept.")271 resync(after: at)272 }273 }274 }275276 // MARK: crossref / xdata277278 enum Inheritance {279 /// Fields BibLaTeX never inherits.280 private static let notInherited: Set<String> = ["crossref", "xref", "xdata", "entryset", "entrysubtype", "execute", "ids", "label", "options", "presort",281 "related", "relatedoptions", "relatedstring", "relatedtype", "shorthand", "shorthandintro", "sortkey", "csltype"]282 private static let containers: Set<String> = ["book", "collection", "proceedings", "reference", "mvbook", "mvcollection", "mvproceedings", "mvreference", "periodical"]283 private static let multivolume: Set<String> = ["mvbook", "mvcollection", "mvproceedings", "mvreference"]284 private static let standalone: Set<String> = ["book", "collection", "proceedings", "reference"]285286 static func resolve(_ input: [RawEntry], issues: inout [String]) -> [RawEntry] {287 guard input.contains(where: { $0.values["crossref"] != nil || $0.values["xdata"] != nil }) else { return input }288 var index: [String: Int] = [:]289 var lowerIndex: [String: Int] = [:]290 for (k, e) in input.enumerated() where !e.key.isEmpty {291 if index[e.key] == nil { index[e.key] = k }292 if lowerIndex[e.key.lowercased()] == nil { lowerIndex[e.key.lowercased()] = k }293 }294 var entries = input295 var state = Array(repeating: 0, count: input.count) // 0 = untouched, 1 = in progress, 2 = done296297 func find(_ key: String) -> Int? { index[key] ?? lowerIndex[key.lowercased()] }298299 func resolveEntry(_ k: Int) {300 guard state[k] == 0 else { return }301 state[k] = 1302 if let x = entries[k].values["xdata"] {303 for name in x.split(separator: ",").map({ $0.trimmingCharacters(in: .whitespacesAndNewlines) }) where !name.isEmpty {304 guard let p = find(name) else {305 issues.append("Line \(entries[k].line): entry \"\(entries[k].key)\": xdata \"\(name)\" does not exist.")306 continue307 }308 if state[p] == 1 { issues.append("Line \(entries[k].line): entry \"\(entries[k].key)\": circular xdata reference through \"\(name)\"."); continue }309 resolveEntry(p)310 for f in entries[p].names where entries[k].values[f] == nil && f != "xdata" { entries[k].set(f, entries[p].values[f]!) }311 }312 entries[k].remove("xdata")313 }314 if let c = entries[k].values["crossref"]?.trimmingCharacters(in: .whitespacesAndNewlines), !c.isEmpty {315 if let p = find(c) {316 if state[p] == 1 {317 issues.append("Line \(entries[k].line): entry \"\(entries[k].key)\": circular crossref through \"\(c)\".")318 } else {319 resolveEntry(p)320 inherit(child: &entries[k], parent: entries[p])321 }322 } else {323 issues.append("Line \(entries[k].line): entry \"\(entries[k].key)\": crossref \"\(c)\" does not exist.")324 }325 }326 state[k] = 2327 }328 for k in entries.indices { resolveEntry(k) }329 return entries330 }331332 /// BibLaTeX inheritance: the parent's title becomes the child's booktitle (or maintitle for multi-volume parents); the rest is copied when missing.333 private static func inherit(child: inout RawEntry, parent: RawEntry) {334 let renames: [String: String]335 if parent.type != child.type, containers.contains(parent.type) {336 if multivolume.contains(parent.type) {337 renames = ["title": "maintitle", "subtitle": "mainsubtitle", "titleaddon": "maintitleaddon"]338 } else if standalone.contains(child.type) {339 renames = [:]340 } else if parent.type == "periodical" {341 renames = ["title": "journaltitle", "subtitle": "journalsubtitle"]342 } else {343 renames = ["title": "booktitle", "subtitle": "booksubtitle", "titleaddon": "booktitleaddon"]344 }345 } else {346 renames = [:]347 }348 let inBook = child.type == "inbook" || child.type == "bookinbook" || child.type == "suppbook"349 for f in parent.names where !notInherited.contains(f) {350 var target = renames[f] ?? f351 if f == "author", parent.type == "book" || parent.type == "mvbook", parent.type != child.type {352 if inBook {353 if child.values["author"] == nil { child.set("author", parent.values[f]!) }354 target = "bookauthor"355 } else if child.type != "book" { continue }356 }357 if !renames.isEmpty, renames[f] == nil, ["shorttitle", "indextitle", "indexsorttitle", "sorttitle"].contains(f) { continue }358 if child.values[target] == nil { child.set(target, parent.values[f]!) }359 }360 }361 }362}363