Repository Public
1// ORIX Docs2// File: Packages/ORIXDocsKit/Sources/DocReferences/RIS.swift3// Description: RIS (Research Information Systems) tagged format: parser and writer, with the type mapping to and from CSL types.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai7import Foundation8import DocModel910enum RISMapping {11 static let toCSL: [String: String] = [12 "JOUR": "article-journal", "EJOUR": "article-journal", "ABST": "article-journal", "INPR": "article-journal", "JFULL": "periodical",13 "MGZN": "article-magazine", "NEWS": "article-newspaper", "BOOK": "book", "EBOOK": "book", "EDBOOK": "book", "SER": "book",14 "CHAP": "chapter", "ECHAP": "chapter", "CONF": "paper-conference", "CPAPER": "paper-conference", "THES": "thesis",15 "RPRT": "report", "GOVDOC": "report", "ELEC": "webpage", "BLOG": "post-weblog", "GEN": "document", "UNPB": "manuscript", "MANSCPT": "manuscript",16 "PAT": "patent", "DATA": "dataset", "AGGR": "dataset", "DBASE": "dataset", "COMP": "software", "ENCYC": "entry-encyclopedia", "DICT": "entry-dictionary",17 "MAP": "map", "MPCT": "motion_picture", "VIDEO": "motion_picture", "ADVS": "motion_picture", "SOUND": "song", "MUSIC": "musical_score",18 "BILL": "bill", "UNBILL": "bill", "CASE": "legal_case", "STAT": "legislation", "LEGAL": "legislation", "HEAR": "hearing",19 "PCOMM": "personal_communication", "ICOMM": "personal_communication", "SLIDE": "speech", "STAND": "standard", "ART": "graphic",20 "PAMP": "pamphlet", "CHART": "figure", "FIGURE": "figure", "CLSWK": "classic", "CTLG": "document", "EQUA": "document", "MULTI": "document",21 ]22 static let fromCSL: [String: String] = [23 "article-journal": "JOUR", "article": "JOUR", "periodical": "JFULL", "article-magazine": "MGZN", "article-newspaper": "NEWS", "book": "BOOK",24 "chapter": "CHAP", "paper-conference": "CONF", "thesis": "THES", "report": "RPRT", "webpage": "ELEC", "post-weblog": "BLOG", "post": "ELEC",25 "document": "GEN", "manuscript": "UNPB", "patent": "PAT", "dataset": "DATA", "software": "COMP", "entry-encyclopedia": "ENCYC",26 "entry-dictionary": "DICT", "entry": "ENCYC", "map": "MAP", "motion_picture": "MPCT", "song": "SOUND", "musical_score": "MUSIC", "bill": "BILL",27 "legal_case": "CASE", "legislation": "STAT", "hearing": "HEAR", "personal_communication": "PCOMM", "speech": "SLIDE", "standard": "STAND",28 "graphic": "ART", "pamphlet": "PAMP", "figure": "FIGURE", "classic": "CLSWK",29 ]30 static let journalTypes: Set<String> = ["article-journal", "article-magazine", "article-newspaper", "periodical", "article"]31 /// Single-valued tags that map straight to a CSL variable.32 static let simple: [(tag: String, csl: String)] = [33 ("VL", "volume"), ("IS", "issue"), ("DO", "DOI"), ("UR", "URL"), ("PB", "publisher"), ("CY", "publisher-place"), ("ET", "edition"),34 ("M3", "genre"), ("LA", "language"), ("ST", "title-short"), ("T3", "collection-title"), ("NV", "number-of-volumes"), ("CN", "call-number"),35 ("AN", "accession"), ("DB", "archive"), ("DP", "source"), ("Y2", "accessed"), ("JA", "container-title-short"), ("C7", ReferenceField.articleNumber),36 ]37}3839public enum RISParser {40 /// Parses RIS records. Records end at `ER`; a missing `ER` before the next `TY` or the end of file is reported and tolerated.41 public static func parse(_ text: String) -> BibliographyParseResult {42 var result = BibliographyParseResult()43 var used = Set<String>()44 var current: [(tag: String, value: String)] = []45 var startLine = 046 var open = false4748 func finish() {49 guard open else { return }50 var entry = entry(from: current, line: startLine, issues: &result.issues)51 if entry.key.isEmpty { entry.key = ReferenceChecks.suggestedKey(for: entry, existing: used) }52 else if used.contains(entry.key) {53 let renamed = BibliographyImporter.uniqueKey(entry.key, existing: used)54 result.issues.append("Line \(startLine): duplicate ID \"\(entry.key)\"; this record is kept as \"\(renamed)\".")55 entry.key = renamed56 }57 used.insert(entry.key)58 result.entries.append(entry)59 current = []60 open = false61 }6263 var lineNumber = 064 for rawLine in text.split(omittingEmptySubsequences: false, whereSeparator: \.isNewline) {65 lineNumber += 166 var line = Substring(rawLine)67 if lineNumber == 1, line.hasPrefix("\u{FEFF}") { line = line.dropFirst() }68 if let (tag, value) = tagged(line) {69 if tag == "TY" {70 if open {71 result.issues.append("Line \(lineNumber): a new record starts before the previous one (line \(startLine)) was closed with ER.")72 finish()73 }74 open = true75 startLine = lineNumber76 current = [(tag, value)]77 } else if tag == "ER" {78 if open { finish() } else { result.issues.append("Line \(lineNumber): ER without a record.") }79 } else if open {80 current.append((tag, value))81 } else if !value.isEmpty {82 result.issues.append("Line \(lineNumber): tag \(tag) outside a record (no TY before it); ignored.")83 }84 } else {85 let trimmed = line.trimmingCharacters(in: .whitespaces)86 guard !trimmed.isEmpty else { continue }87 if open, !current.isEmpty {88 let last = current.count - 189 current[last].value += (current[last].value.isEmpty ? "" : " ") + trimmed // continuation line90 } else {91 result.issues.append("Line \(lineNumber): text outside a record; ignored.")92 }93 }94 }95 if open {96 result.issues.append("Line \(startLine): the last record is not closed with ER.")97 finish()98 }99 return result100 }101102 /// "TY - JOUR": two tag characters, white space, a hyphen and the value.103 private static func tagged(_ line: Substring) -> (String, String)? {104 let u = Array(line.utf8.prefix(6))105 guard u.count >= 5 else {106 // "ER -" may come without the trailing space; "ER" alone is accepted too.107 let t = line.trimmingCharacters(in: .whitespaces)108 return t == "ER" || t == "ER -" || t == "ER -" ? ("ER", "") : nil109 }110 func upperOrDigit(_ c: UInt8) -> Bool { (c >= 0x41 && c <= 0x5A) || (c >= 0x30 && c <= 0x39) }111 guard u[0] >= 0x41, u[0] <= 0x5A, upperOrDigit(u[1]), u[2] == 0x20 else { return nil }112 var k = 3113 if u[k] == 0x20 { k += 1 }114 guard k < u.count, u[k] == UInt8(ascii: "-") else { return nil }115 let tag = String(decoding: u[0..<2], as: UTF8.self)116 let rest = line.utf8.dropFirst(k + 1)117 return (tag, String(Substring(rest)).trimmingCharacters(in: .whitespaces))118 }119120 static func name(_ raw: String) -> PersonName? {121 let parts = raw.split(separator: ",", omittingEmptySubsequences: false).map { $0.trimmingCharacters(in: .whitespaces) }122 guard let family = parts.first, !raw.trimmingCharacters(in: .whitespaces).isEmpty else { return nil }123 if parts.count == 1 {124 if family.lowercased() == "et al." || family.lowercased() == "others" { return .others }125 // RIS names are "Family, Given"; a value without a comma is a single name or an institution and is kept verbatim.126 return PersonName(family: "", given: "", literal: family)127 }128 let given = parts[1]129 let suffix = parts.count > 2 ? parts[2...].joined(separator: ", ") : ""130 return PersonName(family: family, given: [given, suffix].filter { !$0.isEmpty }.joined(separator: ", "))131 }132133 private static func entry(from tags: [(tag: String, value: String)], line: Int, issues: inout [String]) -> BibEntry {134 var entry = BibEntry(key: "", type: "document")135 var multi: [String: [String]] = [:]136 var order: [String] = []137 for (tag, value) in tags where !value.isEmpty {138 if multi[tag] == nil { order.append(tag) }139 multi[tag, default: []].append(value)140 }141 func first(_ tag: String) -> String? { multi[tag]?.first }142 var consumed = Set<String>(["TY"])143 func take(_ tag: String) -> String? {144 guard let v = multi[tag]?.first else { return nil }145 consumed.insert(tag)146 return v147 }148149 let ty = (first("TY") ?? "").uppercased()150 if let t = RISMapping.toCSL[ty] { entry.type = t } else {151 entry.fields["TY"] = ty152 issues.append("Line \(line): unknown reference type \"\(ty)\"; kept as a generic document.")153 }154 let journal = RISMapping.journalTypes.contains(entry.type)155156 if let id = take("ID") { entry.key = id.filter { !$0.isWhitespace } }157 for tag in ["AU", "A1"] { for v in multi[tag] ?? [] { if let n = name(v) { entry.authors.append(n) } }; consumed.insert(tag) }158 for tag in ["A2", "ED"] { for v in multi[tag] ?? [] { if let n = name(v) { entry.editors.append(n) } }; consumed.insert(tag) }159 for (tag, csl) in [("A3", "collection-editor"), ("A4", "translator")] {160 if let values = multi[tag] {161 entry.fields[csl] = NameParser.string(values.compactMap(name))162 consumed.insert(tag)163 }164 }165166 // Dates167 for tag in ["PY", "Y1", "DA"] {168 guard let v = take(tag) else { continue }169 if let (parts, rest) = RefDate.parseRIS(v) {170 if entry.year == nil { entry.year = parts.year }171 if entry.year == parts.year, entry.month == nil, parts.month != nil { entry.month = parts.month; entry.day = parts.day }172 if !rest.isEmpty, entry.fields["season"] == nil { entry.fields["season"] = rest }173 } else if let parts = RefDate.parseLoose(v) {174 if entry.year == nil { entry.year = parts.year }175 if entry.year == parts.year, entry.month == nil, parts.month != nil { entry.month = parts.month; entry.day = parts.day }176 } else if entry.fields[ReferenceField.issuedLiteral] == nil {177 entry.fields[ReferenceField.issuedLiteral] = v178 }179 }180 if entry.year != nil, let literal = entry.fields[ReferenceField.issuedLiteral] {181 entry.fields[ReferenceField.issuedLiteral] = nil182 entry.fields["x-date"] = literal183 }184185 // Titles186 if let t = take("TI") ?? take("T1") ?? (entry.type == "book" ? take("BT") : nil) { entry.fields["title"] = t }187 if journal {188 if let j = take("JF") ?? take("JO") ?? take("T2") ?? take("J2") ?? take("J1") { entry.fields["container-title"] = j }189 } else if entry.type == "book" || entry.type == "report" || entry.type == "thesis" {190 if let s = take("T2"), entry.fields["collection-title"] == nil { entry.fields["collection-title"] = s }191 } else if let c = take("T2") ?? take("BT") ?? take("JF") ?? take("JO") {192 entry.fields["container-title"] = c193 }194195 // Pages196 let sp = take("SP"), ep = take("EP")197 if let sp {198 entry.fields["page"] = ep.map { $0 == sp ? sp : sp + "–" + $0 } ?? sp.replacingOccurrences(of: "--", with: "–").replacingOccurrences(of: "-", with: "–")199 } else if let ep { entry.fields["page"] = ep }200201 if let sn = take("SN") { entry.fields[journal ? "ISSN" : "ISBN"] = sn }202 if let ab = take("AB") ?? take("N2") { entry.fields["abstract"] = ab }203 if let kw = multi["KW"] { entry.fields["keyword"] = kw.joined(separator: "; "); consumed.insert("KW") }204 if let n1 = multi["N1"] { entry.fields["note"] = n1.joined(separator: "\n"); consumed.insert("N1") }205 for (tag, csl) in RISMapping.simple {206 guard entry.fields[csl] == nil, var v = take(tag) else { continue }207 if csl == "DOI" { v = TextFold.bareDOI(v) }208 if csl == "accessed", let p = RefDate.parseRIS(v)?.parts ?? RefDate.parseLoose(v), let iso = RefDate.iso(p) { v = iso }209 entry.fields[csl] = v210 }211 if entry.type == "report" || entry.type == "patent", let n = take("M1") { entry.fields["number"] = n }212213 // Tags without a slot keep their name; repeated ones are joined with a line break.214 for tag in order where !consumed.contains(tag) {215 entry.fields[tag] = multi[tag]!.joined(separator: "\n")216 }217 return entry218 }219}220221public enum RISWriter {222 /// Serialises entries as RIS. Variables without an RIS tag are not written (RIS has no free-form field); see docs/architecture/references.md.223 public static func write(_ entries: [BibEntry]) -> String {224 var out = ""225 for e in entries {226 var f = e.fields227 func line(_ tag: String, _ value: String?) {228 guard let value, !value.isEmpty else { return }229 // A value must stay on its tag line: line breaks would be read back as continuation or as tags.230 out += tag + " - " + value.replacingOccurrences(of: "\r\n", with: " ").replacingOccurrences(of: "\n", with: " ").replacingOccurrences(of: "\r", with: " ") + "\n"231 }232 func take(_ name: String) -> String? { let v = f[name]; f[name] = nil; return v }233 func risName(_ n: PersonName) -> String {234 if n.isOthers { return "et al." }235 if let l = n.literal, !l.isEmpty { return l }236 let (given, suffix) = n.givenAndSuffix237 if let suffix { return n.family + ", " + given + ", " + suffix }238 return given.isEmpty ? n.family + "," : n.family + ", " + given239 }240 let journal = RISMapping.journalTypes.contains(e.type)241 let ty = e.type == "document" ? (take("TY") ?? "GEN") : (RISMapping.fromCSL[e.type] ?? "GEN")242 out += "TY - \(ty)\n"243 line("ID", e.key)244 for a in e.authors { line("AU", risName(a)) }245 for ed in e.editors { line("A2", risName(ed)) }246 if let v = take("collection-editor") { for n in NameParser.parseList(v) { line("A3", risName(n)) } }247 if let v = take("translator") { for n in NameParser.parseList(v) { line("A4", risName(n)) } }248 line("TI", take("title"))249 if let c = take("container-title") { line(journal ? "JF" : "T2", c) }250 if !journal, e.type == "book" || e.type == "report" || e.type == "thesis", let s = take("collection-title") { line("T2", s) }251 if let y = e.year {252 line("PY", RefDate.pad(y, 4))253 if let m = e.month {254 line("DA", "\(RefDate.pad(y, 4))/\(RefDate.pad(m, 2))/\(e.day.map { RefDate.pad($0, 2) } ?? "")/\(take("season") ?? "")")255 } else if let season = take("season") { line("DA", "\(RefDate.pad(y, 4))///\(season)") }256 } else { line("PY", take(ReferenceField.issuedLiteral)) }257 if let page = take("page") {258 if let r = page.range(of: "–") ?? page.range(of: "-") {259 line("SP", String(page[..<r.lowerBound])); line("EP", String(page[r.upperBound...]))260 } else { line("SP", page) }261 }262 line("SN", take(journal ? "ISSN" : "ISBN"))263 line("AB", take("abstract"))264 if let kw = take("keyword") { for k in kw.split(separator: ";") { line("KW", k.trimmingCharacters(in: .whitespaces)) } }265 if let note = take("note") { for n in note.split(separator: "\n") { line("N1", String(n)) } }266 for (tag, csl) in RISMapping.simple { line(tag, take(csl)) }267 if e.type == "report" || e.type == "patent" { line("M1", take("number")) }268 for name in f.keys.sorted() where isTag(name) {269 for v in f[name]!.split(separator: "\n") { line(name, String(v)) }270 }271 out += "ER - \n\n"272 }273 return out274 }275276 private static func isTag(_ name: String) -> Bool {277 let u = Array(name.utf8)278 return u.count == 2 && u[0] >= 0x41 && u[0] <= 0x5A && ((u[1] >= 0x41 && u[1] <= 0x5A) || (u[1] >= 0x30 && u[1] <= 0x39))279 }280}281