Skip to content

Commit daeb317

Browse files
ctruedenclaude
andcommitted
docs: use TOML rather than YAML for the settings store
TOML reads like the INI files people already understand, supports comments, and -- unlike YAML -- is neither whitespace-fragile nor implicitly typed, so `no` stays the string `no` and `1.10` stays `1.10`. Those traps bite exactly the values a config file holds. Jaunch already uses TOML, so the format is familiar across the stack. The cost is a dependency, since the JDK has no TOML parser where snakeyaml was already present; the library is worth choosing when this is actually built. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent a6e9e32 commit daeb317

2 files changed

Lines changed: 9 additions & 6 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -734,11 +734,14 @@ design settled now, so that Phase 4 inherits decisions rather than a debate:
734734
- **Not `java.util.prefs`.** Its opacity is the actual complaint: the registry
735735
on Windows, plists on macOS, `~/.java/.userPrefs` on Linux; values over 8KB
736736
silently truncated; nothing a user can inspect or diff.
737-
- **YAML.** `snakeyaml` is already in this stack for op declarations, so it is
738-
no new dependency, and unlike JSON it supports **comments**, which a
739-
hand-editable file wants. Load with the safe constructor and quote scalars
740-
on write, to avoid implicit typing turning `no` into `false` and version
741-
strings into numbers.
737+
- **TOML.** It reads like the INI files everyone already understands
738+
(`key = value`), supports comments, and — unlike YAML — is not
739+
whitespace-fragile and has no implicit typing, so `no` stays the string
740+
`no` and `1.10` stays `1.10`. Those YAML traps bite exactly the values a
741+
config file holds. Jaunch already uses TOML, so the format is familiar
742+
across the stack. The cost is a dependency: the JDK has no TOML parser,
743+
where `snakeyaml` was already present — worth choosing the library when
744+
this is built.
742745
- **`$XDG_CONFIG_HOME/fiji`, else `~/.config/fiji`** — what users asked for —
743746
on every platform rather than `%APPDATA%` and `~/Library`. The complaint was
744747
opacity, and a path users can find, back up and quote in a bug report beats

‎docs/migration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ A **dropped** row is a successful outcome, not a gap.
117117
| `plugin` (the `HandlerPlugin`/`WrapperPlugin`/`TypedPlugin`/`SingletonPlugin` hierarchy and their services) | not ported — each user of these inlines the small contract it needs, as `DataHandle` did | dropped |
118118
| `service` | `org.scijava.context`: `Service` (no longer a plugin, and discovered via `ServiceLoader`), with `Context` holding them. `SciJavaService` has no equivalent — a marker is not needed. `ServiceHelper` and `ServiceIndex` are internal to `Context` | ported |
119119
| `object` | with the widgets and conversion layer that use it (Phase 3/4), so a consumer shapes it | planned |
120-
| `prefs` | split: a YAML settings store under `~/.config/fiji` (design settled in [migration-plan.md](migration-plan.md)), and widget value persistence, which belongs with the input harvester (Phase 4). Explicitly **not** `java.util.prefs` | planned |
120+
| `prefs` | split: a TOML settings store under `~/.config/fiji` (design settled in [migration-plan.md](migration-plan.md)), and widget value persistence, which belongs with the input harvester (Phase 4). Explicitly **not** `java.util.prefs` | planned |
121121
| `app` | mostly `org.scijava.meta` for version and title metadata; the rest is app-shell material, dropped | planned |
122122
| `thread` | EDT dispatch belongs with the UI layer (Phase 4); parallelism is `org.scijava.concurrent` | planned |
123123
| `convert` | `scijava-convert3` (Phase 2) | planned |

0 commit comments

Comments
 (0)