cp_ast_core/
lib.rs

1//! Core AST model for competitive-programming problem specifications.
2//!
3//! `cp-ast-core` models an input format as two cooperating trees:
4//!
5//! - [`structure`] describes the shape of the input: scalars, arrays, matrices,
6//!   tuples, repeated blocks, choices, sections, and holes.
7//! - [`constraint`] attaches semantic facts to those nodes: numeric ranges,
8//!   expected value types, distinctness, sortedness, string character sets,
9//!   rendering hints, and similar problem-statement constraints.
10//!
11//! Most applications use [`operation::AstEngine`] as the main entry point. It
12//! stores both trees and applies high-level [`operation::Action`] values that
13//! are convenient for editors and other interactive tools.
14//!
15//! # Public API Map
16//!
17//! - [`structure`] - AST node IDs, node kinds, references, literals, and the
18//!   arena-backed [`structure::StructureAst`].
19//! - [`constraint`] - constraint expressions, IDs, and
20//!   [`constraint::ConstraintSet`].
21//! - [`operation`] - mutation API centered on [`operation::AstEngine`].
22//! - [`projection`] - UI-friendly read models, including
23//!   [`projection::project_full`].
24//! - [`render`] - deterministic text rendering for input formats and
25//!   constraints.
26//! - [`render_tex`] - deterministic TeX/KaTeX rendering.
27//! - [`sample`] - deterministic sample input generation from an AST.
28//!
29//! # Example
30//!
31//! Build a tiny input format for `N` followed by an array `A` of length `N`:
32//!
33//! ```
34//! use cp_ast_core::constraint::{Constraint, ExpectedType, Expression};
35//! use cp_ast_core::operation::AstEngine;
36//! use cp_ast_core::render::render_input;
37//! use cp_ast_core::structure::{Ident, NodeKind, Reference};
38//!
39//! let mut engine = AstEngine::new();
40//! let n = engine.structure.add_node(NodeKind::Scalar {
41//!     name: Ident::new("N"),
42//! });
43//! let a = engine.structure.add_node(NodeKind::Array {
44//!     name: Ident::new("A"),
45//!     length: Expression::Var(Reference::VariableRef(n)),
46//! });
47//!
48//! let root = engine.structure.add_node(NodeKind::Sequence {
49//!     children: vec![n, a],
50//! });
51//! engine.structure.set_root(root);
52//! engine.constraints.add(
53//!     Some(n),
54//!     Constraint::TypeDecl {
55//!         target: Reference::VariableRef(n),
56//!         expected: ExpectedType::Int,
57//!     },
58//! );
59//!
60//! let rendered = render_input(&engine);
61//! assert!(rendered.starts_with("N\nA_1"));
62//! ```
63//!
64//! For JSON roundtrips and browser integration, pair this crate with
65//! `cp-ast-json` and `cp-ast-wasm`.
66
67/// Constraint AST types and storage.
68pub mod constraint;
69/// High-level mutation API for building and editing AST documents.
70pub mod operation;
71/// UI-friendly read projections derived from AST documents.
72pub mod projection;
73/// Plain-text rendering helpers.
74pub mod render;
75/// TeX and KaTeX rendering helpers.
76pub mod render_tex;
77/// Deterministic sample input generation.
78pub mod sample;
79/// Structure AST types and storage.
80pub mod structure;
cp_ast_core/lib.rs

cp_ast_core/
lib.rs
