BlueGit

timfa posprint

Files

posprint / docs / DSL-SPEC.md

DSL-SPEC.md

feat: include paired Classic Bluetooth SPP printers in discovery
timfa project_84475926_bot_3b4fb417c41b9b24a7422b6452f025d2 · pushed by timfa · 8 weeks ago
8b514b7f History
DSL-SPEC.md 8.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. 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. Consecutive spaces are preserved (not collapsed), including leading indentation, so authors can pad columns manually. Trailing spaces on a line are trimmed.

Thank you for your purchase!
Visit us again soon.
Item               12.00
                          rightish note

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

Same line, multiple markers: ESC/POS can only justify a whole line (ESC a), so :left: appel:right:10 cannot be true dual-alignment. posprint pads with spaces to chars_per_line (after ${Param} substitution) so left/center/right text shares one printed line. Marker order is normalized to Left → Center → Right (e.g. :right:10:left:appel prints as appel … 10). If the parts do not fit, they fall back to separate lines.

:left: ${Item}:right: ${Price}

Standalone :center: / :right: paragraphs (one alignment per line) still use printer justification.

Bullet lists

- Groceries
  - Milk
  - Eggs
- Wash car

Each line must start with optional indent (2 spaces or 1 tab per level) then - . Consecutive list lines form one list block. A blank line ends the list.

DepthPrinted bullet
0 (top)*
≥ 1indented -

Wrapped lines use a hanging indent matching the bullet prefix width:

* this is a
  long line
  - nested item that
    wraps too

Parameters

SyntaxEffect
${Name}Text parameter placeholder (see Parameters)
$[Name]Bool checkbox parameter → [ ] / [x]

${Name} and $[Name] must not share the same name.

Checkboxes

SyntaxPrinted result
[] or [ ][ ]
[x] / [X][x]
$[Name][ ] or [x] from a bool parameter

ASCII brackets + x stay inline in the native CP437 font. Do not use Unicode ☐ / √ — many ESC/POS printers map those to CJK glyphs. ${Name} and $[Name] cannot share a name.

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

Example:

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

$[Paid] 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}; multiple words joined until the first attribute token (height=…, align=…); URLs with ?a=1 are data
heightModule / PNG height in dots (default: 64)
alignleft, center, right
show_textNative only: print HRI text under barcode (default: off; set show_text=true to enable)

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}; multiple words joined until the first attribute token (size=…, ecc=…); URLs with ?a=1 are dataSame
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}   # text
$[ParameterName]   # boolean checkbox → [ ] / [x]
  • Names: [A-Za-z_][A-Za-z0-9_]* (ASCII letters, digits, underscore)
  • Case-sensitive: ${DocNo} and ${docno} are different
  • No mixed types: the same name must not appear as both ${…} and $[…]
  • Uniqueness at input: all occurrences of the same name share one value entered at print time

Where parameters are allowed

LocationExample
TextOrder ${OrderId} / $[Paid] Paid
Barcode data@barcode CODE128 ${OrderId} (${…} only)
QR data@qr ${VerifyUrl} (${…} only)
Image path@image ${LogoPath} (${…} only)

Print-time behavior

1. Before print, scan AST for all ${…} and $[…] tokens. 2. Deduplicate by name (kinds must not conflict — enforced at parse). 3. Show dialog: text field per ${…}, checkbox per $[…] (or require CLI --set). 4. Bool values: true/false (also 1/0, yes/no). 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
- item / - nestedTop: ASCII * ; nested: indented - + hanging wrap
[] / [ ] / [x] / $[Name]ASCII [ ] / [x] (CP437-safe, inline)
: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
  • Numbered lists
  • Network TCP 9100 printer transport
  • BLE (GATT) printer transport (Classic Bluetooth SPP is implemented)
  • 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. Consecutive spaces are preserved (not collapsed), including leading indentation, so authors can pad columns manually. Trailing spaces on a line are trimmed.
22
23```markdown
24Thank you for your purchase!
25Visit us again soon.
26Item 12.00
27 rightish note
28```
29
30### Headings
31
32```markdown
33# Store Name
34## Receipt
35```
36
37- `#` → large / double-height text (ESC/POS emphasis)
38- `##` → bold emphasis
39- Maximum two levels in v1
40
41### Alignment
42
43Prefix a paragraph with alignment markers:
44
45```markdown
46:center:
47Your Store Name
48
49:right:
50Total: ${Amount}
51```
52
53| Marker | Effect |
54|--------|--------|
55| `:left:` | Left (default) |
56| `:center:` | Centered |
57| `:right:` | Right-aligned |
58
59**Same line, multiple markers:** ESC/POS can only justify a whole line (`ESC a`), so `:left: appel:right:10` cannot be true dual-alignment. posprint pads with spaces to `chars_per_line` (after `${Param}` substitution) so left/center/right text shares one printed line. Marker order is normalized to Left → Center → Right (e.g. `:right:10:left:appel` prints as `appel` … `10`). If the parts do not fit, they fall back to separate lines.
60
61```markdown
62:left: ${Item}:right: ${Price}
63```
64
65Standalone `:center:` / `:right:` paragraphs (one alignment per line) still use printer justification.
66
67### Bullet lists
68
69```markdown
70- Groceries
71 - Milk
72 - Eggs
73- Wash car
74```
75
76Each line must start with optional indent (2 spaces or 1 tab per level) then `- `. Consecutive list lines form one list block. A blank line ends the list.
77
78| Depth | Printed bullet |
79|-------|----------------|
80| 0 (top) | `* ` |
81| ≥ 1 | indented `- ` |
82
83Wrapped lines use a hanging indent matching the bullet prefix width:
84
85```text
86* this is a
87 long line
88 - nested item that
89 wraps too
90```
91
92### Parameters
93
94| Syntax | Effect |
95|--------|--------|
96| `${Name}` | Text parameter placeholder (see Parameters) |
97| `$[Name]` | Bool checkbox parameter → `[ ]` / `[x]` |
98
99`${Name}` and `$[Name]` must not share the same name.
100
101### Checkboxes
102
103| Syntax | Printed result |
104|--------|----------------|
105| `[]` or `[ ]` | `[ ]` |
106| `[x]` / `[X]` | `[x]` |
107| `$[Name]` | `[ ]` or `[x]` from a bool parameter |
108
109ASCII brackets + `x` stay inline in the native CP437 font. Do not use Unicode ☐ / √ — many ESC/POS printers map those to CJK glyphs. `${Name}` and `$[Name]` cannot share a name.
110
111Parameters work inside any text, and inside barcode/QR/image directives (below).
112
113**Example:**
114
115```markdown
116Receipt #${DocumentNumber}
117Date: ${Date}
118
119$[Paid] Paid
120[] Pending
121
122Item: ${ItemName} ${LineTotal}
123```
124
125### Horizontal rule
126
127```markdown
128---
129```
130
131Renders a dashed or solid separator line across the print width.
132
133---
134
135## Directives (block-level)
136
137Directives start with `@` at the beginning of a line.
138
139### Feed (blank lines)
140
141```markdown
142@feed 3
143```
144
145Advances paper by *n* lines.
146
147### Cut
148
149```markdown
150@cut
151```
152
153Partial cut after content (if printer supports). Often placed at document end.
154
155### Image
156
157```markdown
158@image path/to/logo.png
159@image ${LogoPath} width=50%
160@image assets/qr-promo.png width=384
161```
162
163| Attribute | Description |
164|-----------|-------------|
165| `path` (positional) | File path relative to `.pos` file or absolute; may be `${Param}` |
166| `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
167| `align` | `left` (default), `center`, `right` |
168
169Images are converted to monochrome raster data and scaled to width (never wider than `printable_dots`).
170
171### Date / time
172
173```markdown
174@date
175@date DD-MM-YYYY
176@time
177@time 12h
178@time 24h
179```
180
181| Directive | Behaviour |
182|-----------|-----------|
183| `@date` | System regional short date (`%x`) |
184| `@date PATTERN` | Custom pattern (`YYYY`, `MM`, `DD`, …) |
185| `@time` / `@time 24h` | 24-hour `HH:MM` |
186| `@time 12h` | 12-hour with AM/PM |
187
188### Barcode
189
190```markdown
191@barcode CODE128 ${Sku}
192@barcode EAN13 ${EanCode} height=80
193@barcode RASTER CODE128 ${Sku}
194@barcode RASTER CODE93 ABC-1234
195```
196
197| Field | Values |
198|-------|--------|
199| Mode | Optional `RASTER` prefix; otherwise native ESC/POS |
200| Symbology | Native: `CODE128`, `EAN13`, `EAN8`, `CODE39`, `UPC-A`, `UPC-E`, `ITF`, `CODABAR`. Raster-only: `CODE93`, `CODE11` |
201| Data | Literal or `${Param}`; multiple words joined until the first attribute token (`height=…`, `align=…`); URLs with `?a=1` are data |
202| `height` | Module / PNG height in dots (default: 64) |
203| `align` | `left`, `center`, `right` |
204| `show_text` | Native only: print HRI text under barcode (default: off; set `show_text=true` to enable) |
205
206Raster barcodes stretch horizontally to full printable width.
207
208### QR code
209
210```markdown
211@qr https://example.com/receipt/${DocumentNumber}
212@qr ${PaymentUrl} size=6 ecc=H
213@qr RASTER ${PaymentUrl} version=5 scale=4 ecc=M
214```
215
216| Attribute | Native | Raster |
217|-----------|--------|--------|
218| Data | URL/text; may include `${Param}`; multiple words joined until the first attribute token (`size=…`, `ecc=…`); URLs with `?a=1` are data | Same |
219| `size` | Module size 1–16 (default 4) | — |
220| `scale` | — | Pixels per module (default 4) |
221| `version` | — | QR version 1–40 (optional) |
222| `ecc` | `L`, `M`, `Q`, `H` (default `M`) | Same |
223| `align` | `left`, `center`, `right` | Same |
224
225---
226
227## Parameters
228
229### Syntax
230
231```
232${ParameterName} # text
233$[ParameterName] # boolean checkbox → [ ] / [x]
234```
235
236- **Names:** `[A-Za-z_][A-Za-z0-9_]*` (ASCII letters, digits, underscore)
237- **Case-sensitive:** `${DocNo}` and `${docno}` are different
238- **No mixed types:** the same name must not appear as both `${…}` and `$[…]`
239- **Uniqueness at input:** all occurrences of the same name share one value entered at print time
240
241### Where parameters are allowed
242
243| Location | Example |
244|----------|---------|
245| Text | `Order ${OrderId}` / `$[Paid] Paid` |
246| Barcode data | `@barcode CODE128 ${OrderId}` (`${…}` only) |
247| QR data | `@qr ${VerifyUrl}` (`${…}` only) |
248| Image path | `@image ${LogoPath}` (`${…}` only) |
249
250### Print-time behavior
251
2521. Before print, scan AST for all `${…}` and `$[…]` tokens.
2532. Deduplicate by name (kinds must not conflict — enforced at parse).
2543. Show dialog: text field per `${…}`, checkbox per `$[…]` (or require CLI `--set`).
2554. Bool values: `true`/`false` (also `1`/`0`, `yes`/`no`).
2564. Pre-fill from last print session (in-memory).
2575. Substitute into AST, then encode/print.
258
259Missing parameter at print time: block print and highlight unresolved names.
260
261---
262
263## Comments
264
265```markdown
266<!-- this is not printed -->
267```
268
269HTML-style comments are stripped before parse.
270
271---
272
273## Blank lines
274
275A 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).
276
277---
278
279## Error reporting
280
281Parse errors include 1-based line and column. Typical causes:
282
283- Invalid barcode symbology
284- Invalid `${}` name
285- Missing required directive argument
286- Unknown `@time` format
287
288---
289
290## ESC/POS mapping (summary)
291
292| DSL | ESC/POS |
293|-----|---------|
294| `# heading` | Double width/height ON → text → OFF |
295| `## heading` | Bold ON → text → OFF |
296| `- item` / ` - nested` | Top: ASCII `* `; nested: indented `- ` + hanging wrap |
297| `[]` / `[ ]` / `[x]` / `$[Name]` | ASCII `[ ]` / `[x]` (CP437-safe, inline) |
298| `:center:` | Justification center |
299| `@feed n` / blank line | ESC d n |
300| `@cut` | GS V partial cut |
301| `@barcode` | GS k or GS v 0 raster |
302| `@qr` | GS ( k or GS v 0 raster |
303| `@image` | GS v 0 raster bit image |
304| `@date` / `@time` | Plain text lines |
305
306Full command details: [PRINTING.md](PRINTING.md).
307
308---
309
310## Future extensions (not implemented)
311
312- `@table` for columnar line items
313- Numbered lists
314- Network TCP 9100 printer transport
315- BLE (GATT) printer transport (Classic Bluetooth SPP is implemented)
316- Syntax highlighting in the editor
317
318---
319
320## Example document
321
322```markdown
323# ${StoreName}
324:center:
325
326123 Main Street
327
328---
329@date
330@time
331Receipt: ${DocumentNumber}
332
333- Item one
334- Item two
335
336:right:
337TOTAL: ${GrandTotal}
338
339@barcode CODE128 ${DocumentNumber}
340@feed 2
341@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
342
343Thank you!
344@feed 4
345@cut
346```