omgbase_mutate/
lib.rs

1//! # omgbase-mutate
2//!
3//! The omgbase mutation kernel, Rust implementation of `spec/mutate`: a
4//! document loaded from the store as a mutable block tree ([`MutDoc`]), the
5//! six kernel operations over it with placement addressing and
6//! compare-and-swap expectations ([`ops`]), the splice renderer with its
7//! dirty rules ([`render`]), changeset placeholder resolution
8//! ([`changeset`]), the whole-document lowering ([`lower`]), the opset
9//! ([`opset`]) and the public effect vocabulary with its plan shape, conflict
10//! rules and digest ([`effects`], 2.3). Every function here is pure: the store loads, applies,
11//! commits, and hosts the macros and document operations.
12//!
13//! ```
14//! use omgbase_mutate::{MutBlock, MutDoc, At, Parent, To, op_insert, render};
15//! use omgbase_reconcile::SequentialMinter;
16//!
17//! let mut doc = MutDoc::new("d_0", "a.md", vec![MutBlock::new("b_0", "heading", "# Title", "\n")]);
18//! let mut minter = SequentialMinter::new("b");
19//! let to = To { parent: Parent::Doc, at: At::End };
20//! let result = op_insert(&mut doc, &to, "A paragraph.", 0, None, &mut minter).unwrap();
21//! assert_eq!(result.ids, ["b_0"]);
22//! assert_eq!(render(&doc), "# Title\n\nA paragraph.\n");
23//! ```
24
25#![forbid(unsafe_code)]
26
27pub mod changeset;
28pub mod effects;
29pub mod error;
30pub mod lower;
31pub mod ops;
32pub mod opset;
33pub mod render;
34pub mod summary;
35pub mod tree;
36
37pub use changeset::{Op, parse_placeholder, resolve_op, resolve_placeholder, resolve_to};
38pub use effects::{
39    Admission, ConflictTracker, Effect, EffectExpect, ExpectMap, Field, Focus, FocusInfo,
40    FocusTarget, IdentityOp, IdentityPreview, NewId, NewIdKind, PLAN_VERSION, PLANNER_V, ParentRow,
41    Plan, PlanCreate, PlanFrontmatter, PlanMove, PlanOpset, PlanPreview, PlanRevision,
42    PlanTombstone, Preconditions, Repair, RetargetHitPreview, RetargetPairPreview, RetargetPreview,
43    SELECTION_CEILING, ScalarWrite, Selection, SelectionExpect, ShapeError, ShapeFixContext,
44    Target, canonical_json, classify_field, map_block_ids, parse_new_symbol, shift_placeholders,
45};
46pub use error::{ErrorCode, MutationError, Result};
47pub use lower::{LowerResult, body_of, lcs, lower_replace, lower_top_level, strip_frontmatter};
48pub use omgbase_reconcile::Minter;
49pub use ops::{
50    At, Expect, OpResult, Parent, To, UpdateArgs, check_content_hash, check_parent_children_hash,
51    cross_doc_move, default_trivia, op_insert, op_merge, op_move, op_remove, op_split, op_update,
52    parse_content, parse_document, resolve_target, separates_blocks,
53};
54pub use opset::{Opset, OpsetPrecondition, OpsetSummary, PlanDisposition, PlanOp, summarize};
55pub use render::{render, render_block};
56pub use summary::{
57    NoLookup, SummaryLookup, block_count, plural, summarize_effect, visible_text_of,
58};
59pub use tree::{BlockPath, MutBlock, MutDoc, child_ids, parent_children_hash, raw_hash_hex};
60
61/// The `spec/mutate/VERSION` this crate implements (`major.minor`).
62pub const SPEC_VERSION: &str = "3.5";
63
64/// This crate's own version (`Cargo.toml`), for the surface's `version` tool.
65pub const VERSION: &str = env!("CARGO_PKG_VERSION");
66
67#[cfg(test)]
68mod tests {
69    use super::*;
70
71    #[test]
72    fn spec_version_matches_the_crate_line() {
73        let crate_version = env!("CARGO_PKG_VERSION");
74        assert!(
75            crate_version.starts_with(&format!("{SPEC_VERSION}.")),
76            "crate {crate_version} must track spec {SPEC_VERSION}.x"
77        );
78    }
79}
omgbase_mutate/lib.rs

omgbase_mutate/
lib.rs
