BlueGit

timfa posprint

Files

posprint / docs / DSL-SPEC.md

DSL-SPEC.md

DSL-SPEC.md 5.7 KiB Download Raw

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.

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.

Thank you for your purchase!
Visit us again soon.

Headings

# Store Name
## Receipt
  • # → large / double-height text (ESC/POS emphasis)
  • ## → bold emphasis
  • Maximum two levels in v1

Alignment

Prefix a paragraph with alignment markers:

:center:
Your Store Name

:right:
Total: ${Amount}
MarkerEffect
:left:Left (default)
:center:Centered
:right:Right-aligned

Inline markup

SyntaxEffect
**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:

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

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

Horizontal rule

---

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)

@feed 3

Advances paper by n lines.

Cut

@cut

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

Image

@image path/to/logo.png
@image ${LogoPath} width=50%
@image assets/qr-promo.png width=384
AttributeDescription
path (positional)File path relative to .pos file or absolute; may be ${Param}
widthNN% of printable width, or absolute dots (e.g. 384)
alignleft (default), center, right

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

Barcode

@barcode CODE128 ${Sku}
@barcode EAN13 ${EanCode} height=80
FieldValues
SymbologyCODE128, EAN13, EAN8, CODE39
DataLiteral or ${Param}
heightModule height in dots (default: 64)
alignleft, center, right
show_texttrue / false — HRI below barcode (default: true)

QR code

@qr https://example.com/receipt/${DocumentNumber}
@qr ${PaymentUrl} size=6
AttributeDescription
Data (positional)URL or text; may include ${Param}
sizeModule size 1–16 (default: 4)
eccError correction: L, M, Q, H (default: M)
alignleft, 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

LocationExample
TextOrder ${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

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

HTML-style comments are stripped at parse time.

---

Example document

# ${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)

DSLESC/POS
# headingDouble width/height ON → text → OFF
**bold**Bold ON/OFF
:center:Justification center
@feed nPrint and feed n lines
@cutGS V partial cut
@barcodeGS k / CODE128 native
@qrGS ( k QR model 2
@imageGS v 0 raster bit image

Full command details live in the print encoder module; see 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
Source
1# Document DSL specification
2
3A lightweight, markdown-inspired syntax for POS receipt templates. The DSL compiles to an AST and then to ESC/POS bytes or a screen preview.
4
5> **Implementation:** Parser in `src/dsl/parser.rs`. All constructs below are implemented unless listed under [Future extensions](#future-extensions-not-implemented).
6
7**Design goals:** easy to author, line-oriented, explicit about POS-specific features (barcodes, cut, feed), parameter-friendly.
8
9---
10
11## Document structure
12
13A document is a sequence of **blocks** separated by blank lines. Blocks cannot be nested except for inline markup within text blocks.
14
15---
16
17## Text blocks
18
19### Paragraphs
20
21Plain text with optional inline markup. One or more consecutive non-empty lines form a paragraph.
22
23```markdown
24Thank you for your purchase!
25Visit us again soon.
26```
27
28### Headings
29
30```markdown
31# Store Name
32## Receipt
33```
34
35- `#` → large / double-height text (ESC/POS emphasis)
36- `##` → bold emphasis
37- Maximum two levels in v1
38
39### Alignment
40
41Prefix a paragraph with alignment markers:
42
43```markdown
44:center:
45Your Store Name
46
47:right:
48Total: ${Amount}
49```
50
51| Marker | Effect |
52|--------|--------|
53| `:left:` | Left (default) |
54| `:center:` | Centered |
55| `:right:` | Right-aligned |
56
57### Inline markup
58
59| Syntax | Effect |
60|--------|--------|
61| `**text**` | Bold |
62| `*text*` | Italic / emphasized (printer secondary font if available) |
63| `` `text` `` | Monospace / condensed |
64| `${Name}` | Parameter placeholder (see Parameters) |
65
66Parameters work inside any text, and inside barcode/QR/image directives (below).
67
68**Example:**
69
70```markdown
71Receipt #${DocumentNumber}
72Date: ${Date}
73
74Item: ${ItemName} **${LineTotal}**
75```
76
77### Horizontal rule
78
79```markdown
80---
81```
82
83Renders a dashed or solid separator line across the print width.
84
85---
86
87## Directives (block-level)
88
89Directives start with `@` at the beginning of a line.
90
91### Feed (blank lines)
92
93```markdown
94@feed 3
95```
96
97Advances paper by *n* lines.
98
99### Cut
100
101```markdown
102@cut
103```
104
105Partial cut after content (if printer supports). Often placed at document end.
106
107### Image
108
109```markdown
110@image path/to/logo.png
111@image ${LogoPath} width=50%
112@image assets/qr-promo.png width=384
113```
114
115| Attribute | Description |
116|-----------|-------------|
117| `path` (positional) | File path relative to `.pos` file or absolute; may be `${Param}` |
118| `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
119| `align` | `left` (default), `center`, `right` |
120
121Images are converted to monochrome raster data, dithered, and scaled to width.
122
123### Barcode
124
125```markdown
126@barcode CODE128 ${Sku}
127@barcode EAN13 ${EanCode} height=80
128```
129
130| Field | Values |
131|-------|--------|
132| Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |
133| Data | Literal or `${Param}` |
134| `height` | Module height in dots (default: 64) |
135| `align` | `left`, `center`, `right` |
136| `show_text` | `true` / `false` — HRI below barcode (default: true) |
137
138### QR code
139
140```markdown
141@qr https://example.com/receipt/${DocumentNumber}
142@qr ${PaymentUrl} size=6
143```
144
145| Attribute | Description |
146|-----------|-------------|
147| Data (positional) | URL or text; may include `${Param}` |
148| `size` | Module size 1–16 (default: 4) |
149| `ecc` | Error correction: `L`, `M`, `Q`, `H` (default: `M`) |
150| `align` | `left`, `center`, `right` |
151
152---
153
154## Parameters
155
156### Syntax
157
158```
159${ParameterName}
160```
161
162- **Names:** `[A-Za-z_][A-Za-z0-9_]*` (ASCII letters, digits, underscore)
163- **Case-sensitive:** `${DocNo}` and `${docno}` are different
164- **Uniqueness at input:** all occurrences of the same name share one value entered at print time
165
166### Where parameters are allowed
167
168| Location | Example |
169|----------|---------|
170| Text | `Order ${OrderId}` |
171| Barcode data | `@barcode CODE128 ${OrderId}` |
172| QR data | `@qr ${VerifyUrl}` |
173| Image path | `@image ${LogoPath}` |
174
175### Print-time behavior
176
1771. Before print, scan AST for all `${...}` tokens.
1782. Deduplicate by name.
1793. Show dialog with one field per unique name.
1804. Pre-fill from last print session (global or per-file — implementation choice).
1815. Substitute into AST, then render/print.
182
183Missing parameter at print time: block print and highlight unresolved names in UI.
184
185---
186
187## Comments
188
189```markdown
190<!-- This is a comment, not printed -->
191```
192
193HTML-style comments are stripped at parse time.
194
195---
196
197## Example document
198
199```markdown
200# ${StoreName}
201:center:
202
203123 Main Street
204Tel: ${StorePhone}
205
206---
207Date: ${Date} Time: ${Time}
208Receipt: ${DocumentNumber}
209
210Item Total
211${LineItems}
212
213---
214:right:
215**TOTAL: ${GrandTotal}**
216
217@barcode CODE128 ${DocumentNumber}
218@feed 2
219@qr https://shop.example.com/r/${DocumentNumber}
220
221Thank you!
222@feed 4
223@cut
224```
225
226`${LineItems}` might be pre-formatted multi-line text passed as a single parameter (v1); structured line items are a future extension.
227
228---
229
230## Parse errors
231
232The parser reports:
233
234- Unknown directive
235- Invalid barcode symbology
236- Unclosed `**` or `` ` ``
237- Invalid `${}` name
238- Missing required directive argument
239
240Errors include 1-based line and column for editor highlighting.
241
242---
243
244## ESC/POS mapping (summary)
245
246| DSL | ESC/POS |
247|-----|---------|
248| `# heading` | Double width/height ON → text → OFF |
249| `**bold**` | Bold ON/OFF |
250| `:center:` | Justification center |
251| `@feed n` | Print and feed n lines |
252| `@cut` | GS V partial cut |
253| `@barcode` | GS k / CODE128 native |
254| `@qr` | GS ( k QR model 2 |
255| `@image` | GS v 0 raster bit image |
256
257Full command details live in the print encoder module; see [PRINTING.md](PRINTING.md).
258
259---
260
261## Future extensions (not implemented)
262
263- `@table` for columnar line items
264- `UPC-A` barcodes
265- Conditionals: `@if ${HasDiscount} ... @endif`
266- Loops / repeating sections
267- `@signature` for custom ESC/POS hex escape
268- Multiple code pages / Unicode subset
269- Syntax highlighting in the editor