mystical_runic/lib.rs
1//! # 🔮 Mystical-Runic - High-Performance Template Engine for Rust
2//!
3//! [](https://crates.io/crates/mystical-runic)
4//! [](https://docs.rs/mystical-runic)
5//! [](https://opensource.org/licenses/MIT)
6//!
7//! **Rust Compatibility**: Requires Rust 1.74.0+ | Edition 2021 | Future Rust 2024 Ready
8//!
9//! **Mystical-Runic** is a high-performance, zero-dependency templating engine for Rust that combines
10//! Mustache-inspired syntax with advanced features like template inheritance, macros, filters,
11//! enterprise-grade security, comprehensive developer tools, and ecosystem integration.
12//!
13//! ## 🌟 Key Features
14//!
15//! - **Zero Dependencies Core**: No external dependencies for core functionality
16//! - **Enterprise Security**: XSS protection, path traversal prevention, template injection security
17//! - **High Performance**: Bytecode compilation, caching, parallel processing, memory mapping
18//! - **Developer Experience**: Hot reload, debugging, IDE integration, intelligent error messages
19//! - **Ecosystem Integration**: Async support, web framework integration, WASM compatibility, CLI tools
20//! - **Comprehensive Testing**: 204+ tests with 100% coverage following strict TDD methodology
21//! - **Conventional & Mystical APIs**: Choose your preferred naming style
22//!
23//! ## 📋 Template Syntax Reference
24//!
25//! | Feature | Syntax | Description |
26//! |---------|--------|-------------|
27//! | **Variables** | `{{name}}` | HTML-escaped variable output |
28//! | **Raw HTML** | `{{& html}}` | Unescaped HTML output (use carefully) |
29//! | **Conditionals** | `{{if condition}}...{{/if}}` | Conditional rendering with comparison operators |
30//! | **Loops** | `{{for item in items}}...{{/for}}` | Iterate over arrays and nested structures |
31//! | **Deep Access** | `{{user.profile.name}}` | Unlimited depth object property access |
32//! | **Includes** | `{{include "template.html"}}` | Template composition and reuse |
33//! | **Comments** | `{{! comment }}` | Template comments (not rendered) |
34//! | **Filters** | `{{value\|upper\|truncate:10}}` | Transform output with filter chains |
35//! | **Macros** | `{{macro name(params)}}...{{/macro}}` | Reusable template components |
36//! | **Inheritance** | `{{extend "layout.html"}}` | Template inheritance system |
37//! | **Blocks** | `{{block content}}...{{/block}}` | Replaceable content blocks |
38//! | **I18n** | `{{t "key" name=user}}` | Internationalization with variables |
39//! | **Pluralization** | `{{plural count "item" "items"}}` | Smart plural forms |
40//!
41//! ## 📖 Quick Start Guide
42//!
43//! > **📚 Documentation complète disponible** :
44//! > - **Documentation technique** : `cargo doc --open --all-features`
45//! > - **Guide utilisateur** : [Documentation HTML](https://github.com/yrbane/mystical-runic/tree/main/doc) (français)
46//! > - **Référence en ligne** : [docs.rs/mystical-runic](https://docs.rs/mystical-runic)
47//!
48//! Add to your `Cargo.toml`:
49//! ```toml
50//! [dependencies]
51//! mystical-runic = "0.5.2"
52//!
53//! # Optional features for ecosystem integration
54//! mystical-runic = { version = "0.5.2", features = ["async", "web-frameworks", "wasm", "cli"] }
55//! ```
56//!
57//! ## 🌐 Optional Features
58//!
59//! | Feature | Description | Dependencies |
60//! |---------|-------------|--------------|
61//! | `async` | Asynchronous template rendering with Tokio | `tokio`, `futures` |
62//! | `axum-integration` | Direct Axum framework support | `axum`, `async` |
63//! | `warp-integration` | Direct Warp framework support | `warp`, `async` |
64//! | `actix-integration` | Direct Actix-web framework support | `actix-web`, `async` |
65//! | `web-frameworks` | All web framework integrations | All above web features |
66//! | `wasm` | WebAssembly browser compatibility | `wasm-bindgen`, `js-sys`, `web-sys` |
67//! | `cli` | Command-line tools and utilities | `clap`, `serde`, `serde_json`, `toml` |
68//! | `full` | All ecosystem integration features | All optional features |
69//!
70//! ## 🧙♂️ Usage Examples - Choose Your Style
71//!
72//! ### Conventional Style
73//! ```rust
74//! use mystical_runic::{TemplateEngine, TemplateContext, TemplateValue};
75//!
76//! let mut engine = TemplateEngine::new("templates");
77//! let mut context = TemplateContext::new();
78//!
79//! context.set("user", TemplateValue::String("Developer".to_string()));
80//! context.set("task", TemplateValue::String("Build Features".to_string()));
81//!
82//! let result = engine.render_string(
83//! "Hello {{user}}! Your mission: {{task}}",
84//! &context
85//! ).unwrap();
86//! ```
87//!
88//! ### Mystical Style ✨
89//! ```rust
90//! use mystical_runic::{RuneEngine, RuneScroll, RuneSymbol};
91//!
92//! // Summon the ancient engine from the template realm
93//! let mut engine = RuneEngine::new("sacred_scrolls");
94//! let mut scroll = RuneScroll::new();
95//!
96//! // Inscribe your desires upon the scroll
97//! scroll.set("hero", RuneSymbol::String("Rust Developer".to_string()));
98//! scroll.set("quest", RuneSymbol::String("Debug Production Issues".to_string()));
99//!
100//! // Speak the incantation and witness the transformation
101//! let result = engine.render_string(
102//! "Behold! {{hero}} embarks upon {{quest}}! 🗡️",
103//! &scroll
104//! ).unwrap();
105//! ```
106//!
107//! ## 🚀 Performance & Security
108//!
109//! **Performance Features:**
110//! - Template caching with smart invalidation
111//! - Bytecode compilation for frequently-used templates
112//! - Parallel template processing capabilities
113//! - Memory-mapped file loading for large templates
114//! - Optimized nested property traversal
115//!
116//! **Security Features:**
117//! - HTML escaping by default (XSS prevention)
118//! - Path traversal protection (`../` and absolute path blocking)
119//! - Template injection prevention
120//! - Memory exhaustion protection
121//! - Input validation and sanitization
122//!
123//! ## 🛠️ Developer Experience
124//!
125//! - **Hot Reload**: Automatic template recompilation during development
126//! - **Debug Mode**: Variable tracking and execution analysis
127//! - **IDE Integration**: LSP support with auto-completion and diagnostics
128//! - **Smart Suggestions**: Intelligent template and variable suggestions
129//! - **Precise Errors**: Line/column error reporting with context
130//! - **Performance Metrics**: Built-in execution time measurement
131//!
132//! ## 🚀 Ecosystem Integration Examples
133//!
134//! ### Async Template Rendering (requires `async` feature)
135//! ```rust,ignore
136//! use mystical_runic::{TemplateEngine, TemplateContext};
137//!
138//! #[tokio::main]
139//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
140//! let mut engine = TemplateEngine::new("templates");
141//! let mut context = TemplateContext::new();
142//! context.set_string("user", "Async Developer");
143//!
144//! let result = engine.render_string_async(
145//! "Hello {{user}}! Processing async request...",
146//! &context
147//! ).await?;
148//!
149//! println!("{}", result);
150//! Ok(())
151//! }
152//! ```
153//!
154//! ### Web Framework Integration (requires framework-specific features)
155//! ```rust,ignore
156//! // Axum Integration (requires `axum-integration` feature)
157//! use axum::{response::Html, routing::get, Router};
158//! use mystical_runic::{TemplateEngine, TemplateContext};
159//!
160//! async fn render_page() -> Html<String> {
161//! let mut engine = TemplateEngine::new("templates");
162//! let mut context = TemplateContext::new();
163//! context.set_string("title", "My Axum App");
164//!
165//! let html = engine.render_string("<h1>{{title}}</h1>", &context).unwrap();
166//! Html(html)
167//! }
168//! ```
169//!
170//! ### CLI Template Processing (requires `cli` feature)
171//! ```rust,ignore
172//! use mystical_runic::{process_template, batch_process};
173//!
174//! fn main() -> Result<(), Box<dyn std::error::Error>> {
175//! // Single template processing
176//! let result = process_template("Hello {{name}}!", r#"{"name": "CLI User"}"#)?;
177//! println!("{}", result);
178//!
179//! // Batch processing multiple templates
180//! let templates = vec!["template1.html", "template2.html"];
181//! let context_json = r#"{"theme": "dark", "version": "0.5.2"}"#;
182//! let results = batch_process(templates, context_json)?;
183//!
184//! Ok(())
185//! }
186//! ```
187
188mod error;
189mod engine;
190mod context;
191mod value;
192mod utils;
193mod bytecode;
194mod layouts;
195mod debug;
196mod suggestions;
197mod lsp;
198mod async_engine;
199mod web_frameworks;
200mod wasm_support;
201mod cli;
202mod ecosystem;
203
204// 🏢 Conventional names for standard development environments
205pub use error::{TemplateError, TemplateResult};
206pub use engine::TemplateEngine;
207pub use context::TemplateContext;
208pub use value::TemplateValue;
209pub use engine::FilterFunction;
210pub use engine::HelperFunction;
211pub use debug::{DebugInfo, DebugRenderResult, ExecutionStep, PerformanceMetrics};
212pub use lsp::{LspParseResult, TemplateBlock, CompletionItem, SyntaxToken, Diagnostic, HoverInfo, DefinitionInfo};
213
214// 🚀 v0.5.0 Ecosystem Integration exports
215
216/// Async template engine support (requires `async` feature)
217#[cfg(feature = "async")]
218pub use async_engine::AsyncTemplateEngine;
219
220/// Axum web framework integration (requires `axum-integration` feature)
221#[cfg(feature = "axum-integration")]
222pub use web_frameworks::axum_integration::{AxumTemplateEngine, TemplateResponseError};
223
224/// Warp web framework integration (requires `warp-integration` feature)
225#[cfg(feature = "warp-integration")]
226pub use web_frameworks::warp_integration::WarpTemplateEngine;
227
228/// Actix-web framework integration (requires `actix-integration` feature)
229#[cfg(feature = "actix-integration")]
230pub use web_frameworks::actix_integration::ActixTemplateEngine;
231
232/// WebAssembly browser compatibility (requires `wasm` feature)
233#[cfg(feature = "wasm")]
234pub use wasm_support::{WasmTemplateEngine, WasmRuneEngine};
235
236/// Command-line tools and utilities (requires `cli` feature)
237#[cfg(feature = "cli")]
238pub use cli::{Cli, Commands, CliConfig, TemplateWatcher, process_template, process_files, batch_process, load_config};
239
240pub use ecosystem::{EcosystemCompatibility, EcosystemTemplateEngine};
241
242// 🔮 Mystical aliases for the enlightened practitioners of ancient coding arts
243pub use error::{TemplateError as RuneError, TemplateResult as RuneResult};
244pub use engine::TemplateEngine as RuneEngine;
245pub use context::TemplateContext as RuneScroll;
246pub use value::TemplateValue as RuneSymbol;
247pub use engine::FilterFunction as MysticFilter;
248pub use engine::HelperFunction as AncientHelper;
249pub use debug::{DebugInfo as RuneTrace, DebugRenderResult as RuneDivination, ExecutionStep as RuneStep, PerformanceMetrics as RuneMetrics};
250pub use lsp::{LspParseResult as RunicLore, TemplateBlock as RunicBlock, CompletionItem as RunicCompletion, SyntaxToken as RunicToken, Diagnostic as RunicDiagnostic, HoverInfo as RunicWisdom, DefinitionInfo as RunicOrigin};
251
252// 🔮 v0.5.0 Mystical ecosystem aliases
253
254/// Async rune engine (mystical alias, requires `async` feature)
255#[cfg(feature = "async")]
256pub use async_engine::AsyncTemplateEngine as AsyncRuneEngine;
257
258/// Axum rune engine (mystical alias, requires `axum-integration` feature)
259#[cfg(feature = "axum-integration")]
260pub use web_frameworks::axum_integration::{AxumTemplateEngine as AxumRuneEngine, TemplateResponseError as RuneResponseError};
261
262/// Warp rune engine (mystical alias, requires `warp-integration` feature)
263#[cfg(feature = "warp-integration")]
264pub use web_frameworks::warp_integration::WarpTemplateEngine as WarpRuneEngine;
265
266/// Actix rune engine (mystical alias, requires `actix-integration` feature)
267#[cfg(feature = "actix-integration")]
268pub use web_frameworks::actix_integration::ActixTemplateEngine as ActixRuneEngine;
269
270/// WebAssembly rune engines (mystical aliases, requires `wasm` feature)
271#[cfg(feature = "wasm")]
272pub use wasm_support::{WasmTemplateEngine as WasmRuneEngineTrait, WasmRuneEngine as BrowserRuneEngine};
273
274/// Command-line runic tools (mystical aliases, requires `cli` feature)
275#[cfg(feature = "cli")]
276pub use cli::{Cli as RunicCli, Commands as RunicCommands, CliConfig as RunicConfig, TemplateWatcher as RuneWatcher};
277
278pub use ecosystem::{EcosystemCompatibility as RunicCompatibility, EcosystemTemplateEngine as EcosystemRuneEngine};