Repository Public
1// ORIX Docs2// File: Packages/ORIXDocsKit/Sources/DocReferences/BibTeXMapping.swift3// Description: Mapping between BibTeX / BibLaTeX entry types and fields and the CSL types and variables stored in BibEntry,4// in both directions. Unmapped fields keep their original names.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import DocModel1011enum BibTeXMapping {12 static let typeMap: [String: String] = [13 "article": "article-journal", "book": "book", "mvbook": "book", "bookinbook": "chapter", "booklet": "pamphlet",14 "collection": "book", "mvcollection": "book", "reference": "book", "mvreference": "book", "proceedings": "book", "mvproceedings": "book",15 "inbook": "chapter", "incollection": "chapter", "suppbook": "chapter", "suppcollection": "chapter",16 "inproceedings": "paper-conference", "conference": "paper-conference", "inreference": "entry-encyclopedia",17 "manual": "book", "mastersthesis": "thesis", "phdthesis": "thesis", "thesis": "thesis",18 "techreport": "report", "report": "report", "unpublished": "manuscript", "misc": "document",19 "online": "webpage", "electronic": "webpage", "www": "webpage", "patent": "patent", "periodical": "periodical", "suppperiodical": "article-journal",20 "software": "software", "dataset": "dataset", "audio": "song", "music": "song", "video": "motion_picture", "movie": "motion_picture",21 "artwork": "graphic", "image": "graphic", "letter": "personal_communication", "legislation": "legislation", "jurisdiction": "legal_case",22 "standard": "standard", "performance": "performance", "review": "review",23 ]24 /// CSL type → entry type written by `BibTeXWriter`.25 static let reverseTypeMap: [String: String] = [26 "article-journal": "article", "article-magazine": "article", "article-newspaper": "article", "book": "book", "chapter": "incollection",27 "paper-conference": "inproceedings", "entry-encyclopedia": "inreference", "report": "techreport", "manuscript": "unpublished",28 "document": "misc", "webpage": "online", "patent": "patent", "periodical": "periodical", "software": "software", "dataset": "dataset",29 "song": "audio", "motion_picture": "video", "graphic": "artwork", "personal_communication": "letter", "legislation": "legislation",30 "legal_case": "jurisdiction", "standard": "standard", "performance": "performance", "review": "review", "pamphlet": "booklet",31 ]32 static let genreKeys: [String: String] = [33 "phdthesis": "PhD thesis", "mathesis": "Master's thesis", "bathesis": "Bachelor's thesis", "candthesis": "Candidate thesis",34 "techreport": "Technical report", "resreport": "Research report", "software": "Computer software", "datacd": "Data CD", "audiocd": "Audio CD",35 ]36 static let verbatimFields: Set<String> = ["url", "doi", "file", "eprint", "urlraw", "verba", "verbb", "verbc", "pmid", "pmcid", "isbn", "issn", "crossref", "xref",37 "ids", "entryset", "related", "options", "urldate", "eventdate", "origdate", "date", "csltype", "entrysubtype"]38 static let multilineFields: Set<String> = ["abstract", "annote", "annotation", "comment", "review", "file"]39 /// Name-list fields other than author and editor; stored as normalised BibTeX name lists.40 static let nameFields: Set<String> = ["translator", "bookauthor", "editora", "editorb", "editorc", "annotator", "commentator", "introduction", "foreword",41 "afterword", "holder", "namea", "nameb", "namec", "shortauthor", "shorteditor", "sortname"]42 static let articleTypes: Set<String> = ["article-journal", "article-magazine", "article-newspaper", "article", "periodical", "review"]43 static let seriesNumberTypes: Set<String> = ["book", "chapter", "paper-conference", "entry-encyclopedia", "entry-dictionary", "entry"]4445 /// BibTeX field names the mapping consumes; a leftover source field with one of these names is stored as "x-<name>".46 static let reservedNames: Set<String> = {47 var s: Set<String> = ["year", "month", "day", "date", "issue", "number", "author", "editor", "subtitle"]48 for type in ["article-journal", "book", "thesis", "report"] { for (csl, bib) in plan(for: type) { s.insert(csl); s.formUnion(bib) } }49 return s50 }()5152 /// CSL variable → candidate BibTeX fields (the first one is what the writer emits), for a CSL type.53 static func plan(for cslType: String) -> [(csl: String, bib: [String])] {54 let article = articleTypes.contains(cslType)55 var p: [(String, [String])] = [56 ("title", ["title"]),57 ("container-title", article ? ["journal", "journaltitle", "booktitle"] : ["booktitle", "journaltitle", "journal"]),58 ("container-title-short", ["shortjournal"]), ("title-short", ["shorttitle"]), ("collection-title", ["series"]),59 ("volume", ["volume"]),60 ]61 if !article { p.append((seriesNumberTypes.contains(cslType) ? "collection-number" : "number", ["number"])) }62 p += [63 ("page", ["pages"]), ("article-number", ["eid"]), ("edition", ["edition"]), ("genre", ["type"]), ("chapter-number", ["chapter"]),64 ("publisher", cslType == "thesis" ? ["school", "institution", "publisher"]65 : cslType == "report" ? ["institution", "publisher", "organization", "school"] : ["publisher", "organization", "institution", "school"]),66 ("publisher-place", ["address", "location"]),67 ("event-title", ["eventtitle"]), ("event-date", ["eventdate"]), ("event-place", ["venue"]),68 ("number-of-pages", ["pagetotal"]), ("number-of-volumes", ["volumes"]), ("version", ["version"]), ("status", ["pubstate"]),69 ("original-date", ["origdate"]), ("original-title", ["origtitle"]), ("original-publisher", ["origpublisher"]), ("original-publisher-place", ["origlocation"]),70 ("translator", ["translator"]), ("container-author", ["bookauthor"]),71 ("DOI", ["doi"]), ("URL", ["url"]), ("accessed", ["urldate"]), ("ISBN", ["isbn"]), ("ISSN", ["issn"]), ("PMID", ["pmid"]), ("PMCID", ["pmcid"]),72 ("language", ["language"]), ("keyword", ["keywords"]), ("abstract", ["abstract"]), ("note", ["note"]), ("annote", ["annote", "annotation"]),73 ]74 return p75 }7677 static func decodeField(_ name: String, _ raw: String) -> String {78 if verbatimFields.contains(name) { return verbatim(raw) }79 if nameFields.contains(name) || name == "author" || name == "editor" { return NameParser.string(NameParser.parseList(raw, decode: { LaTeXText.decode($0) })) }80 return LaTeXText.decode(raw, collapseWhitespace: !multilineFields.contains(name))81 }8283 /// URLs, DOIs and identifiers: no LaTeX decoding beyond the escapes people add by habit.84 static func verbatim(_ raw: String) -> String {85 var s = LaTeXText.collapse(raw)86 if s.hasPrefix("\\url{"), s.hasSuffix("}") { s = String(s.dropFirst(5).dropLast()) }87 while s.hasPrefix("{"), s.hasSuffix("}"), s.count >= 2 { s = String(s.dropFirst().dropLast()) }88 if s.contains("\\") {89 for (a, b) in [("\\_", "_"), ("\\%", "%"), ("\\#", "#"), ("\\&", "&"), ("\\~{}", "~"), ("\\textasciitilde{}", "~"), ("{\\textasciitilde}", "~"), ("\\textasciitilde ", "~")] {90 s = s.replacingOccurrences(of: a, with: b)91 }92 }93 return s94 }9596 static func joinTitle(_ title: String?, _ subtitle: String?) -> String? {97 guard let title, !title.isEmpty else { return subtitle }98 guard let subtitle, !subtitle.isEmpty else { return title }99 if let last = title.last, "?!:".contains(last) { return title + " " + subtitle }100 return title + ": " + subtitle101 }102103 static func entry(from source: BibTeXParser.RawEntry, issues: inout [String]) -> BibEntry {104 var raw = source105 let where_ = "Line \(raw.line): entry \"\(raw.key)\""106 func pop(_ name: String) -> String? {107 guard let v = raw.values[name] else { return nil }108 raw.remove(name)109 let d = decodeField(name, v)110 return d.isEmpty ? nil : d111 }112113 var entry = BibEntry(key: raw.key, type: "document")114 // Type115 if let t = typeMap[raw.type] {116 entry.type = t117 if raw.type == "article", let sub = raw.values["entrysubtype"].map({ verbatim($0).lowercased() }), sub == "magazine" || sub == "newspaper" {118 entry.type = "article-" + sub119 raw.remove("entrysubtype")120 }121 } else {122 entry.fields[ReferenceField.entryType] = raw.type123 issues.append("\(where_): unknown entry type \"@\(raw.type)\"; kept as a generic document.")124 }125 if let t = pop("csltype") { entry.type = t; entry.fields[ReferenceField.entryType] = nil }126127 // Names128 if let a = raw.values["author"] { entry.authors = NameParser.parseList(a, decode: { LaTeXText.decode($0) }); raw.remove("author") }129 if let e = raw.values["editor"] { entry.editors = NameParser.parseList(e, decode: { LaTeXText.decode($0) }); raw.remove("editor") }130131 // Dates132 if let date = pop("date") {133 if let parsed = RefDate.parseEDTF(date) {134 entry.year = parsed.parts.year; entry.month = parsed.parts.month; entry.day = parsed.parts.day135 if !parsed.exact { entry.fields[ReferenceField.rawDate] = date }136 } else {137 entry.fields[ReferenceField.rawDate] = date138 issues.append("\(where_): the date \"\(date)\" is not an ISO 8601 / EDTF date; kept as text.")139 }140 }141 if let year = pop("year") {142 if entry.year == nil {143 if year.count <= 4, year.allSatisfy(\.isASCIIDigit), let y = Int(year) { entry.year = y }144 else { entry.fields[ReferenceField.issuedLiteral] = year }145 } else if entry.year.map(String.init) != year {146 entry.fields["x-year"] = year147 }148 }149 if let month = pop("month") {150 let (m, d) = RefDate.monthAndDay(month)151 if let m {152 if entry.month == nil { entry.month = m; if entry.day == nil { entry.day = d } }153 } else {154 entry.fields["x-month"] = month155 issues.append("\(where_): the month \"\(month)\" was not understood; kept as text.")156 }157 }158 if let day = pop("day") {159 if let d = Int(day), (1...31).contains(d), entry.month != nil { if entry.day == nil { entry.day = d } } else { entry.fields["x-day"] = day }160 }161162 // Titles (BibLaTeX subtitles are folded into the title)163 if let t = joinTitle(pop("title"), pop("subtitle")) { entry.fields["title"] = t }164 for (main, sub) in [("booktitle", "booksubtitle"), ("journaltitle", "journalsubtitle")] where raw.values[main] != nil && raw.values[sub] != nil {165 let joined = joinTitle(LaTeXText.decode(raw.values[main]!), LaTeXText.decode(raw.values[sub]!)) ?? ""166 raw.remove(sub)167 raw.values[main] = LaTeXText.encode(joined)168 }169170 // Issue and number of periodical articles171 if articleTypes.contains(entry.type) {172 if raw.values["number"] != nil, raw.values["issue"] != nil {173 entry.fields["number"] = pop("number"); entry.fields["issue"] = pop("issue")174 } else if let n = pop("number") ?? pop("issue") { entry.fields["issue"] = n }175 }176177 // Thesis and report genres178 if raw.type == "phdthesis" || raw.type == "mastersthesis", raw.values["type"] == nil {179 entry.fields["genre"] = raw.type == "phdthesis" ? genreKeys["phdthesis"] : genreKeys["mathesis"]180 }181182 for (csl, candidates) in plan(for: entry.type) where entry.fields[csl] == nil {183 for bib in candidates where raw.values[bib] != nil {184 guard var value = pop(bib) else { continue }185 switch csl {186 case "DOI": value = TextFold.bareDOI(value)187 case "genre": value = genreKeys[value.lowercased()] ?? value188 default: break189 }190 entry.fields[csl] = value191 break192 }193 }194 // howpublished that is only a link195 if entry.fields["URL"] == nil, let how = raw.values["howpublished"] {196 let v = verbatim(how)197 if (v.hasPrefix("http://") || v.hasPrefix("https://")) && !v.contains(" ") { entry.fields["URL"] = v; raw.remove("howpublished") }198 }199 // Everything else keeps its original name.200 for name in raw.names {201 guard let value = pop(name) else { continue }202 entry.fields[entry.fields[name] == nil ? name : "x-" + name] = value203 }204 return entry205 }206}207208public enum BibTeXWriter {209 private static let order = ["title", "container-title", "container-title-short", "collection-title", "collection-number", "edition", "volume", "issue", "number",210 "page", "article-number", "genre", "publisher", "publisher-place"]211212 /// Serialises entries as BibTeX that BibLaTeX also reads. UTF-8 text is written as is; only the characters BibTeX treats specially are escaped.213 public static func write(_ entries: [BibEntry]) -> String {214 var out = ""215 out.reserveCapacity(entries.count * 400)216 for (n, e) in entries.enumerated() {217 if n > 0 { out += "\n" }218 write(e, to: &out)219 }220 return out221 }222223 static func safeKey(_ key: String) -> String {224 let cleaned = String(key.unicodeScalars.filter { !CharacterSet.whitespacesAndNewlines.contains($0) && !",{}()%#\"'\\=~".unicodeScalars.contains($0) })225 return cleaned.isEmpty ? "ref" : cleaned226 }227228 private static func balanced(_ s: String) -> Bool {229 var depth = 0230 for u in s.utf8 {231 if u == UInt8(ascii: "{") { depth += 1 } else if u == UInt8(ascii: "}") { depth -= 1; if depth < 0 { return false } }232 }233 return depth == 0234 }235236 static func encodeValue(_ text: String) -> String {237 let e = LaTeXText.encode(text)238 return balanced(e) ? e : LaTeXText.encode(text, strict: true)239 }240241 /// Braces around words with inner capitals ("NASA", "GARCH", "iPhone") so BibTeX styles that re-case titles leave them alone.242 static func protectCase(_ title: String) -> String {243 guard !title.contains("\\"), !title.contains("$"), !title.contains("<"), !title.contains("{"), !title.contains("}") else { return encodeValue(title) }244 return title.split(separator: " ", omittingEmptySubsequences: false).map { word -> String in245 let letters = word.drop(while: { !$0.isLetter })246 let enc = LaTeXText.encode(String(word))247 return letters.dropFirst().contains(where: { $0.isUppercase }) ? "{" + enc + "}" : enc248 }.joined(separator: " ")249 }250251 private static func write(_ e: BibEntry, to out: inout String) {252 var fields = e.fields253 var lines: [(String, String)] = [] // (name, already formatted value including delimiters)254 var emitted = Set<String>()255 func put(_ name: String, _ body: String, bare: Bool = false) {256 var n = name257 while emitted.contains(n) { n = "x-" + n }258 emitted.insert(n)259 lines.append((n, bare ? body : "{" + body + "}"))260 }261 func verbatim(_ v: String) -> String {262 balanced(v) ? v : v.replacingOccurrences(of: "{", with: "%7B").replacingOccurrences(of: "}", with: "%7D")263 }264265 // Type266 var type: String267 if e.type == "thesis" {268 switch fields["genre"] {269 case BibTeXMapping.genreKeys["phdthesis"]: type = "phdthesis"; fields["genre"] = nil270 case BibTeXMapping.genreKeys["mathesis"]: type = "mastersthesis"; fields["genre"] = nil271 default: type = "thesis"272 }273 } else if e.type == "document", let original = fields[ReferenceField.entryType], !original.isEmpty, original.allSatisfy(\.isASCIILetter),274 BibTeXMapping.typeMap[original.lowercased()] == nil, !["string", "comment", "preamble", "xdata"].contains(original.lowercased()) {275 type = original.lowercased()276 fields[ReferenceField.entryType] = nil277 } else {278 type = BibTeXMapping.reverseTypeMap[e.type] ?? "misc"279 }280 if e.type == "article-magazine" { put("entrysubtype", "magazine") }281 if e.type == "article-newspaper" { put("entrysubtype", "newspaper") }282 let readsBackAs = type == "phdthesis" || type == "mastersthesis" ? "thesis"283 : e.type.hasPrefix("article-") ? e.type : (BibTeXMapping.typeMap[type] ?? "document")284 if readsBackAs != e.type { put("csltype", e.type) }285286 if !e.authors.isEmpty { put("author", NameParser.string(e.authors, encode: encodeValue)) }287 if !e.editors.isEmpty { put("editor", NameParser.string(e.editors, encode: encodeValue)) }288289 // Mapped variables290 var mapped: [String: String] = [:]291 for (csl, bib) in BibTeXMapping.plan(for: e.type) { mapped[csl] = bib[0] }292 if BibTeXMapping.articleTypes.contains(e.type) {293 if fields["number"] != nil { mapped["issue"] = "issue"; mapped["number"] = "number" } else { mapped["issue"] = "number" }294 }295 func emit(_ csl: String) {296 guard let value = fields[csl], let bib = mapped[csl] else { return }297 fields[csl] = nil298 if BibTeXMapping.verbatimFields.contains(bib) { put(bib, verbatim(value)) }299 else if BibTeXMapping.nameFields.contains(bib) { put(bib, NameParser.string(NameParser.parseList(value), encode: encodeValue)) }300 else if csl == "title" { put(bib, protectCase(value)) }301 else { put(bib, encodeValue(value)) }302 }303 for csl in order { emit(csl) }304305 // Date306 if let raw = fields[ReferenceField.rawDate] { put("date", verbatim(raw)); fields[ReferenceField.rawDate] = nil }307 if let y = e.year { put("year", String(y)) }308 else if let literal = fields[ReferenceField.issuedLiteral] { put("year", encodeValue(literal)) }309 fields[ReferenceField.issuedLiteral] = e.year == nil ? nil : fields[ReferenceField.issuedLiteral]310 if let m = e.month, (1...12).contains(m) { put("month", RefDate.bibMacros[m - 1], bare: true) }311 if let d = e.day { put("day", String(d)) }312313 for csl in mapped.keys.sorted() { emit(csl) }314 for name in fields.keys.sorted() {315 guard let value = fields[name] else { continue }316 // "x-month", "x-publisher"…: a source field the parser could not store under its own name; it goes back under that name.317 var bib = name.hasPrefix("x-") && BibTeXMapping.reservedNames.contains(String(name.dropFirst(2))) ? String(name.dropFirst(2)) : name318 if bib.isEmpty || !bib.utf8.allSatisfy({ ($0 >= 0x30 && $0 <= 0x39) || ($0 >= 0x41 && $0 <= 0x5A) || ($0 >= 0x61 && $0 <= 0x7A) || $0 == 0x2D || $0 == 0x5F || $0 == 0x3A || $0 == 0x2E }) {319 bib = "x-field"320 }321 let lower = bib.lowercased()322 if BibTeXMapping.verbatimFields.contains(lower) { put(bib, verbatim(value)) }323 else if BibTeXMapping.nameFields.contains(lower) { put(bib, NameParser.string(NameParser.parseList(value), encode: encodeValue)) }324 else { put(bib, encodeValue(value)) }325 }326327 out += "@\(type){\(safeKey(e.key)),\n"328 for (name, value) in lines { out += " \(name) = \(value),\n" }329 out += "}\n"330 }331}332