# `.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 ```json { "version": 1, "metadata": { ... }, "body": "..." } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `version` | `number` | yes | File format version (currently `1`) | | `metadata` | `object` | yes | Document settings | | `body` | `string` | yes | DSL source (UTF-8) | --- ## Metadata schema (version 1) ```json { "title": "Sales Receipt", "page_width_mm": 80, "chars_per_line": 48, "codepage": "CP437" } ``` | Field | Type | Default | Description | |-------|------|---------|-------------| | `title` | `string?` | `null` | Display name in app title | | `page_width_mm` | `number` | `80` | Physical paper width (mm) | | `chars_per_line` | `number?` | derived | Override column count; derived from mm if omitted | | `codepage` | `string?` | `"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_mm` | Default `chars_per_line` | `printable_dots` | |-----------------|--------------------------|------------------| | ≤ 58 | 32 | 384 | | > 58 | 48 | 576 | ### Legacy fields (ignored) Unknown JSON keys are ignored by serde. Notably: | Field | Former meaning | Current behaviour | |-------|----------------|-------------------| | `preview_mode` | autoscale / fixed preview | Ignored; UI uses zoom slider | | `cut_after_print` | auto-cut after job | Ignored; use `@cut` in the template | --- ## Example file **`receipt.pos`:** ```json { "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 | From | To | Migration | |------|-----|-----------| | — | 1 | Initial 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).