NodetteHQ/PureYAML
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Emitter has no width-based line wrapping or canonical-mode controls #10

New Issue
Closed
opened 2026-07-10 13:56:12 +00:00 by Mihaela · 1 comment
Mihaela commented 2026-07-10 13:56:12 +00:00 (Migrated from codeberg.org)
Copy Link

Status (2026-07-10)

Open. Found by a public-API feature-parity audit against Yams
(NodetteHQ/PureYAMLYamsComparison, Reports/macos-2026-07-10-apisguru-sample-504/FEATURE-PARITY.md),
not by a corpus parse-success run: this is a capability gap in the dump/emit
side, not a correctness bug.

Yams's Emitter.Options exposes: canonical mode, indent width, line width,
allowUnicode, line-break style, explicit document start/end, YAML version,
sortKeys, per-collection style (flow/block), scalar style, and a
redundancy/aliasing strategy.

PureYAML's Emitting.Options (Sources/Emitting/Options.swift) has exactly
two knobs:

  • scalarStyle (.quoted / .plainWhenSafe / .literalBlockWhenMultiline),
    applied uniformly across the whole document.
  • collectionStyle (.block / .flow), also applied uniformly.

Missing entirely: indent width, line width/wrapping, canonical mode,
sortKeys (key order is always insertion-preserving; this is a deliberate
design choice since it also preserves duplicate keys, not itself a bug, but
it means there is no opt-in sorted output either), explicit document
start/end control, and any way to override style on a single node rather
than the whole document.

Impact

Anything that needs specific, tool-facing output formatting (a fixed line
width for readability, deterministic sorted-key output for diffable
generated files, canonical form for a strict-comparison use case) cannot get
it from PureYAML today; the emitted YAML's exact shape is far less
controllable than Yams's.

Work

  • Decide the target knob set: at minimum indent, width, and sortKeys
    look like the highest-value additions based on what Yams exposes and what
    real consumers are likeliest to reach for.
  • Extend Emitting.Options and thread the new settings through
    Emitting.Dumper (Sources/Emitting/Dumper*.swift).
  • Decide whether canonical mode and per-node style overrides are in scope
    here or belong with the Node-equivalent type work (#9), since per-node
    style really only makes sense once there is a node-level type to attach it
    to.
  • Add round-trip and golden-output tests for each new option, matching the
    existing Emitting test conventions.

See NodetteHQ/PureYAMLYamsComparison's FEATURE-PARITY.md for the full
audit.

Part of #8.

## Status (2026-07-10) Open. Found by a public-API feature-parity audit against Yams (NodetteHQ/PureYAMLYamsComparison, `Reports/macos-2026-07-10-apisguru-sample-504/FEATURE-PARITY.md`), not by a corpus parse-success run: this is a capability gap in the dump/emit side, not a correctness bug. Yams's `Emitter.Options` exposes: canonical mode, indent width, line width, `allowUnicode`, line-break style, explicit document start/end, YAML version, `sortKeys`, per-collection style (flow/block), scalar style, and a redundancy/aliasing strategy. PureYAML's `Emitting.Options` (`Sources/Emitting/Options.swift`) has exactly two knobs: - `scalarStyle` (`.quoted` / `.plainWhenSafe` / `.literalBlockWhenMultiline`), applied uniformly across the whole document. - `collectionStyle` (`.block` / `.flow`), also applied uniformly. Missing entirely: indent width, line width/wrapping, canonical mode, `sortKeys` (key order is always insertion-preserving; this is a deliberate design choice since it also preserves duplicate keys, not itself a bug, but it means there is no opt-in sorted output either), explicit document start/end control, and any way to override style on a single node rather than the whole document. ## Impact Anything that needs specific, tool-facing output formatting (a fixed line width for readability, deterministic sorted-key output for diffable generated files, canonical form for a strict-comparison use case) cannot get it from PureYAML today; the emitted YAML's exact shape is far less controllable than Yams's. ## Work - Decide the target knob set: at minimum `indent`, `width`, and `sortKeys` look like the highest-value additions based on what Yams exposes and what real consumers are likeliest to reach for. - Extend `Emitting.Options` and thread the new settings through `Emitting.Dumper` (`Sources/Emitting/Dumper*.swift`). - Decide whether canonical mode and per-node style overrides are in scope here or belong with the Node-equivalent type work (#9), since per-node style really only makes sense once there is a node-level type to attach it to. - Add round-trip and golden-output tests for each new option, matching the existing `Emitting` test conventions. See NodetteHQ/PureYAMLYamsComparison's `FEATURE-PARITY.md` for the full audit. Part of #8.
Mihaela commented 2026-07-10 15:19:01 +00:00 (Migrated from codeberg.org)
Copy Link

indentWidth and sortKeys are done (Emitting.Options, threaded through Dumper.swift/Dumper.Mapping.swift), verified with round-trip tests and no regression against the official yaml-test-suite (still 333/333 parse-level, 208/208 value-level).

sortKeys only sorts a mapping when every key in it is a plain string; a mapping with any complex (mapping/sequence) key stays in insertion order, since there's no well-defined ordering across mixed key kinds to sort by.

Not done, deliberately: width-based line wrapping (real line-folding logic) and canonical mode (needs its own definition of what "canonical" means for this emitter) are each a correctness surface of their own, bigger and riskier than the two mechanical options above, and remain open. Leaving this issue open, narrowed to just those two.

`indentWidth` and `sortKeys` are done (`Emitting.Options`, threaded through `Dumper.swift`/`Dumper.Mapping.swift`), verified with round-trip tests and no regression against the official yaml-test-suite (still 333/333 parse-level, 208/208 value-level). `sortKeys` only sorts a mapping when every key in it is a plain string; a mapping with any complex (`mapping`/`sequence`) key stays in insertion order, since there's no well-defined ordering across mixed key kinds to sort by. Not done, deliberately: `width`-based line wrapping (real line-folding logic) and canonical mode (needs its own definition of what "canonical" means for this emitter) are each a correctness surface of their own, bigger and riskier than the two mechanical options above, and remain open. Leaving this issue open, narrowed to just those two.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
No items
No Label
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: NodetteHQ/PureYAML#10
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?