SPB Git

Repository Public

BibTeXMapping.swift 19.4 KB 332 lines swift

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

Theme