# 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 ``` 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