dampen_core/
lib.rs

1//! Dampen Core - Parser, IR, and Traits
2//!
3//! This crate contains the core types and traits for the Dampen UI framework.
4//!
5//! # Overview
6//!
7//! Dampen Core provides:
8//! - **XML Parser**: Parse `.gravity` files into an Intermediate Representation (IR)
9//! - **IR Types**: Structured representation of UI widgets and bindings
10//! - **Expression Engine**: Evaluate binding expressions like `{counter}` or `{if x > 0}`
11//! - **Handler Registry**: Manage event handlers for UI interactions
12//! - **Code Generation**: Generate static Rust code for production builds
13//! - **Backend Traits**: Abstract interface for rendering backends
14//!
15//! # Quick Start
16//!
17//! ```rust
18//! use dampen_core::parse;
19//!
20//! let xml = r#"<column><text value="Hello!" /></column>"#;
21//! let doc = parse(xml).unwrap();
22//! println!("Parsed {} widgets", doc.root.children.len());
23//! ```
24//!
25//! # Core Concepts
26//!
27//! ## Intermediate Representation (IR)
28//!
29//! The IR bridges XML parsing and backend rendering:
30//! - [`DampenDocument`] - Root document structure
31//! - [`WidgetNode`] - Individual UI widgets
32//! - [`WidgetKind`] - Types of widgets (button, text, etc.)
33//! - [`AttributeValue`] - Static or bound attribute values
34//!
35//! ## Binding Expressions
36//!
37//! Expressions in `{braces}` are parsed into [`Expr`] AST nodes:
38//! - Field access: `{user.name}`
39//! - Method calls: `{items.len()}`
40//! - Conditionals: `{if active then 'yes' else 'no'}`
41//! - Binary operations: `{count > 0}`
42//!
43//! ## Event Handlers
44//!
45//! Handlers connect UI events to Rust functions:
46//! - [`HandlerRegistry`] - Runtime handler storage
47//! - [`HandlerSignature`] - Compile-time handler metadata
48//! - [`HandlerEntry`] - Different handler types (simple, with value, with command)
49//!
50//! # Architecture
51//!
52//! This crate is **backend-agnostic**. It defines traits and types but doesn't
53//! implement any specific UI framework. See `dampen-iced` for the Iced backend.
54//!
55//! # Features
56//!
57//! - **Zero-copy parsing** with `roxmltree`
58//! - **Type-safe** expression evaluation
59//! - **Error recovery** with span information
60//! - **Code generation** for production builds
61//!
62//! # Re-exports
63//!
64//! This crate re-exports all public types from its submodules for convenience.
65//! See individual modules for detailed documentation.
66
67// Module declarations
68pub mod binding;
69pub mod codegen;
70pub mod expr;
71pub mod handler;
72pub mod ir;
73pub mod parser;
74pub mod state;
75pub mod traits;
76
77// Public exports
78
79/// Binding value types and the `UiBindable` trait for data models.
80///
81/// This module provides the core abstraction for data binding in Dampen.
82/// Types implementing `UiBindable` can have their fields accessed from
83/// binding expressions in XML.
84pub use binding::{BindingValue, ToBindingValue, UiBindable};
85
86/// Expression evaluation and AST types.
87///
88/// This module handles parsing and evaluating binding expressions like
89/// `{counter}`, `{items.len()}`, and `{if x > 0 then 'yes' else 'no'}`.
90pub use expr::{
91    BinaryOp, BinaryOpExpr, BindingError, BindingErrorKind, BindingExpr, ConditionalExpr, Expr,
92    FieldAccessExpr, LiteralExpr, MethodCallExpr, UnaryOp, UnaryOpExpr, evaluate_binding_expr,
93    evaluate_expr, evaluate_formatted,
94};
95
96/// Event handler management and signatures.
97///
98/// This module provides the registry for event handlers and signature
99/// validation for compile-time checking.
100pub use handler::{HandlerEntry, HandlerRegistry, HandlerSignature};
101
102/// Intermediate Representation (IR) types.
103///
104/// This module contains all types representing the parsed structure of
105/// a Dampen UI document, suitable for rendering or code generation.
106pub use ir::{
107    AttributeValue, DampenDocument, EventBinding, EventKind, InterpolatedPart, SchemaVersion, Span,
108    WidgetKind, WidgetNode,
109};
110
111/// XML parsing and error types.
112///
113/// This module provides the parser that converts XML markup into the IR.
114pub use parser::error::{ParseError, ParseErrorKind};
115pub use parser::parse;
116
117/// Backend abstraction traits.
118///
119/// This module defines the `Backend` trait that rendering implementations
120/// must provide.
121pub use traits::Backend;
122
123/// Code generation for production builds.
124///
125/// This module generates static Rust code from Dampen documents,
126/// eliminating runtime parsing overhead.
127pub use codegen::{CodegenError, CodegenOutput, generate_application, validate_handlers};
128
129/// Application state container for UI views.
130///
131/// This module provides the [`AppState`](state::AppState) struct that combines
132/// a parsed UI document with application state and event handlers.
133pub use state::AppState;
134
135/// Tokenize a binding expression for debugging or custom processing.
136pub use expr::tokenize_binding_expr;
137
138/// Version of the Dampen framework
139pub const VERSION: &str = env!("CARGO_PKG_VERSION");
dampen_core/lib.rs

dampen_core/
lib.rs
