BlueGit

timfa posprint

Files

posprint / docs / FILE-FORMAT.md

FILE-FORMAT.md

FILE-FORMAT.md 3.8 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: application/x-posprint (registered via packaging/mime/posprint.xml; claimed by *.pos)

---

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