BlueGit

timfa posprint

Files

posprint / docs / FILE-FORMAT.md

FILE-FORMAT.md

FILE-FORMAT.md 2.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). Installed MIME type: application/x-posprint (see packaging MIME XML).

---

Top-level schema

{
  "version": 1,
  "metadata": { ... },
  "body": "..."
}
FieldTypeRequiredDescription
versionnumberyesFile format version (currently 1)
metadataobjectyesDocument settings
bodystringyesDSL source (UTF-8)

---

Metadata schema (version 1)

{
  "title": "Sales Receipt",
  "page_width_mm": 80,
  "chars_per_line": 48,
  "codepage": "CP437"
}
FieldTypeDefaultDescription
titlestring?nullDisplay name in app title
page_width_mmnumber80Physical paper width (mm)
chars_per_linenumber?derivedOverride column count; derived from mm if omitted
codepagestring?"CP437"Reserved; encoder uses CP437 today

Printable width model

Effective print/preview width uses Font A columns:

printable_dots = chars_per_line() × 12

page_width_mmDefault chars_per_lineprintable_dots
≤ 5832384
> 5848576

Legacy fields (ignored)

Unknown JSON keys are ignored by serde. Notably:

FieldFormer meaningCurrent behaviour
preview_modeautoscale / fixed previewIgnored; UI uses zoom slider
cut_after_printauto-cut after jobIgnored; use @cut in the template

---

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:\nTOTAL: ${GrandTotal}\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
}

---

Asset resolution

  • Paths in @image resolve relative to the directory containing the .pos file unless absolute.
  • Parameterized paths (${LogoPath}) resolve after substitution; relative paths still anchor to the .pos directory.

---

Version migration

FromToMigration
—1Initial release

On load, if version is newer than the app supports → error. Older versions would migrate (none yet).

---

Validation

On save / load: JSON parse, version == 1, page_width_mm > 0, UTF-8 body. DSL parse errors show in the UI; the file can still load.

---

Rust types

Defined in src/io/mod.rs (PosFile, PosMetadata) with serde derive. Used directly by the egui app (no IPC).

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**Installed MIME type:** `application/x-posprint` (see packaging MIME XML).
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) |
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 |
42| `page_width_mm` | `number` | `80` | Physical paper width (mm) |
43| `chars_per_line` | `number?` | derived | Override column count; derived from mm if omitted |
44| `codepage` | `string?` | `"CP437"` | Reserved; encoder uses CP437 today |
45
46### Printable width model
47
48Effective print/preview width uses Font A columns:
49
50`printable_dots = chars_per_line() × 12`
51
52| `page_width_mm` | Default `chars_per_line` | `printable_dots` |
53|-----------------|--------------------------|------------------|
54| ≤ 58 | 32 | 384 |
55| > 58 | 48 | 576 |
56
57### Legacy fields (ignored)
58
59Unknown JSON keys are ignored by serde. Notably:
60
61| Field | Former meaning | Current behaviour |
62|-------|----------------|-------------------|
63| `preview_mode` | autoscale / fixed preview | Ignored; UI uses zoom slider |
64| `cut_after_print` | auto-cut after job | Ignored; use `@cut` in the template |
65
66---
67
68## Example file
69
70**`receipt.pos`:**
71
72```json
73{
74 "version": 1,
75 "metadata": {
76 "title": "Standard Receipt",
77 "page_width_mm": 80,
78 "codepage": "CP437"
79 },
80 "body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\nTOTAL: ${GrandTotal}\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
81}
82```
83
84---
85
86## Asset resolution
87
88- Paths in `@image` resolve relative to the **directory containing the `.pos` file** unless absolute.
89- Parameterized paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` directory.
90
91---
92
93## Version migration
94
95| From | To | Migration |
96|------|-----|-----------|
97| — | 1 | Initial release |
98
99On load, if `version` is newer than the app supports → error. Older versions would migrate (none yet).
100
101---
102
103## Validation
104
105On save / load: JSON parse, `version == 1`, `page_width_mm > 0`, UTF-8 body. DSL parse errors show in the UI; the file can still load.
106
107---
108
109## Rust types
110
111Defined in `src/io/mod.rs` (`PosFile`, `PosMetadata`) with `serde` derive. Used directly by the egui app (no IPC).