Supported file formats

Pinman reads and writes configuration files that belong to other programs. This page says which formats it handles, and what it changes when it writes one.

What Pinman guarantees#

Pinman edits a program's own settings file, in place, while that program goes on using it. So the promise it has to keep is simple:

Every value you could read before Pinman writes, you can read after — unchanged. It changes the one setting you asked it to change, and nothing else.

Around that setting, the things that make the file yours stay put:

• Your comments stay. Notes you left yourself in a config file survive an edit. The exception is a comment sitting on the same line as a setting Pinman writes: in an INI file everything after the = counts as the value, so that comment is replaced along with it. Comments on their own line are never touched.
• Your ordering stays. Sections, keys and rows stay where you put them, so the file still reads the way you wrote it.
• Your spelling stays. A key written FullScreen does not come back fullscreen.
• Everything Pinman doesn't know about stays. Settings outside the schema are carried through untouched rather than dropped or rewritten.

What can change is formatting the program's own parser ignores — indentation, column alignment, quoting style, line endings. That is worth knowing for one practical reason: a file can show up as heavily changed in a diff, or as a new version in a backup tool, even though a single value actually differs.

When Pinman refuses#

Pinman inspects an INI or XML file before touching it and refuses the specific settings it cannot safely change — a setting written on two lines, an element name that appears in more than one place, a commented-out copy the text-based writer can't tell from the real thing, text mixed in with child elements. Profile apply and preview both run this check up front, so a refusal is reported before any file is modified.

The check runs across every setting a change touches before the first byte is written, so an apply either goes through in full or stops up front and names the setting it could not handle safely. Nothing is half-applied and no file is left part-written.

Which formats#

Standard formats, used by all sorts of programs — nothing here is specific to any one kind of software:

• INI — the classic [section] / key=value settings file.
• XML — element and attribute values in .xml files.
• JSON — .json documents, addressed by key path.
• YAML — .yaml and .yml documents.
• CSV — .csv tables, with rows addressed by a key column.
• SQLite — .db database files: tables, rows and columns, rather than text.

Kits can add formats belonging to specific software on top of these. And if the program you care about stores its settings in a format that isn't listed here, a custom file adapter can usually be added — contact technical support and describe the file.

Related#

• Windows Registry — soon
• Windows Runtime — soon
• Schema format — soon