BlueGit

timfa posprint

Files

posprint / docs / FILE-FORMAT.md

FILE-FORMAT.md

FILE-FORMAT.md 4.0 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,
  "default_feed_before_cut": 4
}
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
default_feed_before_cutnumber4Feed lines before auto-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;
  default_feed_before_cut?: number;
}

Rust mirrors these with serde derive for 1:1 IPC across Tauri.

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 "default_feed_before_cut": 4
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| `default_feed_before_cut` | `number` | `4` | Feed lines before auto-cut |
51
52### Page width derivation
53
54| `page_width_mm` | Typical dots (203 DPI) | Default `chars_per_line` (Font A) |
55|-----------------|------------------------|-----------------------------------|
56| 58 | 384 | 32 |
57| 80 | 576 | 48 |
58
59---
60
61## Example file
62
63**`receipt.pos`:**
64
65```json
66{
67 "version": 1,
68 "metadata": {
69 "title": "Standard Receipt",
70 "page_width_mm": 80,
71 "preview_mode": "autoscale",
72 "codepage": "CP437",
73 "cut_after_print": true
74 },
75 "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"
76}
77```
78
79For 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.
80
81---
82
83## Asset resolution
84
85- Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute.
86- Bundled assets: optional `assets/` subfolder next to the template.
87- Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory.
88
89---
90
91## Version migration
92
93| From | To | Migration |
94|------|-----|-----------|
95| — | 1 | Initial release |
96
97On load, if `version` is newer than app supports → error with upgrade message.
98If older → run migration chain (none yet).
99
100---
101
102## Alternative considered: two-file bundle
103
104Rejected for v1: `.pos` + sidecar `.pos.json` adds friction. Single JSON file keeps save/load atomic.
105
106A future `.poszip` could bundle images for portable templates.
107
108---
109
110## Validation rules
111
112On save:
113
114- `version` must equal supported version
115- `page_width_mm` > 0
116- `body` must be valid UTF-8
117
118On load:
119
120- Parse JSON; validate schema
121- Parse `body` with DSL parser; warnings shown in UI but file still loads
122
123---
124
125## TypeScript / Rust types (reference)
126
127```typescript
128interface PosFile {
129 version: number;
130 metadata: PosMetadata;
131 body: string;
132}
133
134interface PosMetadata {
135 title?: string;
136 page_width_mm: number;
137 preview_mode: "autoscale" | "fixed";
138 chars_per_line?: number;
139 codepage?: string;
140 cut_after_print?: boolean;
141 default_feed_before_cut?: number;
142}
143```
144
145Rust mirrors these with `serde` derive for 1:1 IPC across Tauri.