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

dampen_core/
lib.rs
