BlueGit

timfa posprint

Files

posprint / docs / FILE-FORMAT.md

FILE-FORMAT.md

FILE-FORMAT.md 3.9 KiB Download Raw

.pos file format

A .pos file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.

Format: JSON envelope with a .pos extension (human-readable, git-friendly). MIME type (suggested): application/vnd.posprint+json

---

Top-level schema

{
  "version": 1,
  "metadata": { ... },
  "body": "..."
}
FieldTypeRequiredDescription
versionnumberyesFile format version (currently 1)
metadataobjectyesDocument settings
bodystringyesDSL source (UTF-8, \n line endings normalized on load)

---

Metadata schema (version 1)

{
  "title": "Sales Receipt",
  "page_width_mm": 80,
  "preview_mode": "autoscale",
  "chars_per_line": 48,
  "codepage": "CP437",
  "cut_after_print": true
}
FieldTypeDefaultDescription
titlestring?nullDisplay name in app title / recent files
page_width_mmnumber80Physical paper width: 58 or 80 (others allowed)
preview_mode"autoscale" \"fixed""autoscale"How preview panel sizes content
chars_per_linenumber?derivedOverride character width for preview; derived from mm if omitted
codepagestring?"CP437"Character encoding for ESC/POS text
cut_after_printbooleantrueAppend cut command when printing if doc has no @cut

Page width derivation

page_width_mmTypical dots (203 DPI)Default chars_per_line (Font A)
5838432
8057648

---

Example file

receipt.pos:

{
  "version": 1,
  "metadata": {
    "title": "Standard Receipt",
    "page_width_mm": 80,
    "preview_mode": "autoscale",
    "codepage": "CP437",
    "cut_after_print": true
  },
  "body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\n**TOTAL: ${GrandTotal}**\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
}

For readability, the app may save body with literal newlines (pretty-printed JSON) when the user chooses “formatted save”; both pretty and escaped forms are valid.

---

Asset resolution

  • Paths in @image directives are resolved relative to the directory containing the .pos file unless absolute.
  • Bundled assets: optional assets/ subfolder next to the template.
  • Parameterized image paths (${LogoPath}) resolve after substitution; relative paths still anchor to the .pos file directory.

---

Version migration

FromToMigration
—1Initial release

On load, if version is newer than app supports → error with upgrade message. If older → run migration chain (none yet).

---

Alternative considered: two-file bundle

Rejected for v1: .pos + sidecar .pos.json adds friction. Single JSON file keeps save/load atomic.

A future .poszip could bundle images for portable templates.

---

Validation rules

On save:

  • version must equal supported version
  • page_width_mm > 0
  • body must be valid UTF-8

On load:

  • Parse JSON; validate schema
  • Parse body with DSL parser; warnings shown in UI but file still loads

---

TypeScript / Rust types (reference)

interface PosFile {
  version: number;
  metadata: PosMetadata;
  body: string;
}

interface PosMetadata {
  title?: string;
  page_width_mm: number;
  preview_mode: "autoscale" | "fixed";
  chars_per_line?: number;
  codepage?: string;
  cut_after_print?: boolean;
}

Rust types use serde derive in src/io/mod.rs and are used directly by the egui app (no IPC layer).

Source
1# `.pos` file format
2
3A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.
4
5**Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly).
6**MIME type (suggested):** `application/vnd.posprint+json`
7
8---
9
10## Top-level schema
11
12```json
13{
14 "version": 1,
15 "metadata": { ... },
16 "body": "..."
17}
18```
19
20| Field | Type | Required | Description |
21|-------|------|----------|-------------|
22| `version` | `number` | yes | File format version (currently `1`) |
23| `metadata` | `object` | yes | Document settings |
24| `body` | `string` | yes | DSL source (UTF-8, `\n` line endings normalized on load) |
25
26---
27
28## Metadata schema (version 1)
29
30```json
31{
32 "title": "Sales Receipt",
33 "page_width_mm": 80,
34 "preview_mode": "autoscale",
35 "chars_per_line": 48,
36 "codepage": "CP437",
37 "cut_after_print": true
38}
39```
40
41| Field | Type | Default | Description |
42|-------|------|---------|-------------|
43| `title` | `string?` | `null` | Display name in app title / recent files |
44| `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |
45| `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |
46| `chars_per_line` | `number?` | derived | Override character width for preview; derived from mm if omitted |
47| `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |
48| `cut_after_print` | `boolean` | `true` | Append cut command when printing if doc has no `@cut` |
49
50### Page width derivation
51
52| `page_width_mm` | Typical dots (203 DPI) | Default `chars_per_line` (Font A) |
53|-----------------|------------------------|-----------------------------------|
54| 58 | 384 | 32 |
55| 80 | 576 | 48 |
56
57---
58
59## Example file
60
61**`receipt.pos`:**
62
63```json
64{
65 "version": 1,
66 "metadata": {
67 "title": "Standard Receipt",
68 "page_width_mm": 80,
69 "preview_mode": "autoscale",
70 "codepage": "CP437",
71 "cut_after_print": true
72 },
73 "body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\n**TOTAL: ${GrandTotal}**\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
74}
75```
76
77For readability, the app may save `body` with literal newlines (pretty-printed JSON) when the user chooses “formatted save”; both pretty and escaped forms are valid.
78
79---
80
81## Asset resolution
82
83- Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute.
84- Bundled assets: optional `assets/` subfolder next to the template.
85- Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory.
86
87---
88
89## Version migration
90
91| From | To | Migration |
92|------|-----|-----------|
93| — | 1 | Initial release |
94
95On load, if `version` is newer than app supports → error with upgrade message.
96If older → run migration chain (none yet).
97
98---
99
100## Alternative considered: two-file bundle
101
102Rejected for v1: `.pos` + sidecar `.pos.json` adds friction. Single JSON file keeps save/load atomic.
103
104A future `.poszip` could bundle images for portable templates.
105
106---
107
108## Validation rules
109
110On save:
111
112- `version` must equal supported version
113- `page_width_mm` > 0
114- `body` must be valid UTF-8
115
116On load:
117
118- Parse JSON; validate schema
119- Parse `body` with DSL parser; warnings shown in UI but file still loads
120
121---
122
123## TypeScript / Rust types (reference)
124
125```typescript
126interface PosFile {
127 version: number;
128 metadata: PosMetadata;
129 body: string;
130}
131
132interface PosMetadata {
133 title?: string;
134 page_width_mm: number;
135 preview_mode: "autoscale" | "fixed";
136 chars_per_line?: number;
137 codepage?: string;
138 cut_after_print?: boolean;
139}
140```
141
142Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).