SPB Git

Repository Public

RIS.swift 16.2 KB 281 lines swift

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
Files main
Menu

Theme