Crate mystical_runic

Expand description

§🔮 Mystical-Runic - High-Performance Template Engine for Rust

Rust Compatibility: Requires Rust 1.74.0+ | Edition 2021 | Future Rust 2024 Ready

Mystical-Runic is a high-performance, zero-dependency templating engine for Rust that combines Mustache-inspired syntax with advanced features like template inheritance, macros, filters, enterprise-grade security, comprehensive developer tools, and ecosystem integration.

§🌟 Key Features

Zero Dependencies Core: No external dependencies for core functionality
Enterprise Security: XSS protection, path traversal prevention, template injection security
High Performance: Bytecode compilation, caching, parallel processing, memory mapping
Developer Experience: Hot reload, debugging, IDE integration, intelligent error messages
Ecosystem Integration: Async support, web framework integration, WASM compatibility, CLI tools
Comprehensive Testing: 204+ tests with 100% coverage following strict TDD methodology
Conventional & Mystical APIs: Choose your preferred naming style

§📋 Template Syntax Reference

Feature	Syntax	Description
Variables	`{{name}}`	HTML-escaped variable output
Raw HTML	`{{& html}}`	Unescaped HTML output (use carefully)
Conditionals	`{{if condition}}...{{/if}}`	Conditional rendering with comparison operators
Loops	`{{for item in items}}...{{/for}}`	Iterate over arrays and nested structures
Deep Access	`{{user.profile.name}}`	Unlimited depth object property access
Includes	`{{include "template.html"}}`	Template composition and reuse
Comments	`{{! comment }}`	Template comments (not rendered)
Filters	`{{value\|upper\|truncate:10}}`	Transform output with filter chains
Macros	`{{macro name(params)}}...{{/macro}}`	Reusable template components
Inheritance	`{{extend "layout.html"}}`	Template inheritance system
Blocks	`{{block content}}...{{/block}}`	Replaceable content blocks
I18n	`{{t "key" name=user}}`	Internationalization with variables
Pluralization	`{{plural count "item" "items"}}`	Smart plural forms

§📖 Quick Start Guide

📚 Documentation complète disponible :

Documentation technique : cargo doc --open --all-features

Guide utilisateur : Documentation HTML (français)

Référence en ligne : docs.rs/mystical-runic

Add to your Cargo.toml:

[dependencies]
mystical-runic = "0.5.2"

# Optional features for ecosystem integration
mystical-runic = { version = "0.5.2", features = ["async", "web-frameworks", "wasm", "cli"] }

§🌐 Optional Features

Feature	Description	Dependencies
`async`	Asynchronous template rendering with Tokio	`tokio`, `futures`
`axum-integration`	Direct Axum framework support	`axum`, `async`
`warp-integration`	Direct Warp framework support	`warp`, `async`
`actix-integration`	Direct Actix-web framework support	`actix-web`, `async`
`web-frameworks`	All web framework integrations	All above web features
`wasm`	WebAssembly browser compatibility	`wasm-bindgen`, `js-sys`, `web-sys`
`cli`	Command-line tools and utilities	`clap`, `serde`, `serde_json`, `toml`
`full`	All ecosystem integration features	All optional features

§🧙‍♂️ Usage Examples - Choose Your Style

§Conventional Style

use mystical_runic::{TemplateEngine, TemplateContext, TemplateValue};

let mut engine = TemplateEngine::new("templates");
let mut context = TemplateContext::new();
 
context.set("user", TemplateValue::String("Developer".to_string()));
context.set("task", TemplateValue::String("Build Features".to_string()));
 
let result = engine.render_string(
    "Hello {{user}}! Your mission: {{task}}", 
    &context
).unwrap();

§Mystical Style ✨

use mystical_runic::{RuneEngine, RuneScroll, RuneSymbol};

// Summon the ancient engine from the template realm
let mut engine = RuneEngine::new("sacred_scrolls");
let mut scroll = RuneScroll::new();
 
// Inscribe your desires upon the scroll
scroll.set("hero", RuneSymbol::String("Rust Developer".to_string()));
scroll.set("quest", RuneSymbol::String("Debug Production Issues".to_string()));
 
// Speak the incantation and witness the transformation
let result = engine.render_string(
    "Behold! {{hero}} embarks upon {{quest}}! 🗡️", 
    &scroll
).unwrap();

§🚀 Performance & Security

Performance Features:

Template caching with smart invalidation
Bytecode compilation for frequently-used templates
Parallel template processing capabilities
Memory-mapped file loading for large templates
Optimized nested property traversal

Security Features:

HTML escaping by default (XSS prevention)
Path traversal protection (../ and absolute path blocking)
Template injection prevention
Memory exhaustion protection
Input validation and sanitization

§🛠️ Developer Experience

Hot Reload: Automatic template recompilation during development
Debug Mode: Variable tracking and execution analysis
IDE Integration: LSP support with auto-completion and diagnostics
Smart Suggestions: Intelligent template and variable suggestions
Precise Errors: Line/column error reporting with context
Performance Metrics: Built-in execution time measurement

§🚀 Ecosystem Integration Examples

§Async Template Rendering (requires `async` feature)

use mystical_runic::{TemplateEngine, TemplateContext};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut engine = TemplateEngine::new("templates");
    let mut context = TemplateContext::new();
    context.set_string("user", "Async Developer");

    let result = engine.render_string_async(
        "Hello {{user}}! Processing async request...",
        &context
    ).await?;

    println!("{}", result);
    Ok(())
}

§Web Framework Integration (requires framework-specific features)

// Axum Integration (requires `axum-integration` feature)
use axum::{response::Html, routing::get, Router};
use mystical_runic::{TemplateEngine, TemplateContext};

async fn render_page() -> Html<String> {
    let mut engine = TemplateEngine::new("templates");
    let mut context = TemplateContext::new();
    context.set_string("title", "My Axum App");

    let html = engine.render_string("<h1>{{title}}</h1>", &context).unwrap();
    Html(html)
}

§CLI Template Processing (requires `cli` feature)

use mystical_runic::{process_template, batch_process};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Single template processing
    let result = process_template("Hello {{name}}!", r#"{"name": "CLI User"}"#)?;
    println!("{}", result);

    // Batch processing multiple templates
    let templates = vec!["template1.html", "template2.html"];
    let context_json = r#"{"theme": "dark", "version": "0.5.2"}"#;
    let results = batch_process(templates, context_json)?;

    Ok(())
}

Structs§

BrowserRuneEngine: WebAssembly rune engines (mystical aliases, requires wasm feature) JavaScript bindings for WASM
Cli: Command-line tools and utilities (requires cli feature) CLI command structure
CliConfig: Command-line tools and utilities (requires cli feature) CLI configuration structure
CompletionItem: Completion item for auto-completion
DebugInfo: Debug information collected during template rendering
DebugRenderResult: Result of template rendering with debug information
DefinitionInfo: Definition location information
Diagnostic: Diagnostic information for error squiggles
EcosystemCompatibility: Ecosystem compatibility information
ExecutionStep: Individual step in template execution
HoverInfo: Hover information for variables
LspParseResult: LSP parsing result containing template analysis
PerformanceMetrics: Performance metrics for debugging
RuneDivination: Result of template rendering with debug information
RuneEngine: TemplateEngine - High-Performance Template Processing Engine
RuneMetrics: Performance metrics for debugging
RuneResponseError: Axum rune engine (mystical alias, requires axum-integration feature)
RuneScroll: Template context containing variables for rendering
RuneStep: Individual step in template execution
RuneTrace: Debug information collected during template rendering
RuneWatcher: Command-line runic tools (mystical aliases, requires cli feature) Template file watcher for auto-recompilation
RunicBlock: Template block information for LSP
RunicCli: Command-line runic tools (mystical aliases, requires cli feature) CLI command structure
RunicCompatibility: Ecosystem compatibility information
RunicCompletion: Completion item for auto-completion
RunicConfig: Command-line runic tools (mystical aliases, requires cli feature) CLI configuration structure
RunicDiagnostic: Diagnostic information for error squiggles
RunicLore: LSP parsing result containing template analysis
RunicOrigin: Definition location information
RunicToken: Syntax highlighting token
RunicWisdom: Hover information for variables
SyntaxToken: Syntax highlighting token
TemplateBlock: Template block information for LSP
TemplateContext: Template context containing variables for rendering
TemplateEngine: TemplateEngine - High-Performance Template Processing Engine
TemplateResponseError: Axum web framework integration (requires axum-integration feature)
TemplateWatcher: Command-line tools and utilities (requires cli feature) Template file watcher for auto-recompilation
WasmRuneEngine: WebAssembly browser compatibility (requires wasm feature) JavaScript bindings for WASM

Enums§

Commands: Command-line tools and utilities (requires cli feature)
RuneError: Template engine error type with enhanced developer experience
RuneSymbol: Template value types that can be used in templates
RunicCommands: Command-line runic tools (mystical aliases, requires cli feature)
TemplateError: Template engine error type with enhanced developer experience
TemplateValue: Template value types that can be used in templates

Traits§

ActixRuneEngine: Actix rune engine (mystical alias, requires actix-integration feature) Actix-web response extension for TemplateEngine
ActixTemplateEngine: Actix-web framework integration (requires actix-integration feature) Actix-web response extension for TemplateEngine
AsyncRuneEngine: Async rune engine (mystical alias, requires async feature) Async extension trait for TemplateEngine
AsyncTemplateEngine: Async template engine support (requires async feature) Async extension trait for TemplateEngine
AxumRuneEngine: Axum rune engine (mystical alias, requires axum-integration feature) Axum response extension for TemplateEngine
AxumTemplateEngine: Axum web framework integration (requires axum-integration feature) Axum response extension for TemplateEngine
EcosystemRuneEngine: Extension trait to add ecosystem compatibility to TemplateEngine
EcosystemTemplateEngine: Extension trait to add ecosystem compatibility to TemplateEngine
WarpRuneEngine: Warp rune engine (mystical alias, requires warp-integration feature) Warp response extension for TemplateEngine
WarpTemplateEngine: Warp web framework integration (requires warp-integration feature) Warp response extension for TemplateEngine
WasmRuneEngineTrait: WebAssembly rune engines (mystical aliases, requires wasm feature) WASM-specific template engine extensions
WasmTemplateEngine: WebAssembly browser compatibility (requires wasm feature) WASM-specific template engine extensions

Functions§

batch_process: Command-line tools and utilities (requires cli feature) Batch process multiple templates
load_config: Command-line tools and utilities (requires cli feature) Load CLI configuration from TOML
process_files: Command-line tools and utilities (requires cli feature) Process template and data files
process_template: Command-line tools and utilities (requires cli feature) Process a template string with JSON data

Type Aliases§

AncientHelper: Custom helper function type
FilterFunction: Custom filter function type
HelperFunction: Custom helper function type
MysticFilter: Custom filter function type
RuneResult: Template engine result type
TemplateResult: Template engine result type

Crate mystical_runic

Crate mystical_runic Copy item path

§🔮 Mystical-Runic - High-Performance Template Engine for Rust

§🌟 Key Features

§📋 Template Syntax Reference

§📖 Quick Start Guide

§🌐 Optional Features

§🧙‍♂️ Usage Examples - Choose Your Style

§Conventional Style

§Mystical Style ✨

§🚀 Performance & Security

§🛠️ Developer Experience

§🚀 Ecosystem Integration Examples

§Async Template Rendering (requires async feature)

§Web Framework Integration (requires framework-specific features)

§CLI Template Processing (requires cli feature)

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate mystical_runic

§Async Template Rendering (requires `async` feature)

§CLI Template Processing (requires `cli` feature)