🥮 mooncakes.io
    Sign in

    This version of the module is deprecated: Use moonbitlang/docx2html instead

    bobzhang/docx2html/docx does not have a README file

    AnnotationAnchor

    source
    pub struct AnnotationAnchor {
      // private fields
    }

    One anchor of a comment: a paired range (start+end), a dangling half-range, or a point (references only). Paths are full agent paths ("/body/p[2]"); references are the comment-reference positions attached to this anchor, in document order.

    AnnotationAnchor::end

    source
    fn AnnotationAnchor::end(self : AnnotationAnchor) -> String?

    The range end's containing projection path, when present.

    AnnotationAnchor::end_boundary

    source

    The end marker's boundary relative to end, when present.

    AnnotationAnchor::references

    source
    fn AnnotationAnchor::references(self : AnnotationAnchor) -> Array[String]

    Comment-reference positions attached to this anchor, in document order.

    AnnotationAnchor::start

    source
    fn AnnotationAnchor::start(self : AnnotationAnchor) -> String?

    The range start's containing projection path, when present.

    AnnotationAnchor::start_boundary

    source

    The start marker's boundary relative to start, when present.

    AnnotationAnchor::story

    source
    fn AnnotationAnchor::story(self : AnnotationAnchor) -> String

    The story this anchor lives in ("/body", "/header[1]", ...).

    AnnotationBoundary

    source
    pub enum AnnotationBoundary {
      Before
      InsideStart
      InsideEnd
      After
    } derive(Eq)

    Where a marker sits relative to its rendered projection node — the plan's boundary distinction, preserved so "before p[3]" and "after p[2]" do not collapse into the same position.

    AnnotationBoundary::equal

    source

    AnnotationBoundary::not_equal

    source

    AnnotationBoundary::output

    source
    fn AnnotationBoundary::output(self : AnnotationBoundary, logger : &Logger) -> Unit

    AnnotationBoundary::to_string

    source
    fn AnnotationBoundary::to_string(self : AnnotationBoundary) -> String

    AnnotationIndex

    source
    pub struct AnnotationIndex {
      // private fields
    }

    The annotation index. Opaque: fields stay private so the surface can evolve additively.

    AnnotationIndex::comments

    source

    Comments: one entry per definition (comments.xml order), then marker-only ids.

    AnnotationIndex::covering_comment_ids

    source
    fn AnnotationIndex::covering_comment_ids(self : AnnotationIndex, path : String) -> Array[String]

    The ids of comments whose anchors INTERSECT the projection element at path ("/body/p[2]" style), in definition order — the reverse link J2's comment_ids exposes. Point anchors cover their reference's paragraph.

    AnnotationIndex::endnotes

    source

    Endnotes with their reference positions.

    AnnotationIndex::footnotes

    source
    fn AnnotationIndex::footnotes(self : AnnotationIndex) -> Array[NoteInfo]

    Footnotes with their reference positions.

    AnnotationIndex::revisions

    source

    Tracked changes across every publicly addressable story, in document order (story order, then position within the story).

    AnnotationIndex::warnings

    source
    fn AnnotationIndex::warnings(self : AnnotationIndex) -> Array[String]

    Non-fatal diagnostics gathered while building the index.

    CommentInfo

    source
    pub struct CommentInfo {
      // private fields
    }

    One comment: identity and metadata from comments.xml (defined is false for a dangling id that only appears in markers), threading from commentsExtended when present, and anchors from the story scans in the total order the plan fixes (story rank, then position).

    CommentInfo::anchors

    source

    Anchors in the plan's total order (story rank, then position).

    CommentInfo::author

    source
    fn CommentInfo::author(self : CommentInfo) -> String?

    The w:author attribute, when present.

    CommentInfo::body_paragraphs

    source
    fn CommentInfo::body_paragraphs(self : CommentInfo) -> Int

    Number of body paragraphs in the comment definition.

    CommentInfo::date

    source
    fn CommentInfo::date(self : CommentInfo) -> String?

    The w:date attribute, LEXICAL (never converted), when present.

    CommentInfo::defined

    source
    fn CommentInfo::defined(self : CommentInfo) -> Bool

    False when the id appears only in markers (no definition).

    CommentInfo::done

    source
    fn CommentInfo::done(self : CommentInfo) -> Bool?

    w15 resolution state; None when commentsExtended is absent.

    CommentInfo::id

    source
    fn CommentInfo::id(self : CommentInfo) -> String

    The comment id, as spelled in comments.xml.

    CommentInfo::initials

    source
    fn CommentInfo::initials(self : CommentInfo) -> String?

    The w:initials attribute, when present.

    CommentInfo::last_para_id

    source
    fn CommentInfo::last_para_id(self : CommentInfo) -> String?

    The definition's LAST body paragraph w14:paraId (the commentsExtended key), or None when the paragraph is unstamped.

    CommentInfo::parent_id

    source
    fn CommentInfo::parent_id(self : CommentInfo) -> String?

    The parent comment id for replies (w15 paraIdParent, last-paragraph rule).

    CommentSpec

    source
    pub struct CommentSpec {
      // private fields
    }

    One comment to attach to the written body: WHO (author, optional initials and xsd:dateTime date), WHERE (an inclusive range of top-level body block indexes with both endpoints paragraphs — or, for a reply, the earlier comment it answers), optionally a done resolution flag, and WHAT (paragraph-only body content). Construct with comment_spec (anchored) or comment_reply (anchorless), which fail-close on everything a spec can get wrong in isolation.

    DocxAnnotatedResult

    source
    pub struct DocxAnnotatedResult {
      // private fields
    }

    The package read plus its annotation index. Opaque. Carries the annotation BODIES as (id, body) pairs in reader order — exactly the shape @paths.resolve_annotation_path consumes (J2's read surface).

    The retained source bytes, story scans, and mutation-planning topology of a returned result form a source-pinned IMMUTABLE snapshot: in mutation-safe mode its index scans ARE the retained reader-projection scans (one scan per story part, shared by every consumer). Applying surgery never patches a retained scan in place — the plan writes a new archive, and reading that archive is the only way to observe the mutation.

    DocxAnnotatedResult::annotation_sidecars

    source
    fn DocxAnnotatedResult::annotation_sidecars(self : DocxAnnotatedResult) -> Array[String]

    Relationship types of annotation SIDECARS this tooling cannot keep consistent when mutating comments (Word's modern comment identity and people parts). Per the L0 matrix rule these are detected by RELATIONSHIP TYPE from the main part — their presence makes mutating commands fail closed. commentsExtended is NOT here: the add operation never touches it (matrix row), and L2 owns it.

    DocxAnnotatedResult::annotations

    source

    The annotation index built from the same bytes.

    DocxAnnotatedResult::body_paragraph_span

    source
    fn DocxAnnotatedResult::body_paragraph_span(self : DocxAnnotatedResult, relative_path : String) -> NodeSpan?

    The span of the body-story paragraph at relative_path — the story-relative ORDINAL path exactly as the index emits it ("p[3]", "tbl[1]/tr[2]/tc[1]/p[1]") — or None when no such paragraph was projected. Offsets index into main_story_part's original bytes.

    DocxAnnotatedResult::body_run_span

    source
    fn DocxAnnotatedResult::body_run_span(self : DocxAnnotatedResult, relative_path : String) -> NodeSpan?

    The span of the body-story RUN at relative_path ("p[3]/r[2]", the index's ordinal form), or None. Runs carry the same offsets as paragraphs (content_start past a leading rPr) so L1 can rewrite a self-closing <w:r/> by its own extent too.

    DocxAnnotatedResult::comment_bodies

    source

    Comment (id, body) pairs in comments.xml order.

    DocxAnnotatedResult::comments_extended_part

    source
    fn DocxAnnotatedResult::comments_extended_part(self : DocxAnnotatedResult) -> String?

    The zip entry holding the commentsExtended part (resolved by RELATIONSHIP TYPE), or None when the package has none — L2 then creates it.

    DocxAnnotatedResult::comments_part

    source
    fn DocxAnnotatedResult::comments_part(self : DocxAnnotatedResult) -> String?

    The zip entry holding the comments part (resolved by RELATIONSHIP TYPE from the main part, never by filename), or None when the package has no comments part yet — L1 then creates it.

    DocxAnnotatedResult::comments_story_source

    source
    fn DocxAnnotatedResult::comments_story_source(self : DocxAnnotatedResult) -> DocxStoryPartSource?

    Physical source for the comments story, when one was read.

    DocxAnnotatedResult::endnote_bodies

    source

    Endnote (id, body) pairs in reader order.

    DocxAnnotatedResult::endnotes_story_source

    source
    fn DocxAnnotatedResult::endnotes_story_source(self : DocxAnnotatedResult) -> DocxStoryPartSource?

    Physical source for the endnotes story, when one was read.

    DocxAnnotatedResult::footer_story_sources

    source

    Physical sources for rendered footer stories in package-result order.

    DocxAnnotatedResult::footnote_bodies

    source

    Footnote (id, body) pairs in reader order.

    DocxAnnotatedResult::footnotes_story_source

    source
    fn DocxAnnotatedResult::footnotes_story_source(self : DocxAnnotatedResult) -> DocxStoryPartSource?

    Physical source for the footnotes story, when one was read.

    DocxAnnotatedResult::header_story_sources

    source

    Physical sources for rendered header stories in package-result order.

    DocxAnnotatedResult::main_story_part

    source
    fn DocxAnnotatedResult::main_story_part(self : DocxAnnotatedResult) -> String

    The zip entry name of the MAIN document part the body-story spans index into (resolved through the officeDocument relationship, never hardcoded).

    DocxAnnotatedResult::main_story_source

    source

    Physical source and authority for the body story.

    DocxAnnotatedResult::result

    source

    The package-level read (identical to read_docx_package).

    DocxAnnotatedResult::revision_spans

    source

    Every tracked-change element across every scanned story, in story order then document order. Offsets index into the part that backs each story.

    The list is complete BY CONSTRUCTION: the scanner records a site for every tracked-change element it walks, without the suppression and projection gates the reading index applies, and retraction never removes one. A resolver can therefore treat an empty result as proof that the package carries no tracked changes at all.

    DocxAnnotatedResult::story_paragraph_span

    source
    fn DocxAnnotatedResult::story_paragraph_span(self : DocxAnnotatedResult, story : String, relative_path : String) -> NodeSpan?

    The span of a paragraph in ANY scanned story ("/comments" included), by its story-relative ordinal path ("comment[2]/p[1]") — offsets index into that story's part bytes. L2's paraId retrofit edits the parent comment's LAST body paragraph through this.

    DocxAnnotatedResult::story_root_span

    source
    fn DocxAnnotatedResult::story_root_span(self : DocxAnnotatedResult, story : String) -> NodeSpan?

    The ROOT element's span for a scanned story ("/body", "/comments", "/footnotes", "/endnotes"), or None when the story was not scanned. L1 splices a new comment definition just before the comments story's close_tag_start; a self-closing root reports no interior and must be rewritten by its own extent first.

    DocxAnnotatedResult::story_row_span

    source
    fn DocxAnnotatedResult::story_row_span(self : DocxAnnotatedResult, story : String, relative_path : String) -> NodeSpan?

    The span of one table ROW in any scanned story, addressed by the story key ("/body", "/header[1]", ...) and the story-relative ordinal path ("tbl[1]/tr[2]"). The scanner already records tr nodes with full spans; template repetition replaces a row's byte region with filled clones through this.

    DocxAnnotatedResult::story_run_span

    source
    fn DocxAnnotatedResult::story_run_span(self : DocxAnnotatedResult, story : String, relative_path : String) -> NodeSpan?

    The span of one text RUN in any scanned story, addressed by the story key ("/body", "/header[1]", ...) and the story-relative ordinal path ("p[3]/r[2]", "p[1]/hyperlink[1]/r[1]"). The scanner already records run nodes with full spans in every story; this generalizes the body-only lookup so template merging can rewrite header and footer runs through the same byte-span contract.

    DocxPackageResult

    source

    Everything read_docx_with_messages returns, plus sections and header/footer stories.

    DocxPackageResult::equal

    source
    #deprecated("implicit trait-method promotion is being removed; call via the trait")
    fn DocxPackageResult::equal(DocxPackageResult, DocxPackageResult) -> Bool

    DocxPackageResult::not_equal

    source
    #deprecated("implicit trait-method promotion is being removed; call via the trait")
    fn DocxPackageResult::not_equal(x : DocxPackageResult, y : DocxPackageResult) -> Bool

    DocxPackageResult::to_repr

    source
    #deprecated("implicit trait-method promotion is being removed; call via the trait")
    fn DocxPackageResult::to_repr(DocxPackageResult) -> 
    Repr

    DocxReadResult

    source

    Document tree plus diagnostics produced while reading a DOCX package.

    DocxReadResult::equal

    source
    #deprecated("implicit trait-method promotion is being removed; call via the trait")
    fn DocxReadResult::equal(DocxReadResult, DocxReadResult) -> Bool

    DocxReadResult::not_equal

    source
    #deprecated("implicit trait-method promotion is being removed; call via the trait")
    fn DocxReadResult::not_equal(x : DocxReadResult, y : DocxReadResult) -> Bool

    DocxReadResult::to_repr

    source
    #deprecated("implicit trait-method promotion is being removed; call via the trait")
    fn DocxReadResult::to_repr(DocxReadResult) -> 
    Repr

    DocxStoryPartAuthority

    source
    pub enum DocxStoryPartAuthority {
      RelationshipBacked
      LegacyFilenameFallback
    }

    How the reader selected a physical story part.

    DocxStoryPartAuthority::name

    source

    Stable protocol spelling for story-part authority.

    DocxStoryPartSource

    source
    pub struct DocxStoryPartSource {
      // private fields
    }

    The physical ZIP entry used for one logical DOCX story and how it was selected. The type is opaque so more provenance can be added later without exposing mutable reader internals.

    DocxStoryPartSource::authority

    source

    Whether this part was relationship-backed or a legacy filename fallback.

    DocxStoryPartSource::part

    source
    fn DocxStoryPartSource::part(self : DocxStoryPartSource) -> String

    The exact physical ZIP entry read for this story.

    HeaderFooterSpec

    source
    pub struct HeaderFooterSpec {
      // private fields
    }

    One header or footer story attached to the written document's section. Construct with header_footer_spec, which fail-closes on everything the story can get wrong in isolation.

    NodeSpan

    source
    pub struct NodeSpan {
      // private fields
    }

    The byte extent of one BODY-story projection node (paragraph or run) in the original word-processing part, plus the two insertion offsets annotation surgery uses: content_start (just past the open tag AND past a leading pPr/rPr — the property container leads its sequence, so content and markers must land after it) and close_tag_start (the '<' of the close tag). Both are None for a self-closing form, which has no interior — the splice layer must first rewrite it to the open form (a byte edit of this node's own span).

    NodeSpan::byte_end

    source
    fn NodeSpan::byte_end(self : NodeSpan) -> Int

    Offset just past the '>' of the paragraph's close tag (exclusive).

    NodeSpan::byte_start

    source
    fn NodeSpan::byte_start(self : NodeSpan) -> Int

    Offset of the '<' of the paragraph's open tag.

    NodeSpan::close_tag_start

    source
    fn NodeSpan::close_tag_start(self : NodeSpan) -> Int?

    Offset of the '<' of the close tag, or None for a self-closing paragraph.

    NodeSpan::content_start

    source
    fn NodeSpan::content_start(self : NodeSpan) -> Int?

    Earliest interior insertion offset (past the open tag and any leading pPr), or None for a self-closing paragraph.

    NodeSpan::self_closing

    source
    fn NodeSpan::self_closing(self : NodeSpan) -> Bool

    True when the paragraph is the self-closing <w:p/> form.

    NoteInfo

    source
    pub struct NoteInfo {
      // private fields
    }

    One footnote/endnote: its id and every body position referencing it (multi-reference notes are representable per the plan).

    NoteInfo::id

    source
    fn NoteInfo::id(self : NoteInfo) -> String

    The note id, as spelled.

    NoteInfo::references

    source
    fn NoteInfo::references(self : NoteInfo) -> Array[String]

    Every body position referencing this note, in document order.

    NoteSpec

    source
    pub struct NoteSpec {
      // private fields
    }

    One footnote or endnote body: plain-content, paragraph-only, and no note references of its own (notes do not nest). Construct with note_spec.

    RevisionInfo

    source
    pub struct RevisionInfo {
      // private fields
    }

    One tracked change: what kind of revision it is, who made it, when they said they made it, and the projection path of the paragraph that contains it.

    The reader flattens w:ins into the accepted text and drops w:del entirely, so a revision has no representation in the parsed document at all. This record is the only place the identity survives, and it is read-only: text still returns the accepted view, unchanged.

    id, author and date are the attributes AS SPELLED and stay absent when the source omits them. All three are optional in CT_TrackChange; a defaulted author or date would make the index assert authorship the document never recorded.

    RevisionInfo::author

    source
    fn RevisionInfo::author(self : RevisionInfo) -> String?

    The w:author attribute, when present.

    RevisionInfo::date

    source
    fn RevisionInfo::date(self : RevisionInfo) -> String?

    The w:date attribute, LEXICAL (never converted), when present.

    RevisionInfo::id

    source
    fn RevisionInfo::id(self : RevisionInfo) -> String?

    The w:id attribute, as spelled, when present.

    RevisionInfo::kind

    source
    fn RevisionInfo::kind(self : RevisionInfo) -> String

    "ins" for an insertion, "del" for a deletion.

    RevisionInfo::path

    source
    fn RevisionInfo::path(self : RevisionInfo) -> String

    The story-qualified projection path of the containing paragraph ("/body/p[2]"), degrading to the nearest verifiable ancestor.

    RevisionNameEdit

    source
    pub struct RevisionNameEdit {
      // private fields
    }

    One element-name rewrite: the byte range of an element's LOCAL NAME in the original part, and the name it becomes. Rejecting a deletion turns every w:delText back into w:t through these ranges, which leaves the namespace prefix, xml:space, and every other byte of the tag untouched.

    RevisionNameEdit::end

    source
    fn RevisionNameEdit::end(self : RevisionNameEdit) -> Int

    Offset just past the last byte of the local name (exclusive).

    RevisionNameEdit::replacement

    source
    fn RevisionNameEdit::replacement(self : RevisionNameEdit) -> String

    The local name that replaces the range ("t" or "instrText").

    RevisionNameEdit::start

    source
    fn RevisionNameEdit::start(self : RevisionNameEdit) -> Int

    Offset of the first byte of the local name.

    RevisionSpan

    source
    pub struct RevisionSpan {
      // private fields
    }

    One tracked-change ELEMENT in the original bytes: what it is, who recorded it, and the byte extent a resolver needs to unwrap or remove it.

    This is the MUTATION view of a revision and is deliberately wider than AnnotationIndex::revisions, which is the READING view. Reading reports the content insertions and deletions the reader's projection retains; resolving must additionally see every construct it cannot act on, because a construct it cannot see is a construct it would silently leave behind. supported separates the two: it is true only for content w:ins and w:del, false for property revisions, moves, and every *PrChange.

    RevisionSpan::author

    source
    fn RevisionSpan::author(self : RevisionSpan) -> String?

    The w:author attribute, as spelled, when present.

    RevisionSpan::byte_end

    source
    fn RevisionSpan::byte_end(self : RevisionSpan) -> Int

    Offset just past the '>' that ends the element (exclusive).

    RevisionSpan::byte_start

    source
    fn RevisionSpan::byte_start(self : RevisionSpan) -> Int

    Offset of the '<' of the element's open tag.

    RevisionSpan::close_tag_start

    source
    fn RevisionSpan::close_tag_start(self : RevisionSpan) -> Int?

    Offset of the '<' of the close tag, or None for the self-closing form.

    RevisionSpan::container_path

    source
    fn RevisionSpan::container_path(self : RevisionSpan) -> String?

    The story-relative projection path of the innermost containing node ("p[2]", "tbl[1]/tr[1]/tc[1]/p[1]"), or None at story level.

    RevisionSpan::content_start

    source
    fn RevisionSpan::content_start(self : RevisionSpan) -> Int?

    Offset just past the '>' of the open tag, or None for the self-closing form — which has no content to keep, so all four resolutions of it collapse to removing the element.

    RevisionSpan::date

    source
    fn RevisionSpan::date(self : RevisionSpan) -> String?

    The w:date attribute, LEXICAL (never converted), when present.

    RevisionSpan::declares_namespaces

    source
    fn RevisionSpan::declares_namespaces(self : RevisionSpan) -> Bool

    True when the element's own start tag binds a namespace prefix. Unwrapping it would drop the binding while its former children still use it, so an unwrap resolution must refuse; removing the whole element stays safe.

    RevisionSpan::id

    source
    fn RevisionSpan::id(self : RevisionSpan) -> String?

    The w:id attribute, as spelled, when present.

    RevisionSpan::kind

    source
    fn RevisionSpan::kind(self : RevisionSpan) -> String

    The WML local name of the element ("ins", "del", "moveFrom", "rPrChange").

    RevisionSpan::name_edits

    source
    fn RevisionSpan::name_edits(self : RevisionSpan) -> Array[RevisionNameEdit]

    The w:delText/w:delInstrText names inside this deletion, in document order; empty for an insertion. Rejecting the deletion applies all of them.

    RevisionSpan::story

    source
    fn RevisionSpan::story(self : RevisionSpan) -> String

    The story key the span's offsets index into ("/body", "/header[1]").

    RevisionSpan::supported

    source
    fn RevisionSpan::supported(self : RevisionSpan) -> Bool

    True only for a content w:ins/w:del a resolver can accept or reject.

    RunTextReceipt

    source
    pub struct RunTextReceipt {
      // private fields
    }

    What an addressed run replacement planned: the story part, the address that named the run, the reader-visible text the caller expected (and the plan replaces), and how many byte edits carry it.

    RunTextReceipt::at_relative

    source
    fn RunTextReceipt::at_relative(self : RunTextReceipt) -> String

    RunTextReceipt::edit_count

    source
    fn RunTextReceipt::edit_count(self : RunTextReceipt) -> Int

    RunTextReceipt::replaced_text

    source
    fn RunTextReceipt::replaced_text(self : RunTextReceipt) -> String

    RunTextReceipt::result_text

    source
    fn RunTextReceipt::result_text(self : RunTextReceipt) -> String

    RunTextReceipt::story_part

    source
    fn RunTextReceipt::story_part(self : RunTextReceipt) -> String

    MAX_AUTHORED_MEDIA_BYTES

    source
    let MAX_AUTHORED_MEDIA_BYTES : Int64

    Maximum aggregate emitted-media bytes, summed over image occurrences rather than unique assets.

    MAX_AUTHORED_MEDIA_PARTS

    source
    let MAX_AUTHORED_MEDIA_PARTS : Int

    Maximum distinct media parts a fresh-authoring script may emit (one per image OCCURRENCE, not per unique asset), and the aggregate emitted-media byte ceiling summed over occurrences. Enforced BEFORE the writer graph is built, so a script that references one asset thousands of times is refused as a typed media limit rather than after materializing every part.

    author_docx_bytes

    source

    Builds a fresh DOCX from an already-parsed docx.batch/2 script and the image bytes its image_paths() referenced. Body/comment/note construction errors surface as Unsupported carrying the script op address; a bounded serialization or emitted-media ceiling breach surfaces as WriteResourceLimit. Nothing is written — the caller publishes the returned bytes through its own transaction/atomic-write boundary.

    comment_anchor_fragments

    source
    fn comment_anchor_fragments(id~ : String, wordprocessing_namespace? : String) -> (String, String)

    The two anchor fragments for comment id: the range start (spliced at the from-paragraph's content_start) and the range end plus the reference run (spliced at the to-paragraph's close_tag_start) — the same canonical shape the K1 writer emits, in self-contained form.

    comment_definition_fragment

    source
    fn comment_definition_fragment(spec : CommentSpec, id~ : String, para_ids? : Array[String], max_output_bytes? : Int, wordprocessing_namespace? : String) -> String raise 
    DocxError

    The w:comment definition fragment for spec (whose anchored range is ignored here — the splice layer owns placement). The body is re-validated (the arrays stay caller-mutable) and serialized through the same body writers as the packaging path, under the same fail-closed guard against relationship-bearing content.

    comment_reply

    source
    fn comment_reply(author~ : String, initials? : String, date? : String, reply_to~ : Int, done? : Bool, body : Array[
    DocumentElement    ]) -> CommentSpec raise 
    DocxError

    Validates and builds an anchorless REPLY: reply_to is the 0-based index of an EARLIER spec in the array passed to write_docx_with_comments (checked against the array there; chains are allowed — a reply may answer another reply). Per the locked policy a reply emits NO range or reference markers: its parent's anchor is logically its own, and the thread linkage lives in word/commentsExtended.xml (w15:paraIdParent). Everything else — author/initials/date rules, the plain-content paragraph-only body — matches comment_spec.

    comment_spec

    source
    fn comment_spec(author~ : String, initials? : String, date? : String, from~ : Int, to~ : Int, done? : Bool, body : Array[
    DocumentElement    ]) -> CommentSpec raise 
    DocxError

    Validates and builds a CommentSpec. from/to are 0-based indexes into the body array later passed to write_docx_with_comments (the inclusive anchored range); bounds against that body are checked at write time, everything spec-local is checked here so callers can attribute the failure to the exact comment: non-empty attribute-safe author, non-empty attribute-safe initials (when given), a lexically valid xsd:dateTime date (when given), an ordered non-negative range, and a non-empty paragraph-only body. Bodies are PLAIN CONTENT by the roadmap's locked rule — hyperlinks (even relationship-free anchor-only ones) and images are rejected here, and again at write time because the arrays stay caller-mutable.

    convert

    source
    fn convert(docx : BytesView, output_format? : 
    OutputFormat    , style_map? : Array[String], include_default_style_map? : Bool, include_embedded_style_map? : Bool, ignore_empty_paragraphs? : Bool, id_prefix? : String, pretty_print? : Bool, convert_image? : (
    Image    ) -> 
    ImageConversion    , transform_document? : (
    DocumentElement    ) -> 
    DocumentElement    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> 
    ConversionResult     raise 
    DocxError

    Converts DOCX bytes using the requested output format.

    convert_to_html

    source
    fn convert_to_html(docx : BytesView, style_map? : Array[String], include_default_style_map? : Bool, include_embedded_style_map? : Bool, ignore_empty_paragraphs? : Bool, id_prefix? : String, pretty_print? : Bool, convert_image? : (
    Image    ) -> 
    ImageConversion    , transform_document? : (
    DocumentElement    ) -> 
    DocumentElement    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> 
    ConversionResult     raise 
    DocxError

    Converts DOCX bytes to HTML.

    convert_to_markdown

    source
    fn convert_to_markdown(docx : BytesView, style_map? : Array[String], include_default_style_map? : Bool, include_embedded_style_map? : Bool, ignore_empty_paragraphs? : Bool, id_prefix? : String, convert_image? : (
    Image    ) -> 
    ImageConversion    , transform_document? : (
    DocumentElement    ) -> 
    DocumentElement    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> 
    ConversionResult     raise 
    DocxError

    Converts DOCX bytes to Markdown.

    embed_style_map

    source
    fn embed_style_map(docx : BytesView, style_map : String) -> Bytes raise 
    DocxError

    Embeds or replaces the DOCX style map part.

    extract_raw_text

    source
    fn extract_raw_text(docx : BytesView, external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> 
    ConversionResult     raise 
    DocxError

    Extracts raw text from DOCX bytes.

    Validates and builds one header/footer story. variant is the OOXML reference type (default, first or even); the body is non-empty and block-level (paragraphs and tables), plain content all the way down.

    new_blank_docx

    source
    fn new_blank_docx() -> Bytes

    Builds a minimal, schema-valid blank docx: one empty paragraph, a body-final section (Letter, one-inch margins), and a Normal style. All inputs are compile-time constants, so builder failures are programming errors — hence the abort rather than a raise.

    new_blank_docx_limited

    source

    Like new_blank_docx, but serialized under limits so a fresh-creation transaction can bound the candidate BEFORE allocation (the blank package is a small constant, so this never actually breaches — it keeps the create path on the same bounded-writer contract as authored documents). An over- limit ceiling surfaces as the typed WriteResourceLimit.

    note_spec

    source

    Validates and builds a NoteSpec. The body rules match comment bodies (non-empty, paragraph-only, plain content) plus the no-nesting rule; they are re-checked at write time because the arrays stay caller-mutable. Which KIND the note is (footnote or endnote) is decided by which array it is passed in, so one spec type serves both.

    plan_comment_addition

    source
    fn plan_comment_addition(annotated : DocxAnnotatedResult, original : BytesView, at_relative~ : String, to_relative~ : String, spec : CommentSpec, max_fragment_bytes? : Int) -> (
    SplicePlan    , String) raise 
    DocxError

    Builds the splice plan that adds one comment to the ORIGINAL package: anchor markers into the main part at scanner offsets (self-closing paragraphs rewritten by their own extent), the definition into the existing comments part (self-closing roots rewritten too) or a fresh part derived from the MAIN part's directory, wired with a parsed-not-guessed relationship id and a content-type Override located at the BYTE level. Returns the plan and the allocated comment id.

    plan_comment_addition_archive

    source
    fn plan_comment_addition_archive(annotated : DocxAnnotatedResult, archive : 
    Archive    , at_relative~ : String, to_relative~ : String, spec : CommentSpec, xml_budget? : 
    XmlReadBudget    , max_fragment_bytes? : Int) -> (
    SplicePlan    , String) raise 
    DocxError

    Archive-backed form used by preservation-safe edit sessions. It reuses the caller's already bounded, materialized package and never inflates the DOCX a second time.

    plan_comment_reply

    source
    fn plan_comment_reply(annotated : DocxAnnotatedResult, original : BytesView, parent_id~ : String, spec : CommentSpec, max_fragment_bytes? : Int) -> (
    SplicePlan    , String) raise 
    DocxError

    Builds the splice plan for docx annotate reply: the reply's definition (paraId-stamped) into comments.xml plus the whole-part commentsExtended update (parent retrofit included). Returns the plan and the reply's new comment id.

    plan_comment_reply_archive

    source
    fn plan_comment_reply_archive(annotated : DocxAnnotatedResult, archive : 
    Archive    , parent_id~ : String, spec : CommentSpec, xml_budget? : 
    XmlReadBudget    , max_fragment_bytes? : Int) -> (
    SplicePlan    , String) raise 
    DocxError

    Archive-backed reply planner for bounded preservation sessions.

    plan_comment_resolution

    source
    fn plan_comment_resolution(annotated : DocxAnnotatedResult, original : BytesView, comment_id~ : String, done~ : Bool) -> 
    SplicePlan     raise 
    DocxError

    Builds the splice plan for docx annotate resolve|unresolve: the comment's commentsExtended entry flips (or gains) its w15:done flag, with the same paraId retrofit as replies when the definition is unstamped.

    plan_comment_resolution_archive

    source

    Archive-backed resolution planner for bounded preservation sessions.

    plan_run_text_replacement

    source
    fn plan_run_text_replacement(annotated : DocxAnnotatedResult, story : DocxStoryPartSource, at_relative~ : String, expect~ : String, text~ : String) -> (
    SplicePlan    , RunTextReceipt) raise 
    DocxError

    Plans the replacement of one addressed run's whole text with text.

    story must be a story part source the annotated result itself exposed, and the result must come from a MUTATION-SAFE read: only those retain the classified projection this planner consumes. at_relative is the story-relative ordinal run path (p[3]/r[2]), resolved against the projection's own physical scan. expect is REQUIRED and must equal the run's reader-visible text: addresses are snapshot-relative, and a stale expectation refuses rather than editing whatever now sits at the path.

    Every failure is a typed refusal; nothing falls back. The planner takes NO archive: it plans against the exact source bytes the annotated read retained beside the projection, so a mismatched archive cannot be smuggled in -- and the returned plan is pinned to those same bytes, so applying it to anything else refuses as stale.

    read_docx

    source
    fn read_docx(docx : BytesView, external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> 
    DocumentElement     raise 
    DocxError

    Reads DOCX bytes into a document tree.

    read_docx_annotated

    source
    fn read_docx_annotated(docx : BytesView, external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> DocxAnnotatedResult raise 
    DocxError

    Reads DOCX bytes into the package representation PLUS the annotation index. The package half is identical to read_docx_package.

    read_docx_annotated_archive

    source
    fn read_docx_annotated_archive(archive : 
    Archive    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> DocxAnnotatedResult raise 
    DocxError

    Builds the same package and annotation indexes from a caller-owned archive snapshot. Payload buffers are shared; the DOCX reader does not inflate the package a second time. Duplicate entry names fail before the map-backed view is constructed.

    read_docx_annotated_archive_limited

    source
    fn read_docx_annotated_archive_limited(archive : 
    Archive    , xml_budget : 
    XmlReadBudget    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?, max_diagnostics? : Int, max_diagnostic_chars? : Int, expected_main_document_path? : String) -> DocxAnnotatedResult raise 
    DocxError

    Builds package and annotation indexes from an existing archive while every XML part shares one cumulative parser budget. Source bytes are charged before UTF-8 decoding and parser tokens before DOM allocation. Reader diagnostics are deduplicated in first-seen order and bounded during production by max_diagnostics and max_diagnostic_chars.

    read_docx_annotated_archive_tolerant_limited

    source
    fn read_docx_annotated_archive_tolerant_limited(archive : 
    Archive    , xml_budget : 
    XmlReadBudget    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?, max_diagnostics? : Int, max_diagnostic_chars? : Int, expected_main_document_path? : String) -> DocxAnnotatedResult raise 
    DocxError

    Builds the bounded annotation-aware projection used by tolerant read-only commands. Broken section header/footer references are already warned and omitted by DocxPackageResult; they do not activate mutation-only identity gates. Edit transactions continue to use read_docx_annotated_archive_limited and fail closed on the same input.

    read_docx_package

    source
    fn read_docx_package(docx : BytesView, external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> DocxPackageResult raise 
    DocxError

    Reads DOCX bytes into the package-level representation: the body document tree (identical to read_docx_with_messages), header/footer parts (each a block-level story, deduplicated by part path in first-reference order), and the sections that reference them.

    read_docx_with_messages

    source
    fn read_docx_with_messages(docx : BytesView, external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> DocxReadResult raise 
    DocxError

    Reads DOCX bytes into a document tree and diagnostics.

    read_embedded_style_map

    source
    fn read_embedded_style_map(docx : BytesView) -> String? raise 
    DocxError

    Reads the embedded style map from DOCX bytes, if present.

    validate_annotation_identity_state

    source
    fn validate_annotation_identity_state(annotated : DocxAnnotatedResult) -> Unit raise 
    DocxError

    Rejects annotation state that cannot safely serve as the result of a comment mutation. This is the candidate-side counterpart to the planners' source gate and catches duplicate or ambiguous identities introduced by a caller-supplied generic splice plan.

    validate_global_para_id_state_archive_limited

    source
    fn validate_global_para_id_state_archive_limited(annotated : DocxAnnotatedResult, archive : 
    Archive    , xml_budget : 
    XmlReadBudget    ) -> Unit raise 
    DocxError

    Validates every reachable story's w14:paraId values under one cumulative XML budget. This is the candidate-side gate for generic splice plans; the reply/resolution planners use the same traversal before allocating IDs.

    write_docx

    source

    Serializes body content into a complete docx package. Supported today: paragraphs (style id, alignment, list numbering) containing runs (bold, italic, underline, strikethrough, caps, super/subscript, font, size, highlight), text, tabs, line breaks; and tables with spans. Headings use the Heading1..Heading6 style ids, emitted into the styles part so Word's outline and this repo's own outline command both recognize them; list paragraphs reference the fixed bullet/decimal definitions in the numbering part.

    write_docx_with_annotations

    source

    The full annotation writer: write_docx plus comments (see write_docx_with_comments) plus footnotes and endnotes. Notes are referenced from body runs by note_reference(kind, index) where index is the 0-based position in the matching array here — each supplied note must be referenced EXACTLY ONCE (the canonical shape; unreferenced notes would be invisible orphans, duplicate references are not what Word produces). Note bodies are plain-content paragraph-only, may not carry note references themselves, and land in word/footnotes.xml / word/endnotes.xml as MAIN-part relationships, complete with the separator/continuationSeparator plumbing notes and the in-note footnoteRef/endnoteRef mark run.

    write_docx_with_comments

    source

    write_docx plus comments. The body serializes exactly as write_docx would (an empty comments array is byte-identical); each comment then decorates its anchored paragraphs — range start markers right after pPr in the from paragraph, range end plus the id's reference run appended to the to paragraph — and its definition is written to word/comments.xml. Both anchor endpoints must be top-level paragraphs (tables cannot carry the canonical intra-paragraph shape). REPLIES (comment_reply) must answer an EARLIER spec in this array and emit no markers at all. Comment BODIES reuse the body writers, with a fail-closed guard: content that allocates relationships or media (hyperlinks, images) raises instead of emitting references that would dangle in the comments part. Threading or resolution anywhere adds w14:paraId stamps and word/commentsExtended.xml; otherwise output is byte-identical to the threading-free writer.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io