Skip to main content

Module project

org_gdocs

Module project 

Source
Expand description

P3 — projecting an org document into Google Docs batchUpdate requests.

This module is a pure, total transform (engineering invariant EI-4): a kb::ast::Document becomes an ordered Vec of the generated typed google_docs1::api::Request structs plus a PositionMap recording where each anchorable element begins. It performs no IO, never panics, and produces identical output for identical input.

Two invariants shape the design:

  • DI-7 (UTF-16 indexing). Every index is a UTF-16 code-unit offset computed through crate::google::utf16::len_utf16 — never a byte or char count.
  • Typed requests only. Requests are built from the generated structs, never from serde_json::json! literals, so a malformed request fails to compile.

The projection assumes the cursor starts at index 1 — the first writable position of a freshly created (or freshly cleared) Google Doc body. Creating the doc, clearing an existing one, and issuing the batch are the caller’s job (P4a/P7); this module only decides what to send.

§Position map and CUSTOM_IDs

Headings key the map by their :CUSTOM_ID: (assigned in the body by P2, crate::custom_id); other block elements get a hierarchical <parent>/<type>-<n> id (DI-8). The map lets pull (Q1) resolve a Google comment’s index back to the containing structural element.

§Known degradations (v1)

  • Table cells carry plain text only; inline formatting inside a cell is dropped (cell indices shift on insert, making in-cell styling fragile).
  • A horizontal rule renders as a line of ─ glyphs (the Docs API has no first-class rule insertable via batchUpdate).
  • Org table rule rows (|---+---|) are dropped — they are presentation, not data, and the kb parser keeps them only for round-trip fidelity.

Soft line breaks inside a paragraph (the parser’s Inline::LineBreak, emitted only to round-trip source wrapping) project to a single space: source-line wrapping is presentation, and the sole paragraph boundary is a blank line, which already ends the block.

Structs§

Position
Where an anchorable element begins in the projected document.
Projection
The output of project: the ordered batch requests and the position map.

Enums§

ElementKind
The structural kind of a projected element, stored alongside its index in the PositionMap so pull can report what a comment is anchored to.

Functions§

project
Project an org document into ordered Docs requests and a position map.

Type Aliases§

PositionMap
Map from CUSTOM_ID to the projected Position of that element.