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`]) and the opset
9//! ([`opset`]). Every function here is pure: the store loads, applies,
10//! commits, and hosts the macros and document operations.
11//!
12//! ```
13//! use omgbase_mutate::{MutBlock, MutDoc, At, Parent, To, op_insert, render};
14//! use omgbase_reconcile::SequentialMinter;
15//!
16//! let mut doc = MutDoc::new("d_0", "a.md", vec![MutBlock::new("b_0", "heading", "# Title", "\n")]);
17//! let mut minter = SequentialMinter::new("b");
18//! let to = To { parent: Parent::Doc, at: At::End };
19//! let result = op_insert(&mut doc, &to, "A paragraph.", 0, None, &mut minter).unwrap();
20//! assert_eq!(result.ids, ["b_0"]);
21//! assert_eq!(render(&doc), "# Title\n\nA paragraph.\n");
22//! ```
23
24#![forbid(unsafe_code)]
25
26pub mod changeset;
27pub mod error;
28pub mod lower;
29pub mod ops;
30pub mod opset;
31pub mod render;
32pub mod tree;
33
34pub use changeset::{Op, parse_placeholder, resolve_op, resolve_placeholder, resolve_to};
35pub use error::{ErrorCode, MutationError, Result};
36pub use lower::{LowerResult, body_of, lcs, lower_replace, lower_top_level, strip_frontmatter};
37pub use omgbase_reconcile::Minter;
38pub use ops::{
39 At, Expect, OpResult, Parent, To, UpdateArgs, check_content_hash, check_parent_children_hash,
40 cross_doc_move, default_trivia, op_insert, op_merge, op_move, op_remove, op_split, op_update,
41 parse_content, resolve_target, separates_blocks,
42};
43pub use opset::{Opset, OpsetPrecondition, OpsetSummary, PlanDisposition, PlanOp, summarize};
44pub use render::{render, render_block};
45pub use tree::{BlockPath, MutBlock, MutDoc, child_ids, parent_children_hash, raw_hash_hex};
46
47/// The `spec/mutate/VERSION` this crate implements (`major.minor`).
48pub const SPEC_VERSION: &str = "1.2";
49
50#[cfg(test)]
51mod tests {
52 use super::*;
53
54 #[test]
55 fn spec_version_matches_the_crate_line() {
56 let crate_version = env!("CARGO_PKG_VERSION");
57 assert!(
58 crate_version.starts_with(&format!("{SPEC_VERSION}.")),
59 "crate {crate_version} must track spec {SPEC_VERSION}.x"
60 );
61 }
62}