BlueGit

timfa posprint

Files

posprint / docs / FILE-FORMAT.md

FILE-FORMAT.md

FILE-FORMAT.md 3.4 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,
  "chars_per_line": 48,
  "codepage": "CP437"
}
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

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,
    "codepage": "CP437"
  },
  "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).

---

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;
}

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 "chars_per_line": 48,
35 "codepage": "CP437"
36}
37```
38
39| Field | Type | Default | Description |
40|-------|------|---------|-------------|
41| `title` | `string?` | `null` | Display name in app title / recent files |
42| `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |
43| `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |
44| `chars_per_line` | `number?` | derived | Override character width for preview; derived from mm if omitted |
45| `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |
46
47### Page width derivation
48
49| `page_width_mm` | Typical dots (203 DPI) | Default `chars_per_line` (Font A) |
50|-----------------|------------------------|-----------------------------------|
51| 58 | 384 | 32 |
52| 80 | 576 | 48 |
53
54---
55
56## Example file
57
58**`receipt.pos`:**
59
60```json
61{
62 "version": 1,
63 "metadata": {
64 "title": "Standard Receipt",
65 "page_width_mm": 80,
66 "codepage": "CP437"
67 },
68 "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"
69}
70```
71
72For 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.
73
74---
75
76## Asset resolution
77
78- Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute.
79- Bundled assets: optional `assets/` subfolder next to the template.
80- Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory.
81
82---
83
84## Version migration
85
86| From | To | Migration |
87|------|-----|-----------|
88| — | 1 | Initial release |
89
90On load, if `version` is newer than app supports → error with upgrade message.
91If older → run migration chain (none yet).
92
93---
94
95## Validation rules
96
97On save:
98
99- `version` must equal supported version
100- `page_width_mm` > 0
101- `body` must be valid UTF-8
102
103On load:
104
105- Parse JSON; validate schema
106- Parse `body` with DSL parser; warnings shown in UI but file still loads
107
108---
109
110## TypeScript / Rust types (reference)
111
112```typescript
113interface PosFile {
114 version: number;
115 metadata: PosMetadata;
116 body: string;
117}
118
119interface PosMetadata {
120 title?: string;
121 page_width_mm: number;
122 preview_mode: "autoscale" | "fixed";
123 chars_per_line?: number;
124 codepage?: string;
125}
126```
127
128Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).