# Document DSL specification

A lightweight, markdown-inspired syntax for POS receipt templates. The DSL compiles to an AST and then to ESC/POS bytes or a screen preview.

> **Implementation:** Parser in `src/dsl/parser.rs`. All constructs below are implemented unless listed under [Future extensions](#future-extensions-not-implemented).

**Design goals:** easy to author, line-oriented, explicit about POS-specific features (barcodes, cut, feed), parameter-friendly.

---

## Document structure

A document is a sequence of **blocks** separated by blank lines. Blocks cannot be nested except for inline markup within text blocks.

---

## Text blocks

### Paragraphs

Plain text with optional inline markup. One or more consecutive non-empty lines form a paragraph.

```markdown
Thank you for your purchase!
Visit us again soon.
```

### Headings

```markdown
# Store Name
## Receipt
```

- `#` → large / double-height text (ESC/POS emphasis)
- `##` → bold emphasis
- Maximum two levels in v1

### Alignment

Prefix a paragraph with alignment markers:

```markdown
:center:
Your Store Name

:right:
Total: ${Amount}
```

| Marker | Effect |
|--------|--------|
| `:left:` | Left (default) |
| `:center:` | Centered |
| `:right:` | Right-aligned |

### Inline markup

| Syntax | Effect |
|--------|--------|
| `**text**` | Bold |
| `*text*` | Italic / emphasized (printer secondary font if available) |
| `` `text` `` | Monospace / condensed |
| `${Name}` | Parameter placeholder (see Parameters) |

Parameters work inside any text, and inside barcode/QR/image directives (below).

**Example:**

```markdown
Receipt #${DocumentNumber}
Date: ${Date}

Item: ${ItemName}     **${LineTotal}**
```

### Horizontal rule

```markdown
---
```

Renders a dashed or solid separator line across the print width.

---

## Directives (block-level)

Directives start with `@` at the beginning of a line.

### Feed (blank lines)

```markdown
@feed 3
```

Advances paper by *n* lines.

### Cut

```markdown
@cut
```

Partial cut after content (if printer supports). Often placed at document end.

### Image

```markdown
@image path/to/logo.png
@image ${LogoPath} width=50%
@image assets/qr-promo.png width=384
```

| Attribute | Description |
|-----------|-------------|
| `path` (positional) | File path relative to `.pos` file or absolute; may be `${Param}` |
| `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
| `align` | `left` (default), `center`, `right` |

Images are converted to monochrome raster data, dithered, and scaled to width.

### Barcode

```markdown
@barcode CODE128 ${Sku}
@barcode EAN13 ${EanCode} height=80
```

| Field | Values |
|-------|--------|
| Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |
| Data | Literal or `${Param}` |
| `height` | Module height in dots (default: 64) |
| `align` | `left`, `center`, `right` |
| `show_text` | `true` / `false` — HRI below barcode (default: true) |

### QR code

```markdown
@qr https://example.com/receipt/${DocumentNumber}
@qr ${PaymentUrl} size=6
```

| Attribute | Description |
|-----------|-------------|
| Data (positional) | URL or text; may include `${Param}` |
| `size` | Module size 1–16 (default: 4) |
| `ecc` | Error correction: `L`, `M`, `Q`, `H` (default: `M`) |
| `align` | `left`, `center`, `right` |

---

## Parameters

### Syntax

```
${ParameterName}
```

- **Names:** `[A-Za-z_][A-Za-z0-9_]*` (ASCII letters, digits, underscore)
- **Case-sensitive:** `${DocNo}` and `${docno}` are different
- **Uniqueness at input:** all occurrences of the same name share one value entered at print time

### Where parameters are allowed

| Location | Example |
|----------|---------|
| Text | `Order ${OrderId}` |
| Barcode data | `@barcode CODE128 ${OrderId}` |
| QR data | `@qr ${VerifyUrl}` |
| Image path | `@image ${LogoPath}` |

### Print-time behavior

1. Before print, scan AST for all `${...}` tokens.
2. Deduplicate by name.
3. Show dialog with one field per unique name.
4. Pre-fill from last print session (global or per-file — implementation choice).
5. Substitute into AST, then render/print.

Missing parameter at print time: block print and highlight unresolved names in UI.

---

## Comments

```markdown
<!-- This is a comment, not printed -->
```

HTML-style comments are stripped at parse time.

---

## Example document

```markdown
# ${StoreName}
:center:

123 Main Street
Tel: ${StorePhone}

---
Date: ${Date}        Time: ${Time}
Receipt: ${DocumentNumber}

Item                    Total
${LineItems}

---
:right:
**TOTAL: ${GrandTotal}**

@barcode CODE128 ${DocumentNumber}
@feed 2
@qr https://shop.example.com/r/${DocumentNumber}

Thank you!
@feed 4
@cut
```

`${LineItems}` might be pre-formatted multi-line text passed as a single parameter (v1); structured line items are a future extension.

---

## Parse errors

The parser reports:

- Unknown directive
- Invalid barcode symbology
- Unclosed `**` or `` ` ``
- Invalid `${}` name
- Missing required directive argument

Errors include 1-based line and column for editor highlighting.

---

## ESC/POS mapping (summary)

| DSL | ESC/POS |
|-----|---------|
| `# heading` | Double width/height ON → text → OFF |
| `**bold**` | Bold ON/OFF |
| `:center:` | Justification center |
| `@feed n` | Print and feed n lines |
| `@cut` | GS V partial cut |
| `@barcode` | GS k / CODE128 native |
| `@qr` | GS ( k QR model 2 |
| `@image` | GS v 0 raster bit image |

Full command details live in the print encoder module; see [PRINTING.md](PRINTING.md).

---

## Future extensions (not implemented)

- `@table` for columnar line items
- `UPC-A` barcodes
- Conditionals: `@if ${HasDiscount} ... @endif`
- Loops / repeating sections
- `@signature` for custom ESC/POS hex escape
- Multiple code pages / Unicode subset
- Syntax highlighting in the editor
