# 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**. Blank lines become paper feeds (`@feed 1`). Blocks are not nested except for `${parameters}` inside text. --- ## Text blocks ### Paragraphs Plain text (and `${parameters}`). One or more consecutive non-empty lines form a paragraph. There is **no** inline bold/italic/code markup. ```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 | ### Bullet lists ```markdown - Milk - Bread - Eggs ``` Each line must start with `- ` (dash + space). Consecutive list lines form one list block. A blank line ends the list. Wrapped lines use a hanging indent: ```text * this is a long line ``` ### Parameters | Syntax | Effect | |--------|--------| | `${Name}` | Parameter placeholder (see Parameters) | ### Checkboxes | Syntax | Printed result | |--------|----------------| | `[]` or `[ ]` | ☐ (U+2610) | | `[x]` or `[X]` | 🗹 (U+1F5F9) | Emitted as UTF-8 text (experiment). Many ESC/POS printers only speak CP437 and may show garbage or blanks instead. Parameters work inside any text, and inside barcode/QR/image directives (below). **Example:** ```markdown Receipt #${DocumentNumber} Date: ${Date} [x] Paid [] Pending 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 and scaled to width (never wider than `printable_dots`). ### Date / time ```markdown @date @date DD-MM-YYYY @time @time 12h @time 24h ``` | Directive | Behaviour | |-----------|-----------| | `@date` | System regional short date (`%x`) | | `@date PATTERN` | Custom pattern (`YYYY`, `MM`, `DD`, …) | | `@time` / `@time 24h` | 24-hour `HH:MM` | | `@time 12h` | 12-hour with AM/PM | ### Barcode ```markdown @barcode CODE128 ${Sku} @barcode EAN13 ${EanCode} height=80 @barcode RASTER CODE128 ${Sku} @barcode RASTER CODE93 ABC-1234 ``` | Field | Values | |-------|--------| | Mode | Optional `RASTER` prefix; otherwise native ESC/POS | | Symbology | Native: `CODE128`, `EAN13`, `EAN8`, `CODE39`, `UPC-A`, `UPC-E`, `ITF`, `CODABAR`. Raster-only: `CODE93`, `CODE11` | | Data | Literal or `${Param}` | | `height` | Module / PNG height in dots (default: 64) | | `align` | `left`, `center`, `right` | | `show_text` | Native only: HRI below barcode | Raster barcodes stretch horizontally to full printable width. ### QR code ```markdown @qr https://example.com/receipt/${DocumentNumber} @qr ${PaymentUrl} size=6 ecc=H @qr RASTER ${PaymentUrl} version=5 scale=4 ecc=M ``` | Attribute | Native | Raster | |-----------|--------|--------| | Data | URL/text; may include `${Param}` | Same | | `size` | Module size 1–16 (default 4) | — | | `scale` | — | Pixels per module (default 4) | | `version` | — | QR version 1–40 (optional) | | `ecc` | `L`, `M`, `Q`, `H` (default `M`) | Same | | `align` | `left`, `center`, `right` | Same | --- ## 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 (or require CLI `--set`). 4. Pre-fill from last print session (in-memory). 5. Substitute into AST, then encode/print. Missing parameter at print time: block print and highlight unresolved names. --- ## Comments ```markdown ``` HTML-style comments are stripped before parse. --- ## Blank lines A blank line (or whitespace-only line) inserts `Feed(1)` — same paper advance as `@feed 1`. On print this becomes `ESC d 1` (reliable after raster graphics). --- ## Error reporting Parse errors include 1-based line and column. Typical causes: - Invalid barcode symbology - Invalid `${}` name - Missing required directive argument - Unknown `@time` format --- ## ESC/POS mapping (summary) | DSL | ESC/POS | |-----|---------| | `# heading` | Double width/height ON → text → OFF | | `## heading` | Bold ON → text → OFF | | `- item` | ASCII `* ` bullet + hanging wrap | | `[]` / `[ ]` / `[x]` | UTF-8 ☐ / 🗹 (trial; CP437 printers may not render) | | `:center:` | Justification center | | `@feed n` / blank line | ESC d n | | `@cut` | GS V partial cut | | `@barcode` | GS k or GS v 0 raster | | `@qr` | GS ( k or GS v 0 raster | | `@image` | GS v 0 raster bit image | | `@date` / `@time` | Plain text lines | Full command details: [PRINTING.md](PRINTING.md). --- ## Future extensions (not implemented) - `@table` for columnar line items - Nested lists / numbered lists - Bluetooth / network printer transports - Syntax highlighting in the editor --- ## Example document ```markdown # ${StoreName} :center: 123 Main Street --- @date @time Receipt: ${DocumentNumber} - Item one - Item two :right: TOTAL: ${GrandTotal} @barcode CODE128 ${DocumentNumber} @feed 2 @qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4 Thank you! @feed 4 @cut ```