🚀 [Minor]: Format-Toml normalizes TOML to canonical form

[Marius Storhaug (MariusStorhaug)]

Format-Toml normalizes TOML text into a canonical form — consistent key quoting, canonical scalar formatting, and stable table ordering — without changing its meaning. It is the single-call equivalent of ConvertFrom-Toml | ConvertTo-Toml, matching the pattern already established by sister modules Format-Json and Format-Hashtable.

New: Format-Toml normalizes TOML text

Get-Content 'Cargo.toml' -Raw | Format-Toml
Format-Toml -Path 'Cargo.toml' -Indent 4
Format-Toml -LiteralPath 'C:\configs\[env].toml'

Format-Toml accepts a TOML string via pipeline (-InputObject), or reads a file via -Path (wildcard-aware) or -LiteralPath. It never writes back to the source file — output is always returned as a [string]. Formatting is idempotent: running it twice produces the same result as running it once, and the output always remains parseable by ConvertFrom-Toml.

TOML has no indentation semantics — nested tables are flat [a.b] headers, not indented blocks. The -Indent parameter (default 2) is a display convention: it prefixes nested table headers and their keys with spaces proportional to nesting depth, similar to how the Taplo formatter presents nested tables. Set -Indent 0 to keep the flat, unindented form.

---

Technical details

• New public function src/functions/public/Format-Toml.ps1, three parameter sets (InputObject default/pipeline, Path, LiteralPath), reuses ConvertFrom-Toml + ConvertTo-Toml — no new parser or emitter.
• New private helper src/functions/private/Add-TomlIndentation.ps1 post-processes the canonical (flat) ConvertTo-Toml output to add depth-based indentation without touching the existing serializer, so ConvertTo-Toml's own output and tests are unaffected.
• Added a Describe 'Format-Toml' block to tests/Toml.Tests.ps1 covering: normalization, semantic equivalence to ConvertFrom-Toml | ConvertTo-Toml, indentation at depth, -Indent 0 flat output, idempotency, round-trip validity, pipeline input, -Path, -LiteralPath, and error handling for invalid TOML / missing files.
• README and examples/General.ps1 updated with a Format-Toml usage section.
• Deferred the Format-Tml alias mentioned in Add Format-Toml function for normalization #3 — the module has no established alias-export mechanism yet (build.ps1 only exports functions), so adding one alias in isolation would be inconsistent with the rest of the public surface. Can be revisited once alias support lands.
• Implementation plan progress (from Add Format-Toml function for normalization #3): Format-Toml added with tests, README/examples updated. Alias task intentionally deferred (see above).
• Verified: pwsh -File .\build.ps1 then Invoke-Pester -Path .\tests\Toml.Tests.ps1 -CI → 132/132 passing. PSScriptAnalyzer clean on new files (aside from a pre-existing, module-wide PSUseBOMForUnicodeEncodedFile inconsistency already present on most files).

Relevant issues (or links)

• Closes Add Format-Toml function for normalization #3