Repository Public
1// ORIX Docs2// File: Packages/ORIXDocsKit/Sources/DocReferences/ReferenceSupport.swift3// Description: Shared helpers of the references engine: the parse result type, date parsing (EDTF, RIS, loose text), month names,4// DOI normalisation and text folding used for sorting, keys and duplicate detection.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import DocModel1011/// Result of parsing a bibliography file. `issues` are human-readable problems (with line numbers where the format has lines);12/// a parser never invents data to fill a gap.13public struct BibliographyParseResult: Sendable {14 public var entries: [BibEntry]15 public var issues: [String]16 public init(entries: [BibEntry] = [], issues: [String] = []) { self.entries = entries; self.issues = issues }17}1819/// Non-CSL field names the engine uses to keep information `BibEntry` has no slot for.20public enum ReferenceField {21 /// A publication date that is not a plain year ("in press", "forthcoming", "ca. 1850").22 public static let issuedLiteral = "issued-literal"23 /// The original EDTF date when year/month/day cannot represent it exactly (ranges, seasons, uncertainty).24 public static let rawDate = "date"25 /// Article number of a journal article without page numbers (BibLaTeX `eid`).26 public static let articleNumber = "article-number"27 /// BibTeX entry type that has no CSL equivalent.28 public static let entryType = "entrytype"29}3031enum RefDate {32 struct Parts: Equatable { var year: Int?; var month: Int?; var day: Int? }3334 static let monthsEN = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]35 static let monthsFR = ["janvier", "février", "mars", "avril", "mai", "juin", "juillet", "août", "septembre", "octobre", "novembre", "décembre"]36 static let bibMacros = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"]3738 private static let monthLookup: [String: Int] = {39 var d: [String: Int] = [:]40 for (i, m) in monthsEN.enumerated() { d[m.lowercased()] = i + 1; d[String(m.lowercased().prefix(3))] = i + 1 }41 for (i, m) in monthsFR.enumerated() { d[TextFold.fold(m)] = i + 1 }42 for (k, v) in ["sept": 9, "janv": 1, "fevr": 2, "fev": 2, "avr": 4, "juil": 7, "aout": 8, "dec": 12, "juill": 7] { d[k] = v }43 return d44 }()4546 static func monthNumber(_ name: String) -> Int? { monthLookup[TextFold.fold(name).trimmingCharacters(in: CharacterSet(charactersIn: "."))] }4748 /// A BibTeX `month` value: a number, a name, an abbreviation, optionally with a day ("jan 15", "15~January").49 static func monthAndDay(_ text: String) -> (month: Int?, day: Int?) {50 let tokens = text.split(whereSeparator: { !($0.isLetter || $0.isNumber) }).map(String.init)51 var month: Int?, numbers: [Int] = []52 for t in tokens {53 if let n = Int(t) { numbers.append(n) } else if month == nil, let m = monthNumber(t) { month = m } else { return (nil, nil) }54 }55 if let month {56 guard numbers.count <= 1 else { return (nil, nil) }57 if let d = numbers.first { return (1...31).contains(d) ? (month, d) : (nil, nil) }58 return (month, nil)59 }60 if numbers.count == 1, (1...12).contains(numbers[0]) { return (numbers[0], nil) }61 return (nil, nil)62 }6364 /// ISO 8601 / EDTF level 0–1 date. `exact` is false when year/month/day lose information (range, season, uncertainty, time).65 static func parseEDTF(_ raw: String) -> (parts: Parts, exact: Bool)? {66 let s = raw.trimmingCharacters(in: .whitespaces)67 guard !s.isEmpty else { return nil }68 var exact = true69 var first = Substring(s)70 if let slash = s.firstIndex(of: "/") { first = s[..<slash]; exact = false }71 if let t = first.firstIndex(of: "T") { first = first[..<t]; exact = false }72 while let l = first.last, l == "?" || l == "~" || l == "%" { first = first.dropLast(); exact = false }73 var negative = false74 if first.hasPrefix("-") { negative = true; first = first.dropFirst() }75 let comps = first.split(separator: "-", omittingEmptySubsequences: false)76 guard (1...3).contains(comps.count), comps[0].count == 4, comps[0].allSatisfy(\.isASCIIDigit), var y = Int(comps[0]) else { return nil }77 if negative { y = -y }78 var parts = Parts(year: y)79 if comps.count >= 2 {80 guard comps[1].count == 2, let m = Int(comps[1]) else { return nil }81 if (1...12).contains(m) { parts.month = m } else if (21...41).contains(m) { exact = false } else { return nil }82 }83 if comps.count == 3 {84 guard comps[2].count == 2, let d = Int(comps[2]), (1...31).contains(d), parts.month != nil else { return nil }85 parts.day = d86 }87 return (parts, exact)88 }8990 /// The end of an EDTF range ("2020-03-15/2020-03-20"), when present and parseable.91 static func rangeEnd(_ raw: String) -> Parts? {92 guard let slash = raw.firstIndex(of: "/") else { return nil }93 return parseEDTF(String(raw[raw.index(after: slash)...]))?.parts94 }9596 /// RIS date: "YYYY/MM/DD/other info"; every part optional.97 static func parseRIS(_ raw: String) -> (parts: Parts, rest: String)? {98 let comps = raw.trimmingCharacters(in: .whitespaces).split(separator: "/", maxSplits: 3, omittingEmptySubsequences: false).map { $0.trimmingCharacters(in: .whitespaces) }99 guard let first = comps.first, first.count == 4, let y = Int(first) else { return nil }100 var p = Parts(year: y)101 if comps.count > 1, let m = Int(comps[1]), (1...12).contains(m) { p.month = m }102 if comps.count > 2, p.month != nil, let d = Int(comps[2]), (1...31).contains(d) { p.day = d }103 return (p, comps.count > 3 ? comps[3] : "")104 }105106 /// Dates as people type them: ISO, RIS slashes, "March 15, 2020", "15 mars 2020", "2020".107 static func parseLoose(_ raw: String) -> Parts? {108 let s = raw.trimmingCharacters(in: .whitespaces)109 if let e = parseEDTF(s), e.exact { return e.parts }110 if s.contains("/"), let r = parseRIS(s), r.rest.isEmpty { return r.parts }111 let tokens = s.split(whereSeparator: { !($0.isLetter || $0.isNumber) }).map(String.init)112 var p = Parts()113 var small: [Int] = []114 for t in tokens {115 if let n = Int(t) {116 if t.count == 4, p.year == nil { p.year = n } else { small.append(n) }117 } else if p.month == nil, let m = monthNumber(t) { p.month = m } else { return nil }118 }119 guard p.year != nil, small.count <= 1 else { return nil }120 if let d = small.first {121 guard p.month != nil, (1...31).contains(d) else { return nil }122 p.day = d123 }124 return p125 }126127 static func iso(_ p: Parts) -> String? {128 guard let y = p.year else { return nil }129 var s = y < 0 ? "-" + pad(-y, 4) : pad(y, 4)130 if let m = p.month { s += "-" + pad(m, 2); if let d = p.day { s += "-" + pad(d, 2) } }131 return s132 }133134 static func pad(_ n: Int, _ width: Int) -> String {135 let s = String(n)136 return s.count >= width ? s : String(repeating: "0", count: width - s.count) + s137 }138}139140extension Character {141 var isASCIIDigit: Bool { ("0"..."9").contains(self) }142}143144enum TextFold {145 private static let special: [Character: String] = ["ø": "o", "æ": "ae", "œ": "oe", "ß": "ss", "ł": "l", "đ": "d", "ð": "d", "þ": "th", "ı": "i"]146147 /// Lower-case, diacritics removed, a few letters transliterated to ASCII.148 static func fold(_ s: String) -> String {149 if s.utf8.allSatisfy({ $0 < 0x80 }) { return s.lowercased() }150 let base = s.folding(options: [.diacriticInsensitive, .caseInsensitive, .widthInsensitive], locale: nil)151 var out = ""152 for ch in base { if let r = special[ch] { out += r } else { out.append(ch) } }153 return out154 }155156 /// Letters and digits only: the form used to compare titles.157 static func alphanumeric(_ s: String) -> String { String(fold(stripMarkup(s)).filter { $0.isLetter || $0.isNumber }) }158159 /// Removes the rich-text tags a title may carry.160 static func stripMarkup(_ s: String) -> String {161 guard s.contains("<") else { return s }162 var out = s163 for tag in ["<i>", "</i>", "<b>", "</b>", "<sup>", "</sup>", "<sub>", "</sub>", LaTeXText.smallCapsOpen, LaTeXText.smallCapsClose] {164 out = out.replacingOccurrences(of: tag, with: "")165 }166 return out167 }168169 /// Bare DOI: resolver prefixes and the "doi:" label are removed.170 static func bareDOI(_ raw: String) -> String {171 var s = raw.trimmingCharacters(in: .whitespacesAndNewlines)172 let lower = s.lowercased()173 for prefix in ["https://doi.org/", "http://doi.org/", "https://dx.doi.org/", "http://dx.doi.org/", "doi.org/", "doi:"] where lower.hasPrefix(prefix) {174 s = String(s.dropFirst(prefix.count)).trimmingCharacters(in: .whitespaces)175 break176 }177 return s178 }179}180