Repository Public
1// ORIX Docs2// File: Packages/ORIXDocsKit/Sources/DocReferences/CSLJSON.swift3// Description: CSL-JSON reader and writer: names with particles and suffixes, date-parts / raw / literal dates,4// number-or-string tolerance. Variables BibEntry has no slot for stay in `fields` under their CSL names.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import DocModel1011public enum CSLJSON {12 static let nameVariables: Set<String> = ["translator", "container-author", "collection-editor", "composer", "director", "editorial-director", "illustrator",13 "interviewer", "original-author", "recipient", "reviewed-author", "chair", "compiler", "contributor", "curator",14 "guest", "host", "narrator", "organizer", "performer", "producer", "script-writer", "series-creator", "executive-producer"]15 static let dateVariables: Set<String> = ["accessed", "event-date", "original-date", "submitted", "available-date"]1617 public enum WriteError: Error { case notSerialisable }1819 /// Parses a CSL-JSON array (a single item object or an `{"items": [...]}` wrapper is accepted too).20 public static func parse(_ data: Data) -> BibliographyParseResult {21 var result = BibliographyParseResult()22 var bytes = data23 if bytes.starts(with: [0xEF, 0xBB, 0xBF]) { bytes = bytes.dropFirst(3) }24 let root: Any25 do { root = try JSONSerialization.jsonObject(with: Data(bytes), options: [.fragmentsAllowed]) }26 catch {27 result.issues.append("Not valid JSON: \((error as NSError).userInfo[NSDebugDescriptionErrorKey] as? String ?? error.localizedDescription)")28 return result29 }30 let items: [Any]31 if let a = root as? [Any] { items = a }32 else if let d = root as? [String: Any] {33 if let a = d["items"] as? [Any] ?? d["references"] as? [Any] { items = a } else { items = [d] }34 } else {35 result.issues.append("The JSON document is not a CSL-JSON array of items.")36 return result37 }38 var used = Set<String>()39 for (n, any) in items.enumerated() {40 guard let obj = any as? [String: Any] else {41 result.issues.append("Item \(n + 1): not a JSON object; ignored.")42 continue43 }44 var entry = entry(from: obj, index: n + 1, issues: &result.issues)45 if entry.key.isEmpty {46 entry.key = ReferenceChecks.suggestedKey(for: entry, existing: used)47 result.issues.append("Item \(n + 1): no \"id\"; the key \"\(entry.key)\" was generated.")48 } else if used.contains(entry.key) {49 let renamed = BibliographyImporter.uniqueKey(entry.key, existing: used)50 result.issues.append("Item \(n + 1): duplicate id \"\(entry.key)\"; this item is kept as \"\(renamed)\".")51 entry.key = renamed52 }53 used.insert(entry.key)54 result.entries.append(entry)55 }56 return result57 }5859 private static func string(_ any: Any) -> String? {60 if let s = any as? String { return s }61 if let n = any as? NSNumber {62 if CFGetTypeID(n) == CFBooleanGetTypeID() { return n.boolValue ? "true" : "false" }63 let d = n.doubleValue64 return d == d.rounded() && abs(d) < 1e15 ? String(Int64(d)) : n.stringValue65 }66 return nil67 }6869 private static func int(_ any: Any?) -> Int? {70 guard let any else { return nil }71 if let n = any as? NSNumber, !(any is String) { return n.intValue }72 if let s = any as? String { return Int(s.trimmingCharacters(in: .whitespaces)) }73 return nil74 }7576 private static func name(_ any: Any) -> PersonName? {77 if let s = any as? String { return s.isEmpty ? nil : PersonName(family: "", given: "", literal: s) }78 guard let d = any as? [String: Any] else { return nil }79 func part(_ k: String) -> String { (d[k].flatMap(string) ?? "").trimmingCharacters(in: .whitespaces) }80 let literal = part("literal")81 if !literal.isEmpty { return literal == "others" ? .others : PersonName(family: "", given: "", literal: literal) }82 let family = [part("non-dropping-particle"), part("family")].filter { !$0.isEmpty }.joined(separator: " ")83 var given = [part("given"), part("dropping-particle")].filter { !$0.isEmpty }.joined(separator: " ")84 let suffix = part("suffix")85 if !suffix.isEmpty { given = given.isEmpty ? suffix : given + ", " + suffix }86 if family.isEmpty && given.isEmpty { return nil }87 return PersonName(family: family, given: given)88 }8990 private static func names(_ any: Any) -> [PersonName] {91 if let a = any as? [Any] { return a.compactMap(name) }92 return name(any).map { [$0] } ?? []93 }9495 private struct ParsedDate {96 var parts = RefDate.Parts()97 var end: RefDate.Parts?98 var raw: String? // inexact EDTF to keep99 var literal: String?100 var season: String?101 }102103 private static func date(_ any: Any) -> ParsedDate? {104 var out = ParsedDate()105 func fromText(_ s: String) {106 if let e = RefDate.parseEDTF(s) { out.parts = e.parts; if !e.exact { out.raw = s } }107 else if let p = RefDate.parseLoose(s) { out.parts = p }108 else { out.literal = s }109 }110 if let s = any as? String { fromText(s); return out }111 if let n = any as? NSNumber { out.parts.year = n.intValue; return out }112 guard let d = any as? [String: Any] else { return nil }113 func triple(_ any: Any) -> RefDate.Parts? {114 guard let a = any as? [Any], let y = int(a.first) else { return nil }115 var p = RefDate.Parts(year: y)116 if a.count > 1, let m = int(a[1]), (1...12).contains(m) { p.month = m }117 if a.count > 2, p.month != nil, let dd = int(a[2]), (1...31).contains(dd) { p.day = dd }118 return p119 }120 if let dp = d["date-parts"] as? [Any], let first = dp.first, let p = triple(first) {121 out.parts = p122 if dp.count > 1 { out.end = triple(dp[1]) }123 if let raw = d["raw"] as? String, let e = RefDate.parseEDTF(raw), !e.exact, e.parts == p { out.raw = raw }124 else if let end = out.end, let a = RefDate.iso(p), let b = RefDate.iso(end) { out.raw = a + "/" + b }125 else if (d["circa"].flatMap(string) ?? "false") != "false", let a = RefDate.iso(p) { out.raw = a + "~" }126 } else if let raw = d["raw"].flatMap(string), !raw.isEmpty { fromText(raw) }127 else if let lit = d["literal"].flatMap(string), !lit.isEmpty { out.literal = lit }128 else if d["season"] == nil { return nil }129 if let s = d["season"].flatMap(string), !s.isEmpty { out.season = s }130 return out131 }132133 private static func entry(from obj: [String: Any], index: Int, issues: inout [String]) -> BibEntry {134 var entry = BibEntry(key: (obj["id"].flatMap(string) ?? "").trimmingCharacters(in: .whitespaces), type: "document")135 if let t = obj["type"] as? String, !t.isEmpty { entry.type = t }136 else { issues.append("Item \(index) (\(entry.key)): no \"type\"; kept as a generic document.") }137 for key in obj.keys.sorted() {138 guard let value = obj[key], !(value is NSNull) else { continue }139 switch key {140 case "id", "type": continue141 case "author": entry.authors = names(value)142 case "editor": entry.editors = names(value)143 case "issued":144 guard let d = date(value) else { issues.append("Item \(index) (\(entry.key)): the \"issued\" date was not understood; ignored."); continue }145 entry.year = d.parts.year; entry.month = d.parts.month; entry.day = d.parts.day146 if let raw = d.raw { entry.fields[ReferenceField.rawDate] = raw }147 if let lit = d.literal { entry.fields[ReferenceField.issuedLiteral] = lit }148 if let s = d.season { entry.fields["season"] = s }149 default:150 if nameVariables.contains(key) {151 let list = names(value)152 if !list.isEmpty { entry.fields[key] = NameParser.string(list) }153 } else if dateVariables.contains(key) {154 if let d = date(value) {155 if let raw = d.raw { entry.fields[key] = raw }156 else if let iso = RefDate.iso(d.parts) { entry.fields[key] = iso }157 else if let lit = d.literal { entry.fields[key] = lit }158 } else { issues.append("Item \(index) (\(entry.key)): the \"\(key)\" date was not understood; ignored.") }159 } else if let s = string(value) {160 let v = key == "DOI" ? TextFold.bareDOI(s) : s161 if !v.isEmpty { entry.fields[key] = v }162 } else if JSONSerialization.isValidJSONObject(value),163 let d = try? JSONSerialization.data(withJSONObject: value, options: [.sortedKeys, .withoutEscapingSlashes]) {164 entry.fields[key] = String(decoding: d, as: UTF8.self)165 issues.append("Item \(index) (\(entry.key)): \"\(key)\" is structured data; kept as JSON text.")166 }167 }168 }169 return entry170 }171172 // MARK: Writing173174 /// Writes a CSL-JSON array (pretty-printed, keys sorted, so the output is stable).175 public static func write(_ entries: [BibEntry]) throws -> Data {176 let items = entries.map(object)177 guard JSONSerialization.isValidJSONObject(items) else { throw WriteError.notSerialisable }178 return try JSONSerialization.data(withJSONObject: items, options: [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes])179 }180181 static func nameObject(_ n: PersonName) -> [String: Any] {182 if n.isOthers { return ["literal": "others"] }183 if let l = n.literal, !l.isEmpty { return ["literal": l] }184 var d: [String: Any] = [:]185 if !n.family.isEmpty { d["family"] = n.family }186 let (given, suffix) = n.givenAndSuffix187 if !given.isEmpty { d["given"] = given }188 if let suffix { d["suffix"] = suffix }189 return d190 }191192 private static func dateParts(_ p: RefDate.Parts) -> [Any] {193 var a: [Any] = []194 if let y = p.year { a.append(y); if let m = p.month { a.append(m); if let d = p.day { a.append(d) } } }195 return a196 }197198 private static func dateObject(_ text: String) -> [String: Any] {199 if let e = RefDate.parseEDTF(text) {200 var d: [String: Any] = ["date-parts": [dateParts(e.parts)] + (RefDate.rangeEnd(text).map { [dateParts($0)] } ?? [])]201 if !e.exact { d["raw"] = text }202 return d203 }204 return ["literal": text]205 }206207 private static func object(_ e: BibEntry) -> [String: Any] {208 var o: [String: Any] = ["id": e.key, "type": e.type]209 var f = e.fields210 if !e.authors.isEmpty { o["author"] = e.authors.map(nameObject) }211 if !e.editors.isEmpty { o["editor"] = e.editors.map(nameObject) }212 var issued: [String: Any] = [:]213 if e.year != nil {214 let parts = RefDate.Parts(year: e.year, month: e.month, day: e.day)215 var dp: [Any] = [dateParts(parts)]216 if let raw = f[ReferenceField.rawDate], let parsed = RefDate.parseEDTF(raw), parsed.parts == parts, !parsed.exact {217 if let end = RefDate.rangeEnd(raw) { dp.append(dateParts(end)) }218 issued["raw"] = raw219 f[ReferenceField.rawDate] = nil220 }221 issued["date-parts"] = dp222 } else if let lit = f[ReferenceField.issuedLiteral] {223 issued["literal"] = lit224 f[ReferenceField.issuedLiteral] = nil225 }226 if let s = f["season"] { issued["season"] = s; f["season"] = nil }227 if !issued.isEmpty { o["issued"] = issued }228 for (k, v) in f {229 if nameVariables.contains(k) { o[k] = NameParser.parseList(v).map(nameObject) }230 else if dateVariables.contains(k) { o[k] = dateObject(v) }231 else { o[k] = v }232 }233 return o234 }235}236