SPB Git

Repository Public

ExportSupport.swift 23.3 KB 417 lines swift

1// ORIX Docs2// File: Packages/ORIXDocsKit/Sources/DocFormats/ExportSupport.swift3// Description: What the exporters share: export options, resolution of tracked changes, the feature scan behind the loss reports4//              (preflight and export warnings come from the same table), resolved text of fields / cross-references / citations.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import DocModel10import DocContainer1112public struct ExportOptions: Sendable {13    /// Renders citations and the bibliography. Without it citations are written as pandoc keys (`[@key]`).14    public var citations: (any CitationFormatting)?15    /// Converts LaTeX (source, display) to MathML markup for HTML export. Without it equations are written as LaTeX text.16    public var mathML: (@Sendable (String, Bool) -> String?)?17    /// true: export the document as if every tracked change were accepted. false: as if every change were rejected.18    public var acceptChanges: Bool19    /// Markdown only: returns the path to write for an image (the caller saves the file). nil: images are embedded as data URIs.20    public var imagePath: (@Sendable (Asset) -> String?)?21    public init() { citations = nil; mathML = nil; acceptChanges = true; imagePath = nil }22}2324// MARK: - Tracked changes2526enum ChangeResolver {27    static func hasChanges(_ doc: DocumentModel) -> Bool {28        var found = false29        doc.forEachParagraphEverywhere { p, _, _ in if p.hasTrackedChanges { found = true } }30        if !found { found = doc.notes.values.contains { $0.paragraphs.contains(where: \.hasTrackedChanges) } }31        return found32    }3334    /// The document with every tracked change accepted (or rejected) and no revision mark left.35    static func resolved(_ doc: DocumentModel, accept: Bool) -> DocumentModel {36        guard hasChanges(doc) else { return doc }37        var out = doc38        out.body = resolve(doc.body, accept: accept)39        for (id, note) in doc.notes {40            var n = note41            n.paragraphs = resolve(note.paragraphs.map(Block.paragraph), accept: accept).compactMap(\.paragraph)42            if n.paragraphs.isEmpty { n.paragraphs = [Paragraph(style: StyleID.footnoteText)] }43            out.notes[id] = n44        }45        return out46    }4748    private static func resolve(_ p: Paragraph, accept: Bool) -> (paragraph: Paragraph, joinsNext: Bool) {49        var q = p50        q.runs = p.runs.compactMap { run -> Run? in51            var r = run52            if let rev = r.revision {53                if (rev.kind == .deletion) == accept { return nil }54                r.revision = nil55            }56            if let f = r.formatRevision {57                if !accept { r.props = f.previous; r.charStyle = f.previousCharStyle }58                r.formatRevision = nil59            }60            return r61        }62        var joins = false63        if let mark = p.markRevision { joins = (mark.kind == .deletion) == accept }64        q.markRevision = nil65        q.normalize()66        return (q, joins)67    }6869    private static func resolve(_ blocks: [Block], accept: Bool) -> [Block] {70        var out: [Block] = []71        var pending: Paragraph?      // a paragraph whose mark disappears: the next paragraph is appended to it72        for block in blocks {73            switch block {74            case .paragraph(let p):75                let (q, joins) = resolve(p, accept: accept)76                var current = q77                if var head = pending { head.runs += q.runs; head.normalize(); current = head; pending = nil }78                if joins { pending = current } else { out.append(.paragraph(current)) }79            case .table(var t):80                if let head = pending { out.append(.paragraph(head)); pending = nil }81                for r in t.rows.indices {82                    for c in t.rows[r].cells.indices {83                        let cell = resolve(t.rows[r].cells[c].paragraphs.map(Block.paragraph), accept: accept).compactMap(\.paragraph)84                        t.rows[r].cells[c].paragraphs = cell.isEmpty ? [Paragraph(style: StyleID.tableText)] : cell85                    }86                }87                out.append(.table(t))88            default:89                if let head = pending { out.append(.paragraph(head)); pending = nil }90                out.append(block)91            }92        }93        if let head = pending { out.append(.paragraph(head)) }94        return out95    }96}9798// MARK: - Feature scan and loss reports99100/// Counts the features of a document that some export format cannot carry.101struct FeatureScan {102    var comments = 0, trackedChanges = 0, equations = 0, footnotes = 0, endnotes = 0, images = 0, floatingObjects = 0, shapes = 0103    var tables = 0, mergedCells = 0, cellFormatting = 0, citations = 0, crossRefs = 0, pageFields = 0, otherFields = 0, bookmarks = 0104    var listParagraphs = 0, headings = 0, links = 0105    var headersFooters = false, sections = 0, pageBreaks = 0, multiColumn = false, pageDecor = false106    var tocBlocks = 0, bibliographyBlocks = 0107    var fonts = 0, colours = 0, underline = 0, highlights = 0, charEffects = 0, paragraphFormatting = 0, customStyles = 0108    var preservedParts = 0, codeBlocks = 0, emphasis = 0109110    init(_ doc: DocumentModel) {111        comments = doc.comments.count112        preservedParts = doc.preservedParts.count113        let builtIn = Set(StyleSheet.standard().styles.map(\.id))114        func visit(_ p: Paragraph, inTable: Bool = false) {115            if p.markRevision != nil { trackedChanges += 1 }116            if p.list != nil { listParagraphs += 1 }117            if ModelIdiom.headingLevel(p, styles: doc.styles) != nil { headings += 1 }118            if p.style == StyleID.code { codeBlocks += 1 }119            if !builtIn.contains(p.style) { customStyles += 1 }120            var direct = p.props121            direct.outlineLevel = nil122            if ModelIdiom.isRule(p) { direct.borderBottom = nil }123            // Column alignment, list continuation indents and nested-quote indents are structure, not formatting.124            if inTable { direct.alignment = nil }125            if p.style == StyleID.listParagraph || p.style == StyleID.quote { direct.indentLeft = nil }126            if !direct.isEmpty { paragraphFormatting += 1 }127            for r in p.runs {128                if r.revision != nil || r.formatRevision != nil { trackedChanges += 1 }129                let c = r.props130                if c.fontFamily != nil || c.fontSize != nil { fonts += 1 }131                if c.color != nil { colours += 1 }132                if c.highlight != nil { highlights += 1 }133                if c.underline == true { underline += 1 }134                if c.bold == true || c.italic == true || c.strikethrough == true { emphasis += 1 }135                if c.link != nil { links += 1 }136                if c.smallCaps == true || c.allCaps == true || c.tracking != nil || c.baselineShift != nil { charEffects += 1 }137                guard let inline = r.inline else { continue }138                switch inline {139                case .image(let i): images += 1; if i.placement.isFloating { floatingObjects += 1 }140                case .shape(let s): shapes += 1; if s.placement.isFloating { floatingObjects += 1 }141                case .equation: equations += 1142                case .note(let n): if n.kind == .footnote { footnotes += 1 } else { endnotes += 1 }143                case .citation: citations += 1144                case .crossRef: crossRefs += 1145                case .field(let f):146                    switch f {147                    case .pageNumber, .pageCount, .headingText: pageFields += 1148                    default: otherFields += 1149                    }150                case .bookmark: bookmarks += 1151                }152            }153        }154        func decor(_ s: PageSetup) {155            if !s.header.isEmpty || !s.footer.isEmpty { headersFooters = true }156            if s.columns > 1 { multiColumn = true }157            if s.border != nil || s.background != nil || s.watermark != nil { pageDecor = true }158        }159        decor(doc.pageSetup)160        for block in doc.body {161            switch block {162            case .paragraph(let p): visit(p)163            case .table(let t):164                tables += 1165                for row in t.rows {166                    for cell in row.cells {167                        if cell.colSpan > 1 || cell.vMerge != .none { mergedCells += 1 }168                        if cell.shading != nil || cell.borderTop != nil || cell.borderBottom != nil || cell.borderLeft != nil || cell.borderRight != nil || cell.formula != nil { cellFormatting += 1 }169                        cell.paragraphs.forEach { visit($0, inTable: true) }170                    }171                }172            case .pageBreak: pageBreaks += 1173            case .sectionBreak(let s): sections += 1; decor(s.setup)174            case .toc: tocBlocks += 1175            case .bibliography: bibliographyBlocks += 1176            }177        }178        for note in doc.notes.values { note.paragraphs.forEach { visit($0) } }179    }180}181182enum LossReport {183    /// What exporting to `format` loses, derived from the document's content only (nothing is exported).184    static func warnings(for doc: DocumentModel, format: DocFormat, options: ExportOptions) -> [FormatWarning] {185        let s = FeatureScan(doc)186        var w = WarningCollector()187        func add(_ severity: FormatWarning.Severity, _ feature: String, _ detail: String, when count: Int) {188            guard count > 0 else { return }189            w.add(severity, feature, count > 1 ? "\(detail) (\(count) occurrences)" : detail)190        }191        func flag(_ severity: FormatWarning.Severity, _ feature: String, _ detail: String, when condition: Bool) {192            if condition { w.add(severity, feature, detail) }193        }194        let name = format.displayName195        switch format {196        case .orixdoc:197            return []198        case .docx:199            return [FormatWarning(.info, feature: "DOCX", detail: "DOCX export is handled by the DocDOCX module; its losses are reported there.")]200        case .pdf:201            return [FormatWarning(.info, feature: "PDF", detail: "PDF export is produced by the layout engine; this module only imports PDF text.")]202        case .markdown, .html, .rtf, .txt:203            break204        }205        // Common to every lossy format.206        add(.approximated, "Tracked changes", "Tracked changes are not kept; the document is written with every change \(options.acceptChanges ? "accepted" : "rejected")", when: s.trackedChanges)207        add(.dropped, "Comments", "Comments cannot be stored in \(name)", when: s.comments)208        flag(.dropped, "Headers and footers", "Headers and footers cannot be stored in \(name).", when: s.headersFooters)209        add(.dropped, "Sections", "Section breaks and their page setup are not kept", when: s.sections)210        flag(.dropped, "Columns", "Multi-column layout is not kept.", when: s.multiColumn)211        flag(.dropped, "Page decoration", "Page borders, backgrounds and watermarks are not kept.", when: s.pageDecor)212        add(.dropped, "Shapes", "Shapes are not kept; only their text is written", when: s.shapes)213        add(.dropped, "Page-dependent fields", "Page numbers, page counts and running headings are left empty", when: s.pageFields)214        add(.approximated, "Fields", "Fields (title, author, date, caption numbers) are written as their current text", when: s.otherFields)215        add(.approximated, "Cross-references", "Cross-references are written as their current text", when: s.crossRefs)216        add(.dropped, "Preserved DOCX content", "Uninterpreted parts kept from an imported DOCX are only stored in .orixdoc and .docx", when: s.preservedParts)217        if options.citations == nil {218            add(.approximated, "Citations", "No citation formatter was supplied: citations are written as keys ([@key])", when: s.citations)219            add(.approximated, "Bibliography", "No citation formatter was supplied: the bibliography is not rendered", when: s.bibliographyBlocks)220        } else {221            add(.approximated, "Citations", "Citations and the bibliography are written as formatted text", when: s.citations + s.bibliographyBlocks)222        }223        switch format {224        case .markdown:225            w.add(.info, "Page setup", "Paper size, margins and orientation are not stored in Markdown.")226            add(.dropped, "Fonts", "Font families and sizes cannot be expressed in Markdown", when: s.fonts)227            add(.dropped, "Colours", "Text colours cannot be expressed in Markdown", when: s.colours)228            add(.approximated, "Highlight", "Highlights are written as <mark>; the colour is not kept", when: s.highlights)229            add(.approximated, "Underline", "Underline is written as inline HTML (<u>)", when: s.underline)230            add(.dropped, "Character effects", "Small caps, all caps, tracking and baseline shifts are not kept", when: s.charEffects)231            add(.dropped, "Paragraph formatting", "Alignment, indents, spacing, tabs and borders are not kept", when: s.paragraphFormatting)232            add(.dropped, "Custom styles", "Paragraphs with custom styles are written as plain paragraphs", when: s.customStyles)233            add(.dropped, "Page breaks", "Page breaks are not kept", when: s.pageBreaks)234            add(.approximated, "Floating objects", "Floating images are written inline", when: s.floatingObjects)235            add(.approximated, "Image sizes", "Markdown has no image size: images come back at their natural size", when: s.images)236            add(.approximated, "Merged table cells", "Merged cells are written as separate cells", when: s.mergedCells)237            add(.dropped, "Table formatting", "Cell shading, borders and formulas are not kept", when: s.cellFormatting)238            add(.approximated, "Endnotes", "Endnotes are written as footnotes", when: s.endnotes)239            add(.approximated, "Generated lists", "Tables of contents and lists of figures are written as static lists", when: s.tocBlocks)240        case .html:241            w.add(.info, "Page setup", "Paper size, margins and orientation are not stored in HTML.")242            add(.approximated, "Page breaks", "Page breaks are written as CSS print breaks", when: s.pageBreaks)243            add(.approximated, "Floating objects", "Floating objects are written with CSS floats", when: s.floatingObjects)244            add(.dropped, "Character effects", "Tracking and baseline shifts are not kept", when: s.charEffects)245            add(.dropped, "Table formulas and borders", "Cell borders and formulas are not kept", when: s.cellFormatting)246            if options.mathML == nil {247                add(.approximated, "Equations", "No MathML converter was supplied: equations are written as LaTeX source", when: s.equations)248            }249        case .rtf:250            w.add(.info, "Styles", "Named styles are flattened to direct formatting in RTF.")251            add(.approximated, "Equations", "Equations are written as their LaTeX source", when: s.equations)252            add(.approximated, "Footnotes and endnotes", "Notes are appended at the end of the document", when: s.footnotes + s.endnotes)253            add(.approximated, "Floating objects", "Floating images are written inline", when: s.floatingObjects)254            add(.approximated, "Generated lists", "Tables of contents and lists of figures are written as static text", when: s.tocBlocks)255            add(.dropped, "Table formatting", "Cell borders and formulas are not kept", when: s.cellFormatting)256            add(.dropped, "Bookmarks", "Bookmarks are not kept", when: s.bookmarks)257        case .txt:258            flag(.dropped, "Formatting", "Fonts, colours, styles and paragraph formatting are not kept in plain text.",259                 when: s.fonts + s.colours + s.emphasis + s.underline + s.highlights + s.paragraphFormatting + s.headings + s.customStyles + s.codeBlocks > 0)260            add(.dropped, "Images", "Images are replaced by their alternative text", when: s.images)261            add(.dropped, "Links", "Link targets are not kept", when: s.links)262            add(.approximated, "Tables", "Tables are written as tab-separated lines", when: s.tables)263            add(.approximated, "Equations", "Equations are written as their LaTeX source", when: s.equations)264            add(.approximated, "Footnotes and endnotes", "Notes are appended at the end of the text", when: s.footnotes + s.endnotes)265            add(.approximated, "Generated lists", "Tables of contents and lists of figures are written as static text", when: s.tocBlocks)266        default: break267        }268        return w.warnings269    }270}271272// MARK: - Citations in pandoc syntax273274enum CitationSyntax {275    private static func isKeyStart(_ u: Unicode.Scalar) -> Bool { u.properties.isAlphabetic || ("0"..."9").contains(Character(u)) || u == "_" }276    private static func isKeyInner(_ u: Unicode.Scalar) -> Bool { ":.#$%&-+?<>~/".unicodeScalars.contains(u) }277278    /// "[see @smith2020, p. 4; -@doe]" without the brackets.279    static func render(_ c: Citation) -> String {280        c.items.map { item in281            var s = ""282            if let p = item.prefix, !p.isEmpty { s += p + " " }283            s += (item.suppressAuthor ? "-@" : "@") + item.key284            if let l = item.locator, !l.isEmpty { s += ", " + l }285            if let x = item.suffix, !x.isEmpty { s += (item.locator?.isEmpty ?? true ? ", " : " ") + x }286            return s287        }.joined(separator: "; ")288    }289290    /// Parses the inside of a bracketed pandoc citation. nil when some item has no `@key`.291    static func parse(_ inner: String) -> Citation? {292        var items: [CitationItem] = []293        for part in inner.split(separator: ";", omittingEmptySubsequences: false) {294            let u = Array(part.unicodeScalars)295            var at = -1296            var i = 0297            while i < u.count {298                if u[i] == "@", i + 1 < u.count, isKeyStart(u[i + 1]), i == 0 || u[i - 1] == " " || u[i - 1] == "-" || u[i - 1] == "\u{A0}" { at = i; break }299                i += 1300            }301            guard at >= 0 else { return nil }302            var end = at + 1303            while end < u.count, isKeyStart(u[end]) || (isKeyInner(u[end]) && end + 1 < u.count && (isKeyStart(u[end + 1]) || isKeyInner(u[end + 1]))) { end += 1 }304            let key = String(String.UnicodeScalarView(u[(at + 1)..<end]))305            var suppress = false306            var prefixEnd = at307            if at > 0, u[at - 1] == "-" { suppress = true; prefixEnd = at - 1 }308            let prefix = String(String.UnicodeScalarView(u[..<prefixEnd])).trimmingCharacters(in: .whitespaces)309            var rest = String(String.UnicodeScalarView(u[end...])).trimmingCharacters(in: .whitespaces)310            if rest.hasPrefix(",") { rest = String(rest.dropFirst()).trimmingCharacters(in: .whitespaces) }311            var item = CitationItem(key: key, suppressAuthor: suppress)312            if !prefix.isEmpty { item.prefix = prefix }313            if !rest.isEmpty {314                let lower = rest.lowercased()315                let terms = ["p.", "pp.", "page", "pages", "chap.", "ch.", "chapter", "sec.", "section", "§", "vol.", "fig.", "figure", "no.", "para.", "¶", "l.", "ll.", "n.", "nn."]316                if terms.contains(where: { lower.hasPrefix($0) }) || (rest.first?.isNumber ?? false) { item.locator = rest } else { item.suffix = rest }317            }318            items.append(item)319        }320        return items.isEmpty ? nil : Citation(items: items)321    }322}323324// MARK: - Export context325326/// Everything an exporter needs about one document: the change-resolved model, its numbering and the text of generated content.327struct ExportContext {328    let doc: DocumentModel329    let numbering: Numbering330    let options: ExportOptions331    var warnings = WarningCollector()332333    init(_ source: DocumentModel, options: ExportOptions) {334        doc = ChangeResolver.resolved(source, accept: options.acceptChanges)335        numbering = Numbering(doc)336        self.options = options337    }338339    func citationText(_ c: Citation) -> String {340        if let f = options.citations { return f.citationText(c, document: doc, numbering: numbering) }341        return "[" + CitationSyntax.render(c) + "]"342    }343344    /// Text of a field inside `p`. `sequenceIndex` counts the sequence fields already met in the paragraph.345    func fieldText(_ field: Field, in p: Paragraph, sequenceIndex: inout Int) -> String {346        switch field {347        case .sequence:348            let values = numbering.sequences[p.id] ?? []349            defer { sequenceIndex += 1 }350            return sequenceIndex < values.count ? String(values[sequenceIndex]) : "?"351        default:352            return numbering.staticFieldText(field, document: doc) ?? ""353        }354    }355356    func crossRefText(_ ref: CrossRef) -> String { numbering.crossRefText(ref, pageOf: { _ in nil }) }357358    /// Id of the paragraph a cross-reference points to.359    func crossRefTarget(_ ref: CrossRef) -> String? {360        let target = numbering.bookmarks[ref.target] ?? ref.target361        return numbering.targetExists(target) ? target : nil362    }363364    func headingNumberPrefix(_ p: Paragraph) -> String { numbering.headingNumbers[p.id].map { $0 + " " } ?? "" }365366    func noteMark(_ ref: NoteRef) -> String { numbering.noteMark(ref) }367368    /// Notes in reference order: footnotes first, then endnotes.369    var orderedNotes: [(ref: NoteRef, note: Note)] {370        numbering.footnoteOrder.compactMap { id in doc.notes[id].map { (NoteRef(kind: .footnote, id: id), $0) } }371            + numbering.endnoteOrder.compactMap { id in doc.notes[id].map { (NoteRef(kind: .endnote, id: id), $0) } }372    }373374    /// Entries of a generated list: (level, text, target paragraph id).375    func entries(of toc: TOCBlock) -> [(level: Int, text: String, target: String)] {376        switch toc.kind {377        case .contents:378            return numbering.outline.filter { $0.level <= toc.maxLevel }.map { ($0.level, ($0.number.map { $0 + " " } ?? "") + $0.text, $0.id) }379        case .figures, .tables:380            let label = toc.kind == .figures ? "Figure" : "Table"381            return numbering.captions.filter { $0.value.label == label }.sorted { $0.value.number < $1.value.number }.map { (1, $0.value.text, $0.key) }382        }383    }384385    /// Formatted bibliography entries, nil when no formatter was supplied.386    func bibliographyParagraphs() -> [Paragraph]? {387        options.citations?.bibliographyParagraphs(document: doc, numbering: numbering)388    }389390    /// Plain text of a paragraph with every inline object replaced by text (used for alt text, plain text, slugs).391    func flatText(_ p: Paragraph, noteMarks: Bool = false) -> String {392        var out = ""393        var seq = 0394        for r in p.runs {395            guard let inline = r.inline else { out += r.text; continue }396            switch inline {397            case .image(let i): if !i.altText.isEmpty { out += "[\(i.altText)]" }398            case .shape(let s): out += s.text399            case .equation(let e): out += e.latex400            case .note(let n): if noteMarks { out += "[\(noteMark(n))]" }401            case .citation(let c): out += citationText(c)402            case .crossRef(let ref): out += crossRefText(ref)403            case .field(let f): out += fieldText(f, in: p, sequenceIndex: &seq)404            case .bookmark: break405            }406        }407        return out408    }409410    /// Static loss report merged with what the exporter noticed while writing.411    func finalWarnings(source: DocumentModel, format: DocFormat) -> [FormatWarning] {412        var all = LossReport.warnings(for: source, format: format, options: options)413        for w in warnings.warnings where !all.contains(where: { $0.id == w.id }) { all.append(w) }414        return all415    }416}417
Files main
Menu

Theme