# Waltzing - Compile-time Template Engine for Rust

> LLM-optimized documentation for the Waltzing template engine.

## What is Waltzing?

Waltzing is a compile-time template engine for Rust inspired by Scala's Twirl.
It transforms .wtz template files into type-safe Rust code during build time.

## Key Features

- Compile-time template compilation to Rust code
- Type-safe templates with full Rust type checking
- HTML auto-escaping by default for security
- Template inheritance and reusable components
- Embedded CSS, JavaScript, and JSON support with template interpolation
- Alpine.js integration with `@```alpine` blocks
- Template comments work in HTML, `<script>`, and `<style>` contexts

## Machine-Readable Resources

### Syntax Reference (Quick)
GET https://waltzing.awesomike.com/raw/syntax.md

### Full Grammar (EBNF)
GET https://waltzing.awesomike.com/raw/grammar.ebnf

### Claude Code Integration (CLAUDE.md)
GET https://waltzing.awesomike.com/raw/claude.md

### Comprehensive Usage Guide
GET https://waltzing.awesomike.com/raw/usage.md

## MCP Server

Waltzing provides an MCP (Model Context Protocol) server for LLM integration.

### HTTP Endpoint
POST https://waltzing.awesomike.com/mcp
Content-Type: application/json

### Local MCP Server (stdio)
Install the MCP server binary and configure your client:

```bash
curl -fsSL https://waltzing.awesomike.com/install | bash -s -- --binary mcp
```

### Claude Code Configuration
Add to ~/.claude/claude_desktop_config.json or settings:

```json
{
  "mcpServers": {
    "waltzing": {
      "command": "waltzing-mcp",
      "args": []
    }
  }
}
```

### Available MCP Tools

| Tool | Description |
|------|-------------|
| validate_template | Validate template syntax and report errors |
| get_syntax_help | Get detailed help for any construct (if, for, let, match, fn, struct, enum, json, alpine, js, css, etc.) |
| list_constructs | List all constructs, optionally filtered by category |
| get_install_command | Get installation instructions |

### Example MCP Request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_syntax_help",
    "arguments": { "construct": "alpine" }
  }
}
```

## Installation

```bash
# Install all tools (compiler, LSP, MCP)
curl -fsSL https://waltzing.awesomike.com/install | bash

# Install specific tool
curl -fsSL https://waltzing.awesomike.com/install | bash -s -- --binary compiler
curl -fsSL https://waltzing.awesomike.com/install | bash -s -- --binary lsp
curl -fsSL https://waltzing.awesomike.com/install | bash -s -- --binary mcp
```

## Quick Syntax Reference

### Expressions
```
@variable            Output variable (HTML-escaped)
@obj.field           Field access
@obj.method()        Method call
@(a + b)             Complex expression (parens required for operators)
@safe(html)          Unescaped output for trusted HTML
@@                   Literal @ symbol
```

### Variable Bindings (IMPORTANT: operators need parentheses)
```
@let name = user.name           Simple binding
@let sum = (a + b)              Arithmetic needs parens
@let valid = (x > 0 && y < 10)  Comparisons need parens
@let cast = (value as i32)      Type casts need parens
```

### Control Flow
```
@if condition { }                    Conditional
@if let Some(x) = opt { }            Pattern matching in if
@for item in items { }               Loop
@for (i, item) in items.iter().enumerate() { }  With index
@match value { pattern => { } }      Pattern matching
@break / @continue                   Loop control
@break :label / @continue :label     Labeled loop control
```

### Definitions
```
@fn name(param: Type) { }            Template function
@fn name(param: Type = default) { }  With default value
@struct Name { field: Type }         Rust struct
@enum Name { Variant1, Variant2 }    Rust enum
@use crate::path::Type               Import Rust type
@import "file.wtz" as alias          Import template
```

### Components (Function Tags)
```
<@component::function />                      Self-closing
<@component::function attr="value" />         With attributes
<@component::function>content</@>             With content (shorthand close)
<@component::function>content</@component::function>  Full close

SHORTHAND: <@template> is equivalent to <@template::apply>
<@layout title="Home">content</@layout>       Same as <@layout::apply ...>
```

### Embedded Languages
```
@```json { key: @value } ```@        JSON with interpolation
@```alpine { count: @n } ```@        Alpine.js x-data
@```js const x = @value; ```@        JavaScript
@```css .class { color: @c; } ```@   CSS
```

### Comments (work in HTML, script, and style contexts)
```
@* comment *@                        Template comment (not in output)
@** multi-line comment **@           Multi-asterisk (match count)
<!-- HTML comment -->                HTML comment (in output)

Comments in script/style tags:
<script>
    @* This comment works inside script tags *@
    if (condition) { ... }
</script>

<style>
    @* This comment works inside style tags *@
    .class { color: blue; }
</style>
```

### Control Flow in Attributes
```
<button
    @if disabled { disabled }
    @if primary { class="btn-primary" }
    @for attr in attrs { @attr.name="@attr.value" }
>
```

## Common Patterns

### List with conditional classes
```waltzing
<ul>
    @for (i, item) in items.iter().enumerate() {
        <li class="@if i == 0 { first } @if item.active { active }">
            @item.name
        </li>
    }
</ul>
```

### Alpine.js component with server data
```waltzing
<div x-data=@```alpine {
    userId: @user.id,
    items: @items_json,
    selectedId: null,
    select(id) { this.selectedId = id; }
} ```@>
    <template x-for="item in items">
        <div @click="select(item.id)" x-text="item.name"></div>
    </template>
</div>
```

### Form with validation
```waltzing
<input
    type="email"
    value="@form.email"
    @if errors.contains_key("email") {
        class="error"
        aria-invalid="true"
    }
/>
@if let Some(err) = errors.get("email") {
    <span class="error-msg">@err</span>
}
```

## Links

- Repository: https://git.awesomike.com/dev/waltzing
- Documentation: https://waltzing.awesomike.com/docs
- Downloads: https://waltzing.awesomike.com/download
- Tree-sitter Grammar: https://waltzing.awesomike.com/tree-sitter/