BlueGit

timfa posprint

Files

posprint / docs / DSL-SPEC.md

DSL-SPEC.md

DSL-SPEC.md 6.9 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. 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.

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)

Checkboxes

SyntaxPrinted result
[] or [ ]Empty checkbox (raster)
[x] or [X]Checked checkbox with tick (raster)

Lines that contain checkboxes keep the printer’s normal text font; the box/tick is two Font A user-defined characters (ESC &). Preview uses Unicode ☐ / ☑.

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

Example:

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

[x] Paid
[] Pending

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 and scaled to width (never wider than printable_dots).

Date / time

@date
@date DD-MM-YYYY
@time
@time 12h
@time 24h
DirectiveBehaviour
@dateSystem regional short date (%x)
@date PATTERNCustom pattern (YYYY, MM, DD, …)
@time / @time 24h24-hour HH:MM
@time 12h12-hour with AM/PM

Barcode

@barcode CODE128 ${Sku}
@barcode EAN13 ${EanCode} height=80
@barcode RASTER CODE128 ${Sku}
@barcode RASTER CODE93 ABC-1234
FieldValues
ModeOptional RASTER prefix; otherwise native ESC/POS
SymbologyNative: CODE128, EAN13, EAN8, CODE39, UPC-A, UPC-E, ITF, CODABAR. Raster-only: CODE93, CODE11
DataLiteral or ${Param}
heightModule / PNG height in dots (default: 64)
alignleft, center, right
show_textNative only: HRI below barcode

Raster barcodes stretch horizontally to full printable width.

QR code

@qr https://example.com/receipt/${DocumentNumber}
@qr ${PaymentUrl} size=6 ecc=H
@qr RASTER ${PaymentUrl} version=5 scale=4 ecc=M
AttributeNativeRaster
DataURL/text; may include ${Param}Same
sizeModule size 1–16 (default 4)—
scale—Pixels per module (default 4)
version—QR version 1–40 (optional)
eccL, M, Q, H (default M)Same
alignleft, center, rightSame

---

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

<!-- this is not printed -->

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)

DSLESC/POS
# headingDouble width/height ON → text → OFF
## headingBold ON → text → OFF
- itemASCII * bullet + hanging wrap
[] / [ ] / [x]User-defined Font A chars (ESC &) for checkbox; text stays native
:center:Justification center
@feed n / blank lineESC d n
@cutGS V partial cut
@barcodeGS k or GS v 0 raster
@qrGS ( k or GS v 0 raster
@imageGS v 0 raster bit image
@date / @timePlain text lines

Full command details: 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

# ${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
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**. Blank lines become paper feeds (`@feed 1`). Blocks are not nested except for `${parameters}` inside text.
14
15---
16
17## Text blocks
18
19### Paragraphs
20
21Plain text (and `${parameters}`). One or more consecutive non-empty lines form a paragraph. There is **no** inline bold/italic/code markup.
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
80### Checkboxes
81
82| Syntax | Printed result |
83|--------|----------------|
84| `[]` or `[ ]` | Empty checkbox (raster) |
85| `[x]` or `[X]` | Checked checkbox with tick (raster) |
86
87Lines that contain checkboxes keep the printer’s normal text font; the box/tick is two Font A user-defined characters (ESC `&`). Preview uses Unicode ☐ / ☑.
88
89Parameters work inside any text, and inside barcode/QR/image directives (below).
90
91**Example:**
92
93```markdown
94Receipt #${DocumentNumber}
95Date: ${Date}
96
97[x] Paid
98[] Pending
99
100Item: ${ItemName} ${LineTotal}
101```
102
103### Horizontal rule
104
105```markdown
106---
107```
108
109Renders a dashed or solid separator line across the print width.
110
111---
112
113## Directives (block-level)
114
115Directives start with `@` at the beginning of a line.
116
117### Feed (blank lines)
118
119```markdown
120@feed 3
121```
122
123Advances paper by *n* lines.
124
125### Cut
126
127```markdown
128@cut
129```
130
131Partial cut after content (if printer supports). Often placed at document end.
132
133### Image
134
135```markdown
136@image path/to/logo.png
137@image ${LogoPath} width=50%
138@image assets/qr-promo.png width=384
139```
140
141| Attribute | Description |
142|-----------|-------------|
143| `path` (positional) | File path relative to `.pos` file or absolute; may be `${Param}` |
144| `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
145| `align` | `left` (default), `center`, `right` |
146
147Images are converted to monochrome raster data and scaled to width (never wider than `printable_dots`).
148
149### Date / time
150
151```markdown
152@date
153@date DD-MM-YYYY
154@time
155@time 12h
156@time 24h
157```
158
159| Directive | Behaviour |
160|-----------|-----------|
161| `@date` | System regional short date (`%x`) |
162| `@date PATTERN` | Custom pattern (`YYYY`, `MM`, `DD`, …) |
163| `@time` / `@time 24h` | 24-hour `HH:MM` |
164| `@time 12h` | 12-hour with AM/PM |
165
166### Barcode
167
168```markdown
169@barcode CODE128 ${Sku}
170@barcode EAN13 ${EanCode} height=80
171@barcode RASTER CODE128 ${Sku}
172@barcode RASTER CODE93 ABC-1234
173```
174
175| Field | Values |
176|-------|--------|
177| Mode | Optional `RASTER` prefix; otherwise native ESC/POS |
178| Symbology | Native: `CODE128`, `EAN13`, `EAN8`, `CODE39`, `UPC-A`, `UPC-E`, `ITF`, `CODABAR`. Raster-only: `CODE93`, `CODE11` |
179| Data | Literal or `${Param}` |
180| `height` | Module / PNG height in dots (default: 64) |
181| `align` | `left`, `center`, `right` |
182| `show_text` | Native only: HRI below barcode |
183
184Raster barcodes stretch horizontally to full printable width.
185
186### QR code
187
188```markdown
189@qr https://example.com/receipt/${DocumentNumber}
190@qr ${PaymentUrl} size=6 ecc=H
191@qr RASTER ${PaymentUrl} version=5 scale=4 ecc=M
192```
193
194| Attribute | Native | Raster |
195|-----------|--------|--------|
196| Data | URL/text; may include `${Param}` | Same |
197| `size` | Module size 1–16 (default 4) | — |
198| `scale` | — | Pixels per module (default 4) |
199| `version` | — | QR version 1–40 (optional) |
200| `ecc` | `L`, `M`, `Q`, `H` (default `M`) | Same |
201| `align` | `left`, `center`, `right` | Same |
202
203---
204
205## Parameters
206
207### Syntax
208
209```
210${ParameterName}
211```
212
213- **Names:** `[A-Za-z_][A-Za-z0-9_]*` (ASCII letters, digits, underscore)
214- **Case-sensitive:** `${DocNo}` and `${docno}` are different
215- **Uniqueness at input:** all occurrences of the same name share one value entered at print time
216
217### Where parameters are allowed
218
219| Location | Example |
220|----------|---------|
221| Text | `Order ${OrderId}` |
222| Barcode data | `@barcode CODE128 ${OrderId}` |
223| QR data | `@qr ${VerifyUrl}` |
224| Image path | `@image ${LogoPath}` |
225
226### Print-time behavior
227
2281. Before print, scan AST for all `${...}` tokens.
2292. Deduplicate by name.
2303. Show dialog with one field per unique name (or require CLI `--set`).
2314. Pre-fill from last print session (in-memory).
2325. Substitute into AST, then encode/print.
233
234Missing parameter at print time: block print and highlight unresolved names.
235
236---
237
238## Comments
239
240```markdown
241<!-- this is not printed -->
242```
243
244HTML-style comments are stripped before parse.
245
246---
247
248## Blank lines
249
250A 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).
251
252---
253
254## Error reporting
255
256Parse errors include 1-based line and column. Typical causes:
257
258- Invalid barcode symbology
259- Invalid `${}` name
260- Missing required directive argument
261- Unknown `@time` format
262
263---
264
265## ESC/POS mapping (summary)
266
267| DSL | ESC/POS |
268|-----|---------|
269| `# heading` | Double width/height ON → text → OFF |
270| `## heading` | Bold ON → text → OFF |
271| `- item` | ASCII `* ` bullet + hanging wrap |
272| `[]` / `[ ]` / `[x]` | User-defined Font A chars (ESC `&`) for checkbox; text stays native |
273| `:center:` | Justification center |
274| `@feed n` / blank line | ESC d n |
275| `@cut` | GS V partial cut |
276| `@barcode` | GS k or GS v 0 raster |
277| `@qr` | GS ( k or GS v 0 raster |
278| `@image` | GS v 0 raster bit image |
279| `@date` / `@time` | Plain text lines |
280
281Full command details: [PRINTING.md](PRINTING.md).
282
283---
284
285## Future extensions (not implemented)
286
287- `@table` for columnar line items
288- Nested lists / numbered lists
289- Bluetooth / network printer transports
290- Syntax highlighting in the editor
291
292---
293
294## Example document
295
296```markdown
297# ${StoreName}
298:center:
299
300123 Main Street
301
302---
303@date
304@time
305Receipt: ${DocumentNumber}
306
307- Item one
308- Item two
309
310:right:
311TOTAL: ${GrandTotal}
312
313@barcode CODE128 ${DocumentNumber}
314@feed 2
315@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
316
317Thank you!
318@feed 4
319@cut
320```