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 shared;
75pub mod state;
76pub mod traits;
77
78// Public exports
79
80/// Binding value types and the `UiBindable` trait for data models.
81///
82/// This module provides the core abstraction for data binding in Dampen.
83/// Types implementing `UiBindable` can have their fields accessed from
84/// binding expressions in XML.
85pub use binding::{BindingValue, ToBindingValue, UiBindable};
86
87/// Expression evaluation and AST types.
88///
89/// This module handles parsing and evaluating binding expressions like
90/// `{counter}`, `{items.len()}`, and `{if x > 0 then 'yes' else 'no'}`.
91pub use expr::{
92    BinaryOp, BinaryOpExpr, BindingError, BindingErrorKind, BindingExpr, ConditionalExpr, Expr,
93    FieldAccessExpr, LiteralExpr, MethodCallExpr, SharedFieldAccessExpr, UnaryOp, UnaryOpExpr,
94    evaluate_binding_expr, evaluate_expr, evaluate_formatted,
95};
96
97/// Event handler management and signatures.
98///
99/// This module provides the registry for event handlers and signature
100/// validation for compile-time checking.
101pub use handler::{HandlerEntry, HandlerRegistry, HandlerSignature};
102
103/// Intermediate Representation (IR) types.
104///
105/// This module contains all types representing the parsed structure of
106/// a Dampen UI document, suitable for rendering or code generation.
107pub use ir::{
108    AttributeValue, DampenDocument, EventBinding, EventKind, InterpolatedPart, SchemaVersion, Span,
109    WidgetKind, WidgetNode,
110};
111
112/// XML parsing and error types.
113///
114/// This module provides the parser that converts XML markup into the IR.
115pub use parser::error::{ParseError, ParseErrorKind};
116pub use parser::{
117    MAX_SUPPORTED_VERSION, ValidationWarning, parse, parse_version_string,
118    validate_version_supported, validate_widget_versions,
119};
120
121/// Backend abstraction traits.
122///
123/// This module defines the `Backend` trait that rendering implementations
124/// must provide.
125pub use traits::Backend;
126
127/// Code generation for production builds.
128///
129/// This module generates static Rust code from Dampen documents,
130/// eliminating runtime parsing overhead.
131pub use codegen::{CodegenError, CodegenOutput, generate_application, validate_handlers};
132
133/// Application state container for UI views.
134///
135/// This module provides the [`AppState`](state::AppState) struct that combines
136/// a parsed UI document with application state and event handlers.
137pub use state::AppState;
138
139/// Runtime theme context for managing active themes.
140///
141/// This module provides the [`ThemeContext`](state::ThemeContext) struct for
142/// managing theme state including active theme, switching, and hot-reload.
143pub use state::ThemeContext;
144
145/// Shared state container for inter-window communication.
146///
147/// This module provides the [`SharedContext`](shared::SharedContext) struct for
148/// sharing state across multiple views in a Dampen application.
149pub use shared::SharedContext;
150
151/// Tokenize a binding expression for debugging or custom processing.
152pub use expr::tokenize_binding_expr;
153
154/// Version of the Dampen framework
155pub const VERSION: &str = env!("CARGO_PKG_VERSION");
dampen_core/lib.rs

dampen_core/
lib.rs
