Reference
Full format reference
Generated 2026-11-04
This page is generated from Pinman's internal file-format test harness. We use the harness to
run Pinman's real readers and writers against representative file shapes, verify that their
observed behavior matches the behavior we claim, and prevent the release and its documentation
from drifting apart. The same live catalogue supplies pinman file list and
pinman file show.
For an overview of when Pinman writes files, preservation guarantees and qualification notes, read the supported file formats guide.
How to read this reference#
A shape is one representative on-disk form of a format: for example, an INI file with repeated keys or a CSV file without a header. Each operation is run against a fresh temporary copy using Pinman's real reader and writer. The harness then verifies that the observed result matches the outcome declared in the catalogue.
The counts in each row are counts of catalogued shapes, not files in the world, and they are not performance measurements. The combined-operation rows exercise several edits in one flush, including edits that conflict.
- ok — The read returned the correct addressable settings, or the write landed and the format's preservation checks passed.
- partial — The read safely returned some settings but could not address every setting in that shape.
- refused — Pinman recognized that it could not safely perform the operation and left the copy untouched.
- unsupported — That operation is not part of the format's contract, such as adding a positional field to ScreenRes.
- n/a — The shape provided nothing meaningful to try for that operation.
Use pinman file check <path> to run the real writer against a temporary copy of a particular
file. The supplied file is never changed.
Standard formats#
INI#
Read and write · 52 representative shapes catalogued.
| Operation | Catalogued outcomes |
|---|---|
| Read a setting | 45 ok, 2 refused, 5 partial |
| Rewrite unchanged | 43 ok, 4 n/a, 5 refused |
| Change a setting | 41 ok, 4 n/a, 7 refused |
| Add a setting | 50 ok, 2 n/a |
| Remove a setting | 43 ok, 4 n/a, 5 refused |
| Several changes at once | 43 ok, 9 n/a |
| Conflicting changes at once | 43 ok, 9 n/a |
n/a: the shape gave that operation nothing to attempt — nothing readable, no values, or too few verbs to combine.
Where it does not apply#
- Read a setting: Refused: the file is not valid UTF-8. Re-save it as UTF-8. (1 shape)
- Change a setting: Refused: Pinman writes a setting as one line, so it cannot change a value that is spread over several. (2 shapes)
- Read a setting: Refused: the file's section structure cannot be read. (1 shape)
- Read a setting: Pinman shows the last of the repeated settings and cannot address the earlier ones, which stay in the file unchanged. (5 shapes)
- Rewrite unchanged: Refused: writing the setting back unchanged still has to name one of the two. (5 shapes)
- Change a setting: Refused: Pinman cannot tell which of the two the application uses. (5 shapes)
- Remove a setting: Refused for the same reason — removing the wrong one is unrecoverable. (5 shapes)
XML#
Read and write · 40 representative shapes catalogued.
| Operation | Catalogued outcomes |
|---|---|
| Read a setting | 33 ok, 2 refused, 5 partial |
| Rewrite unchanged | 33 ok, 3 refused, 4 n/a |
| Change a setting | 32 ok, 4 refused, 4 n/a |
| Add a setting | 35 ok, 3 refused, 2 n/a |
| Remove a setting | 33 ok, 3 refused, 4 n/a |
| Several changes at once | 33 ok, 7 n/a |
| Conflicting changes at once | 33 ok, 7 n/a |
n/a: the shape gave that operation nothing to attempt — nothing readable, no values, or too few verbs to combine.
Where it does not apply#
- Rewrite unchanged: Refused: Pinman writes UTF-8, and rewriting this file would not match the encoding its own declaration names. (1 shape)
- Change a setting: Refused for the same reason. (2 shapes)
- Add a setting: Refused for the same reason. (2 shapes)
- Remove a setting: Refused for the same reason. (2 shapes)
- Rewrite unchanged: Refused: the file is not valid UTF-8, which is what Pinman writes. (1 shape)
- Read a setting: Refused: an XML file needs one root element. (1 shape)
- Read a setting: Refused: the file holds no XML. (1 shape)
- Read a setting: The value beside the attributes is listed as not addressable. (2 shapes)
- Change a setting: Refused: a carriage return written into an XML file reads back as a line feed, so Pinman will not store a value holding one. (1 shape)
- Read a setting: The repeated elements are listed as not individually addressable. (1 shape)
- Read a setting: The repeated parents are listed as not individually addressable. (1 shape)
- Read a setting: The text around the child element is listed as not addressable. (1 shape)
- Rewrite unchanged: Refused: Pinman cannot show the loose text beside the child elements, so it will not rewrite the element holding it. (1 shape)
- Change a setting: Refused: Pinman cannot show the loose text beside the child elements, so it will not rewrite the element holding it. (1 shape)
- Add a setting: Refused: Pinman cannot show the loose text beside the child elements, so it will not rewrite the element holding it. (1 shape)
- Remove a setting: Refused: Pinman cannot show the loose text beside the child elements, so it will not rewrite the element holding it. (1 shape)
JSON#
Read and write · 34 representative shapes catalogued.
| Operation | Catalogued outcomes |
|---|---|
| Read a setting | 28 ok, 3 refused, 3 partial |
| Rewrite unchanged | 28 ok, 5 n/a, 1 refused |
| Change a setting | 27 ok, 5 n/a, 2 refused |
| Add a setting | 29 ok, 3 n/a, 2 refused |
| Remove a setting | 28 ok, 5 n/a, 1 refused |
| Several changes at once | 28 ok, 6 n/a |
| Conflicting changes at once | 28 ok, 6 n/a |
n/a: the shape gave that operation nothing to attempt — nothing readable, no values, or too few verbs to combine.
Where it does not apply#
- Read a setting: Refused: this file is not UTF-8 text, so Pinman will not guess at it. (1 shape)
- Change a setting: Refused: this name holds a list, and Pinman does not edit one in place. (1 shape)
- Read a setting: The file's outermost value is a list, so there are no names to show. (1 shape)
- Add a setting: Refused: this document holds a list, so there is no name to add one to. (1 shape)
- Read a setting: The file's outermost value is a single value, so there are no names to show. (1 shape)
- Add a setting: Refused: this document holds one bare value, not a set of names. (1 shape)
- Read a setting: Refused: the file is empty, which is not a JSON document. (1 shape)
- Read a setting: Refused: this file is not valid JSON, so Pinman will not guess at it. (1 shape)
- Read a setting: The name is in the document twice; only one of them is shown. (1 shape)
- Rewrite unchanged: Refused: the name is in the document twice, so Pinman cannot tell which one is used. (1 shape)
- Change a setting: Refused: the name is in the document twice, so Pinman cannot tell which one is used. (1 shape)
- Remove a setting: Refused: the name is in the document twice, so Pinman cannot tell which one is used. (1 shape)
YAML#
Read and write · 35 representative shapes catalogued.
| Operation | Catalogued outcomes |
|---|---|
| Read a setting | 32 ok, 1 refused, 2 partial |
| Rewrite unchanged | 30 ok, 4 n/a, 1 refused |
| Change a setting | 29 ok, 4 n/a, 2 refused |
| Add a setting | 33 ok, 1 n/a, 1 refused |
| Remove a setting | 30 ok, 4 n/a, 1 refused |
| Several changes at once | 30 ok, 5 n/a |
| Conflicting changes at once | 30 ok, 5 n/a |
n/a: the shape gave that operation nothing to attempt — nothing readable, no values, or too few verbs to combine.
Where it does not apply#
- Read a setting: Refused: this file is not UTF-8 text, so Pinman will not guess at it. (1 shape)
- Change a setting: Refused: this name holds a list, and Pinman does not edit one in place. (1 shape)
- Read a setting: The file's outermost value is a list, so there are no names to show. (1 shape)
- Add a setting: Refused: this document holds a list, so there is no name to add one to. (1 shape)
- Read a setting: The name is in the document twice; only one of them is shown. (1 shape)
- Rewrite unchanged: Refused: the name is in the document twice, so Pinman cannot tell which one is used. (1 shape)
- Change a setting: Refused: the name is in the document twice, so Pinman cannot tell which one is used. (1 shape)
- Remove a setting: Refused: the name is in the document twice, so Pinman cannot tell which one is used. (1 shape)
CSV#
Read and write · 49 representative shapes catalogued.
| Operation | Catalogued outcomes |
|---|---|
| Read a setting | 43 ok, 1 refused, 5 partial |
| Rewrite unchanged | 44 ok, 2 n/a, 3 refused |
| Change a setting | 44 ok, 2 n/a, 3 refused |
| Add a setting | 45 ok, 3 refused, 1 n/a |
| Remove a setting | 42 ok, 5 refused, 2 n/a |
| Several changes at once | 44 ok, 5 n/a |
| Conflicting changes at once | 46 ok, 3 n/a |
n/a: the shape gave that operation nothing to attempt — nothing readable, no values, or too few verbs to combine.
Where it does not apply#
- Add a setting: Refused: keyless rows are update-only. (2 shapes)
- Remove a setting: Refused: removing a keyless row would shift later ordinals. (2 shapes)
- Read a setting: Refused: the bytes are not UTF-8, so Pinman will not guess an encoding. (1 shape)
- Rewrite unchanged: Refused: a value carrying a line break spreads its row over several lines, and Pinman cannot tell which of them to change. (2 shapes)
- Change a setting: Refused: a value carrying a line break spreads its row over several lines, and Pinman cannot tell which of them to change. (2 shapes)
- Read a setting: The default read projects the last occurrence; ambiguous updates require a first or last declaration. (1 shape)
- Rewrite unchanged: Refused: a duplicate row requires a first or last declaration. (1 shape)
- Change a setting: Refused: a duplicate row requires a first or last declaration. (1 shape)
- Remove a setting: Refused: another occurrence would survive and ordinary undo cannot restore the deleted row. (3 shapes)
- Read a setting: Only the declared occurrence is surfaced; the other occurrence is preserved. (2 shapes)
- Read a setting: A row with no name in its key cell cannot be addressed, so its values are not shown. (1 shape)
- Read a setting: The last column of a repeated name is the one Pinman reads and writes; earlier ones cannot be addressed. (1 shape)
- Add a setting: Refused: with no header there are no columns for a new row to fill. (1 shape)
SQLite#
Read and write · 31 representative shapes catalogued.
| Operation | Catalogued outcomes |
|---|---|
| Read a setting | 28 ok, 3 refused |
| Rewrite unchanged | 27 ok, 4 n/a |
| Change a setting | 26 ok, 1 refused, 4 n/a |
| Add a setting | 28 ok, 3 n/a |
| Remove a setting | 27 ok, 4 n/a |
| Several changes at once | 27 ok, 4 n/a |
| Conflicting changes at once | 27 ok, 4 n/a |
n/a: the shape gave that operation nothing to attempt — nothing readable, no values, or too few verbs to combine.
Where it does not apply#
- Change a setting: Refused: this column holds raw bytes, which Pinman does not edit. (1 shape)
- Read a setting: Refused: the table has no primary key, so Pinman cannot tell one row from another. (1 shape)
- Read a setting: Refused: this file is not a SQLite database. (1 shape)
- Read a setting: Refused: the file holds no table to read. (1 shape)
Pinball formats#
PinMAME options#
Read and write · 27 representative shapes catalogued.
| Operation | Catalogued outcomes |
|---|---|
| Read a setting | 25 ok, 1 refused, 1 partial |
| Rewrite unchanged | 23 ok, 3 n/a, 1 refused |
| Change a setting | 23 ok, 3 n/a, 1 refused |
| Add a setting | 26 ok, 1 n/a |
| Remove a setting | 23 ok, 3 n/a, 1 refused |
| Several changes at once | 23 ok, 4 n/a |
| Conflicting changes at once | 23 ok, 4 n/a |
n/a: the shape gave that operation nothing to attempt — nothing readable, no values, or too few verbs to combine.
Where it does not apply#
- Read a setting: Refused: Pinman cannot tell what encoding this file uses. (1 shape)
- Read a setting: Pinman shows the last of the repeated settings and cannot address the earlier ones, which stay in the file unchanged. (1 shape)
- Rewrite unchanged: Refused: writing the setting back unchanged still has to name one of the two. (1 shape)
- Change a setting: Refused: Pinman cannot tell which of the two lines PinMAME uses. (1 shape)
- Remove a setting: Refused for the same reason — removing the wrong one is unrecoverable. (1 shape)
PinVol settings#
Read and write · 28 representative shapes catalogued.
| Operation | Catalogued outcomes |
|---|---|
| Read a setting | 25 ok, 1 refused, 2 partial |
| Rewrite unchanged | 22 ok, 3 n/a, 3 refused |
| Change a setting | 22 ok, 3 n/a, 3 refused |
| Add a setting | 27 ok, 1 n/a |
| Remove a setting | 22 ok, 3 n/a, 3 refused |
| Several changes at once | 22 ok, 6 n/a |
| Conflicting changes at once | 22 ok, 6 n/a |
n/a: the shape gave that operation nothing to attempt — nothing readable, no values, or too few verbs to combine.
Where it does not apply#
- Read a setting: Refused: this file is not UTF-8 text, so Pinman will not guess at it. (1 shape)
- Rewrite unchanged: Refused: the name is in the file twice, so Pinman cannot tell which line is in use. (2 shapes)
- Change a setting: Refused: the name is in the file twice, so Pinman cannot tell which line is in use. (2 shapes)
- Remove a setting: Refused: the name is in the file twice, so Pinman cannot tell which line is in use. (2 shapes)
- Rewrite unchanged: Refused: writing the setting back unchanged still has to pick one of the entries. (1 shape)
- Change a setting: Refused: PinVol reads this name as a list, and Pinman cannot tell which entry is which. (1 shape)
- Remove a setting: Refused for the same reason — dropping the wrong entry is unrecoverable. (1 shape)
- Read a setting: The line names no setting, so Pinman shows nothing for it. (1 shape)
- Read a setting: There is no name to show this value under. (1 shape)
PinVol tables#
Read and write · 28 representative shapes catalogued.
| Operation | Catalogued outcomes |
|---|---|
| Read a setting | 23 ok, 1 refused, 4 partial |
| Rewrite unchanged | 24 ok, 3 n/a, 1 refused |
| Change a setting | 24 ok, 3 n/a, 1 refused |
| Add a setting | 27 ok, 1 n/a |
| Remove a setting | 22 ok, 3 n/a, 3 refused |
| Several changes at once | 24 ok, 4 n/a |
| Conflicting changes at once | 24 ok, 4 n/a |
n/a: the shape gave that operation nothing to attempt — nothing readable, no values, or too few verbs to combine.
Where it does not apply#
- Read a setting: Refused: this file is not UTF-8 text, so Pinman will not guess at it. (1 shape)
- Read a setting: The values past the last column are not shown. (1 shape)
- Read a setting: The row is in the file twice; only one of them is shown. (1 shape)
- Rewrite unchanged: Refused: the row is in the file twice, so Pinman cannot tell which one is in use. (1 shape)
- Change a setting: Refused: the row is in the file twice, so Pinman cannot tell which one is in use. (1 shape)
- Remove a setting: Refused: the row is in the file twice, so Pinman cannot tell which one is in use. (1 shape)
- Read a setting: Only the declared occurrence is surfaced; the other occurrence is preserved. (2 shapes)
- Remove a setting: Refused: another occurrence would survive and ordinary undo cannot restore the deleted row. (2 shapes)
ScreenRes#
Read and write · 27 representative shapes catalogued.
| Operation | Catalogued outcomes |
|---|---|
| Read a setting | 22 ok, 4 partial, 1 refused |
| Rewrite unchanged | 24 ok, 3 n/a |
| Change a setting | 24 ok, 3 n/a |
| Add a setting | 26 unsupported, 1 n/a |
| Remove a setting | 24 unsupported, 3 n/a |
| Several changes at once | 27 n/a |
| Conflicting changes at once | 24 ok, 3 n/a |
n/a: the shape gave that operation nothing to attempt — nothing readable, no values, or too few verbs to combine.
Where it does not apply#
- Add a setting: The file identifies its settings by position, so Pinman never adds or removes one. (26 shapes)
- Remove a setting: The file identifies its settings by position, so Pinman never adds or removes one. (24 shapes)
- Read a setting: The file stops early, so the later settings are not shown. (1 shape)
- Read a setting: The values past the last known field are not shown. (1 shape)
- Read a setting: Refused: this file is not UTF-8 text, so Pinman will not guess at it. (1 shape)
- Read a setting: The file holds no values, so there is nothing to show. (2 shapes)