BlueGit

timfa posprint

Files

posprint / docs / DSL-SPEC.md

DSL-SPEC.md

cfe7435b History
DSL-SPEC.md 5.8 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

Bullet lists

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

* this is a
  long line

Parameters

SyntaxEffect
${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
  • 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
## headingBold ON → text → OFF
- itemASCII * bullet + hanging wrap
: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### Bullet lists
58
59```markdown
60- Milk
61- Bread
62- Eggs
63```
64
65Each line must start with `- ` (dash + space). Consecutive list lines form one list block. A blank line ends the list.
66
67Wrapped lines use a hanging indent:
68
69```text
70* this is a
71 long line
72```
73
74### Parameters
75
76| Syntax | Effect |
77|--------|--------|
78| `${Name}` | Parameter placeholder (see Parameters) |
79
80Parameters work inside any text, and inside barcode/QR/image directives (below).
81
82**Example:**
83
84```markdown
85Receipt #${DocumentNumber}
86Date: ${Date}
87
88Item: ${ItemName} ${LineTotal}
89```
90
91### Horizontal rule
92
93```markdown
94---
95```
96
97Renders a dashed or solid separator line across the print width.
98
99---
100
101## Directives (block-level)
102
103Directives start with `@` at the beginning of a line.
104
105### Feed (blank lines)
106
107```markdown
108@feed 3
109```
110
111Advances paper by *n* lines.
112
113### Cut
114
115```markdown
116@cut
117```
118
119Partial cut after content (if printer supports). Often placed at document end.
120
121### Image
122
123```markdown
124@image path/to/logo.png
125@image ${LogoPath} width=50%
126@image assets/qr-promo.png width=384
127```
128
129| Attribute | Description |
130|-----------|-------------|
131| `path` (positional) | File path relative to `.pos` file or absolute; may be `${Param}` |
132| `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
133| `align` | `left` (default), `center`, `right` |
134
135Images are converted to monochrome raster data, dithered, and scaled to width.
136
137### Barcode
138
139```markdown
140@barcode CODE128 ${Sku}
141@barcode EAN13 ${EanCode} height=80
142```
143
144| Field | Values |
145|-------|--------|
146| Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |
147| Data | Literal or `${Param}` |
148| `height` | Module height in dots (default: 64) |
149| `align` | `left`, `center`, `right` |
150| `show_text` | `true` / `false` — HRI below barcode (default: true) |
151
152### QR code
153
154```markdown
155@qr https://example.com/receipt/${DocumentNumber}
156@qr ${PaymentUrl} size=6
157```
158
159| Attribute | Description |
160|-----------|-------------|
161| Data (positional) | URL or text; may include `${Param}` |
162| `size` | Module size 1–16 (default: 4) |
163| `ecc` | Error correction: `L`, `M`, `Q`, `H` (default: `M`) |
164| `align` | `left`, `center`, `right` |
165
166---
167
168## Parameters
169
170### Syntax
171
172```
173${ParameterName}
174```
175
176- **Names:** `[A-Za-z_][A-Za-z0-9_]*` (ASCII letters, digits, underscore)
177- **Case-sensitive:** `${DocNo}` and `${docno}` are different
178- **Uniqueness at input:** all occurrences of the same name share one value entered at print time
179
180### Where parameters are allowed
181
182| Location | Example |
183|----------|---------|
184| Text | `Order ${OrderId}` |
185| Barcode data | `@barcode CODE128 ${OrderId}` |
186| QR data | `@qr ${VerifyUrl}` |
187| Image path | `@image ${LogoPath}` |
188
189### Print-time behavior
190
1911. Before print, scan AST for all `${...}` tokens.
1922. Deduplicate by name.
1933. Show dialog with one field per unique name.
1944. Pre-fill from last print session (global or per-file — implementation choice).
1955. Substitute into AST, then render/print.
196
197Missing parameter at print time: block print and highlight unresolved names in UI.
198
199---
200
201## Comments
202
203```markdown
204<!-- This is a comment, not printed -->
205```
206
207HTML-style comments are stripped at parse time.
208
209---
210
211## Example document
212
213```markdown
214# ${StoreName}
215:center:
216
217123 Main Street
218Tel: ${StorePhone}
219
220---
221Date: ${Date} Time: ${Time}
222Receipt: ${DocumentNumber}
223
224Item Total
225${LineItems}
226
227---
228:right:
229**TOTAL: ${GrandTotal}**
230
231@barcode CODE128 ${DocumentNumber}
232@feed 2
233@qr https://shop.example.com/r/${DocumentNumber}
234
235Thank you!
236@feed 4
237@cut
238```
239
240`${LineItems}` might be pre-formatted multi-line text passed as a single parameter (v1); structured line items are a future extension.
241
242---
243
244## Parse errors
245
246The parser reports:
247
248- Unknown directive
249- Invalid barcode symbology
250- Invalid `${}` name
251- Missing required directive argument
252
253Errors include 1-based line and column for editor highlighting.
254
255---
256
257## ESC/POS mapping (summary)
258
259| DSL | ESC/POS |
260|-----|---------|
261| `# heading` | Double width/height ON → text → OFF |
262| `## heading` | Bold ON → text → OFF |
263| `- item` | ASCII `* ` bullet + hanging wrap |
264| `:center:` | Justification center |
265| `@feed n` | Print and feed n lines |
266| `@cut` | GS V partial cut |
267| `@barcode` | GS k / CODE128 native |
268| `@qr` | GS ( k QR model 2 |
269| `@image` | GS v 0 raster bit image |
270
271Full command details live in the print encoder module; see [PRINTING.md](PRINTING.md).
272
273---
274
275## Future extensions (not implemented)
276
277- `@table` for columnar line items
278- `UPC-A` barcodes
279- Conditionals: `@if ${HasDiscount} ... @endif`
280- Loops / repeating sections
281- `@signature` for custom ESC/POS hex escape
282- Multiple code pages / Unicode subset
283- Syntax highlighting in the editor