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.

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, UPC-A (v1 subset)
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 v1)

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