rustixml

Crates.iorustixml
lib.rsrustixml
version0.3.1
created_at2025-11-21 11:48:01.945928+00
updated_at2025-12-08 20:20:15.103212+00
descriptionNative iXML (Invisible XML) parser with left-recursion support - 76.9% spec conformance, works in Rust and WebAssembly
homepagehttps://github.com/bigale/rustixml
repositoryhttps://github.com/bigale/rustixml
max_upload_size
id1943447
size768,407
Alex Everitt (bigale)

documentation

https://docs.rs/rustixml

README

rustixml

Crates.io License WASM Live Demo

A pure Rust implementation of the Invisible XML (iXML) specification with WebAssembly support.

🌐 Try it live in your browser!

Turn any text into XML using simple grammar rules. Works natively in Rust and in the browser via WebAssembly.

✨ Features

  • 🚀 Fast native recursive descent parser - Direct interpretation of iXML grammars with seed-growing left-recursion
  • ✅ 76.9% spec conformance - 50 out of 65 tests passing, 95.9% correctness (47/49) (details)
  • 🌐 WebAssembly support - 50KB gzipped, runs in any modern browser
  • 📦 Single dependency - Only unicode-general-category for native builds
  • 🔒 Pure safe Rust - No unsafe code
  • 🎯 Zero-copy parsing - Efficient memory usage

🚀 Quick Start

Rust

Add to your Cargo.toml:

[dependencies]
rustixml = "0.2"

Example usage:

use rustixml::{parse_ixml_grammar, NativeParser};

fn main() -> Result<(), String> {
    // Define an iXML grammar
    let grammar = r#"
        greeting: "Hello, ", name, "!".
        name: letter+.
        letter: ["A"-"Z"; "a"-"z"].
    "#;

    // Parse the grammar
    let ast = parse_ixml_grammar(grammar)?;
    
    // Create a parser
    let parser = NativeParser::new(ast);
    
    // Parse some input
    let xml = parser.parse("Hello, World!")?;
    
    println!("{}", xml);
    // Output: <greeting>Hello, <name>World</name>!</greeting>
    
    Ok(())
}

WebAssembly (Browser)

<!DOCTYPE html>
<html>
<head>
    <script type="module">
        import init, { parse_ixml } from './pkg/rustixml.js';

        async function run() {
            await init();

            const grammar = `
                greeting: "Hello, ", name, "!".
                name: letter+.
                letter: ["A"-"Z"; "a"-"z"].
            `;

            const result = parse_ixml(grammar, "Hello, World!");
            
            if (result.success) {
                console.log('XML:', result.output);
            } else {
                console.error('Error:', result.error);
            }
        }

        run();
    </script>
</head>
<body>
    <h1>iXML Parser Demo</h1>
</body>
</html>

🎮 Live Demos

Try it online:

Or run locally:

# Clone the repository
git clone https://github.com/bigale/rustixml.git
cd rustixml

# Build WASM
wasm-pack build --target web

# Serve the demo
python3 -m http.server 8080

# Open http://localhost:8080/docs/ in your browser

Three demo versions available:

  • docs/index.html - Standard demo (recommended for most users)
  • docs/htmz-standalone.html - HTMZ pattern demo (form-driven, no backend)
  • docs/wasmz.html - WASMZ pattern demo ⭐ (native speed with wasm:// routing!)

See docs/HTMZ-README.md for comparison of all three versions.

WASMZ Pattern: The wasmz.html demo showcases true wasm:// routing where HTML forms directly call compiled Rust functions that return HTML templates. This is a reference implementation of the WASMZ pattern (WebAssembly + htmz) offering ~10x performance improvement over JavaScript. See docs/WASMZ-PATTERN.md for technical details.

📖 What is Invisible XML?

Invisible XML (iXML) is a specification for describing text formats as grammars and automatically converting text that matches those grammars into XML. It's like regular expressions on steroids!

Example: Parse CSV into XML:

csv: row+.
row: field+separator, field, newline.
field: char*.
@separator: ",".
-char: ~[","; #0A].
-newline: #0A.

Input:

name,age,city
Alice,30,NYC
Bob,25,LA

Output:

<csv>
  <row><field>name</field><field>age</field><field>city</field></row>
  <row><field>Alice</field><field>30</field><field>NYC</field></row>
  <row><field>Bob</field><field>25</field><field>LA</field></row>
</csv>

🏗️ Architecture

rustixml uses a native recursive descent parser that directly interprets iXML grammar ASTs. Unlike other implementations that use parser generators, this approach:

  • ✅ Eliminates intermediate compilation steps
  • ✅ Produces smaller WASM binaries (50KB vs 500KB+)
  • ✅ Handles insertion/suppression semantics natively
  • ✅ Provides better error messages

See docs/ARCHITECTURE.md for details.

📊 Conformance

Overall: 50/65 tests (76.9%) Correct tests: 47/49 tests (95.9%)

Major features supported:

  • ✅ Full left-recursion support (seed-growing algorithm)
  • ✅ Grammar normalization
  • ✅ Static ambiguity detection
  • ✅ Character classes, marks, repetition
  • ✅ Alternatives, sequences, literals

See KNOWN_ISSUES.md for detailed status and roadmap.

🔧 Building

Native

cargo build --release

WebAssembly

# Install wasm-pack if you haven't already
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# Build for web
wasm-pack build --target web

# Build for Node.js
wasm-pack build --target nodejs

# Build for bundlers (webpack, rollup, etc.)
wasm-pack build --target bundler

🧪 Testing

# Run unit tests
cargo test

# Run conformance tests
cargo run --bin conformance_test

📦 Publishing

Crates.io

cargo publish

npm

wasm-pack build --target web
cd pkg
npm publish

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Areas where help is especially appreciated:

  • 🐛 Fixing failing test cases (see KNOWN_ISSUES.md)
  • 📝 Improving documentation
  • ✨ Adding examples
  • 🧪 Writing more tests

📄 License

Licensed under either of:

at your option.

🙏 Acknowledgments

  • iXML Specification by the Invisible XML Community Group
  • iXML Test Suite for comprehensive conformance testing
  • Rust and WebAssembly communities for excellent tooling

📚 Resources

Made with ❤️ and 🦀 by Alex Everitt

Commit count: 0

cargo fmt