🌟 [Major]: TOML 1.0.0 reading and writing now available in PowerShell

.github/PSModule.yml

@@ -29,4 +29,5 @@ Linter:
     VALIDATE_JSCPD: false
     VALIDATE_JSON_PRETTIER: false
     VALIDATE_MARKDOWN_PRETTIER: false
+    VALIDATE_YAML: false
     VALIDATE_YAML_PRETTIER: false

.github/workflows/Process-PSModule.yml

@@ -27,6 +27,6 @@ permissions:
 
 jobs:
   Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@fb1bdb8fefd243292f779d2a856a38db6fe6daf4 # v6.1.13
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@b11b310e461f08ee99055b0827ef7909dea7110a # v6.1.14
     secrets:
-      APIKEY: ${{ secrets.APIKEY }}
+      APIKey: ${{ secrets.APIKey || secrets.APIKEY }}

.gitignore

@@ -11,8 +11,12 @@
 
 # PSModule framework outputs folder
 outputs/*
+output/
 
 # .Net build output
 bin/
 obj/
 libs/
+
+# Pester test output
+testResults.xml

README.md

@@ -1,31 +1,174 @@
 # Toml
 
-Toml is a PowerShell module for reading TOML file content from disk so scripts can load and process configuration text.
+PowerShell module for reading and writing [TOML](https://toml.io) data, with full TOML 1.0.0 specification support.
+
+## Prerequisites
+
+- PowerShell 7.6 LTS
+- The [PSModule framework](https://github.com/PSModule/Process-PSModule) for building, testing and publishing the module.
 
 ## Installation
 
-Install the module from the PowerShell Gallery:
+To install the module from the PowerShell Gallery, you can use the following command:
 
 ```powershell
 Install-PSResource -Name Toml
 Import-Module -Name Toml
 ```
 
-## Capabilities
+## Usage
 
-Use this command to read TOML content from a file path:
+### Parse a TOML string
 
 ```powershell
-Get-Toml -Path '.\settings.toml'
+$doc = ConvertFrom-Toml -InputObject @'
+[database]
+host = "localhost"
+port = 5432
+enabled = true
+'@
+
+$doc.Data.database.host     # "localhost"
+$doc.Data.database.port     # 5432 [long]
+$doc.Data.database.enabled  # $true
 ```
 
-## Documentation
+### Import from a TOML file
+
+```powershell
+$doc = Import-Toml -Path './config.toml'
+$doc.FilePath   # absolute path to the file
+$doc.Data       # OrderedDictionary of all top-level keys
+```
+
+### Serialize an object to TOML
+
+```powershell
+$toml = ConvertTo-Toml -InputObject ([ordered]@{
+    title   = 'My App'
+    version = 1
+    server  = [ordered]@{
+        host = 'localhost'
+        port = 8080
+    }
+})
+# title = "My App"
+# version = 1
+#
+# [server]
+# host = "localhost"
+# port = 8080
+```
+
+### Export to a TOML file
+
+```powershell
+$config = [ordered]@{
+    name    = 'example'
+    enabled = $true
+}
+Export-Toml -InputObject $config -Path './output.toml'
+```
+
+### Round-trip: file → modify → file
+
+```powershell
+$doc = Import-Toml -Path './config.toml'
+$doc.Data['version'] = 2
+Export-Toml -InputObject $doc -Path './config.toml'
+```
+
+### Normalize TOML text
+
+```powershell
+Get-Content 'Cargo.toml' -Raw | Format-Toml
+Format-Toml -Path 'Cargo.toml' -Indent 4
+```
 
-Documentation is published at [psmodule.io/Toml](https://psmodule.io/Toml/).
+`Format-Toml` parses then re-serializes TOML text, producing consistent key
+quoting and canonical scalar forms — equivalent to
+`ConvertFrom-Toml | ConvertTo-Toml` as a single call. TOML itself has no
+indentation semantics; `-Indent` (default `2`) only controls how many spaces
+are used to visually nest table headers and their keys by depth. Set
+`-Indent 0` for the flat, unindented form.
 
-Use PowerShell help and command discovery for details:
+### Merge two TOML documents
 
 ```powershell
-Get-Command -Module Toml
-Get-Help -Name Get-Toml -Examples
+$defaults = @'
+[server]
+host = "localhost"
+port = 8080
+'@
+
+$overrides = @'
+[server]
+port = 9090
+'@
+
+Merge-Toml -BaseObject $defaults -OverrideObject $overrides
+# [server]
+# host = "localhost"
+# port = 9090
 ```
+
+`Merge-Toml` also accepts `-Path`/`-LiteralPath` for merging files, and a `-Strategy` of `LastWins` (default), `FirstWins`, or `ErrorOnConflict` for resolving scalar key conflicts. Nested tables are always deep-merged and arrays of tables are always concatenated.
+
+## TOML type mapping
+
+| TOML type            | PowerShell type            |
+|----------------------|----------------------------|
+| String               | `[string]`                 |
+| Integer              | `[long]`                   |
+| Float                | `[double]`                 |
+| Boolean              | `[bool]`                   |
+| Offset date-time     | `[System.DateTimeOffset]`  |
+| Local date-time      | `[System.DateTime]`        |
+| Local date           | `[System.DateTime]`        |
+| Local time           | `[System.TimeSpan]`        |
+| Array                | `[object[]]`               |
+| Table / Inline table | `[ordered]` hashtable      |
+| Array of tables      | `[object[]]` of hashtables |
+
+## Commands
+
+| Command             | Description                              |
+|---------------------|------------------------------------------|
+| `ConvertFrom-Toml`  | Parse TOML text → `TomlDocument`         |
+| `ConvertTo-Toml`    | Serialize object → TOML text             |
+| `Import-Toml`       | Read TOML file → `TomlDocument`          |
+| `Export-Toml`       | Write object or `TomlDocument` to file   |
+| `Format-Toml`       | Normalize TOML text to canonical form    |
+| `Test-Toml`         | Validate TOML text without throwing      |
+| `Merge-Toml`        | Merge two TOML documents into one        |
+
+## Implementation notes
+
+- Pure PowerShell parser and serializer — no external TOML runtime dependency.
+- Duplicate keys and table redefinition are rejected per the TOML 1.0.0 spec.
+- Files are written as UTF-8 without BOM.
+
+## More examples
+
+See the [examples](examples) folder for runnable scripts. Use PowerShell help for per-command examples:
+
+```powershell
+Get-Help ConvertFrom-Toml -Examples
+Get-Help Import-Toml -Examples
+```
+
+## Documentation
+
+Full documentation is available at [psmodule.io/Toml](https://psmodule.io/Toml).
+
+## Contributing
+
+Coder or not, you can contribute to the project! We welcome all contributions.
+
+### For Users
+
+If you experience unexpected behavior, errors, or missing functionality, please open an issue on the [issues tab](https://github.com/PSModule/Toml/issues).
+
+### For Developers
+
+Please read the [Contribution guidelines](CONTRIBUTING.md) and pick up an existing issue or submit a new one.

build.ps1

@@ -0,0 +1,153 @@
+#!/usr/bin/env pwsh
+#Requires -Version 7.0
+<#
+    .SYNOPSIS
+    Builds the Toml module from source into ./output/Toml/.
+
+    .DESCRIPTION
+    Assembles all source files (classes, init, private functions, public functions)
+    into a single psm1 and creates a manifest, so tests can be run locally without
+    the PSModule CI pipeline.
+#>
+[CmdletBinding()]
+param(
+    # Version to stamp into the manifest.
+    [Alias('ModuleVersion')]
+    [string] $Version,
+
+    # Optional prerelease label to stamp into PrivateData.PSData.Prerelease.
+    [string] $Prerelease
+)
+
+$ErrorActionPreference = 'Stop'
+$moduleName = 'Toml'
+$srcPath = Join-Path $PSScriptRoot 'src'
+$outputPath = Join-Path -Path $PSScriptRoot -ChildPath 'output' -AdditionalChildPath $moduleName
+$resolvedVersion = if (-not [string]::IsNullOrWhiteSpace($Version)) {
+    $Version
+} elseif (-not [string]::IsNullOrWhiteSpace($env:PSMODULE_BUILD_PSMODULE_INPUT_Version)) {
+    $env:PSMODULE_BUILD_PSMODULE_INPUT_Version
+} else {
+    '0.0.1'
+}
+$resolvedPrerelease = if (-not [string]::IsNullOrWhiteSpace($Prerelease)) {
+    $Prerelease
+} elseif (-not [string]::IsNullOrWhiteSpace($env:PSMODULE_BUILD_PSMODULE_INPUT_Prerelease)) {
+    $env:PSMODULE_BUILD_PSMODULE_INPUT_Prerelease
+} else {
+    ''
+}
+
+# ── clean / create output directory ─────────────────────────────────────────
+if (Test-Path $outputPath) {
+    Remove-Item $outputPath -Recurse -Force
+}
+$null = New-Item -ItemType Directory -Path $outputPath -Force
+
+# ── build psm1 ───────────────────────────────────────────────────────────────
+$psm1Path = Join-Path $outputPath "$moduleName.psm1"
+$sb = [System.Text.StringBuilder]::new()
+
+# header
+$headerPath = Join-Path $srcPath 'header.ps1'
+if (Test-Path $headerPath) {
+    $null = $sb.AppendLine((Get-Content $headerPath -Raw))
+} else {
+    $null = $sb.AppendLine('$ErrorActionPreference = ''Stop''')
+    $null = $sb.AppendLine()
+}
+
+# init
+foreach ($f in (Get-ChildItem (Join-Path $srcPath 'init') -Filter '*.ps1' -ErrorAction SilentlyContinue)) {
+    $null = $sb.AppendLine((Get-Content $f.FullName -Raw))
+}
+
+# classes private then public
+foreach ($visibility in @('private', 'public')) {
+    $classPath = Join-Path $srcPath "classes/$visibility"
+    foreach ($f in (Get-ChildItem $classPath -Filter '*.ps1' -Recurse -ErrorAction SilentlyContinue)) {
+        $null = $sb.AppendLine((Get-Content $f.FullName -Raw))
+    }
+}
+
+# private functions
+foreach ($f in (Get-ChildItem (Join-Path $srcPath 'functions/private') -Filter '*.ps1' -Recurse -ErrorAction SilentlyContinue)) {
+    $null = $sb.AppendLine((Get-Content $f.FullName -Raw))
+}
+
+# public functions
+$publicFunctions = [System.Collections.Generic.List[string]]::new()
+foreach ($f in (Get-ChildItem (Join-Path $srcPath 'functions/public') -Filter '*.ps1' -Recurse -ErrorAction SilentlyContinue)) {
+    $null = $sb.AppendLine((Get-Content $f.FullName -Raw))
+    $publicFunctions.Add([System.IO.Path]::GetFileNameWithoutExtension($f.Name))
+}
+
+# finally
+$finallyPath = Join-Path $srcPath 'finally.ps1'
+if (Test-Path $finallyPath) {
+    $null = $sb.AppendLine((Get-Content $finallyPath -Raw))
+}
+
+# class exporter — registers public classes as type accelerators (required by PSModule framework)
+$null = $sb.AppendLine(@'
+#region Class exporter
+$TypeAcceleratorsClass = [psobject].Assembly.GetType('System.Management.Automation.TypeAccelerators')
+$ExistingTypeAccelerators = $TypeAcceleratorsClass::Get
+$ExportableEnums = @(
+    [TomlValueKind]
+)
+$ExportableEnums | ForEach-Object { Write-Verbose "Exporting enum '$($_.FullName)'." }
+foreach ($Type in $ExportableEnums) {
+    if ($Type.FullName -in $ExistingTypeAccelerators.Keys) {
+        Write-Verbose "Enum already exists [$($Type.FullName)]. Skipping."
+    } else {
+        Write-Verbose "Importing enum '$Type'."
+        $TypeAcceleratorsClass::Add($Type.FullName, $Type)
+    }
+}
+$ExportableClasses = @(
+    [TomlDocument]
+)
+$ExportableClasses | ForEach-Object { Write-Verbose "Exporting class '$($_.FullName)'." }
+foreach ($Type in $ExportableClasses) {
+    if ($Type.FullName -in $ExistingTypeAccelerators.Keys) {
+        Write-Verbose "Class already exists [$($Type.FullName)]. Skipping."
+    } else {
+        Write-Verbose "Importing class '$Type'."
+        $TypeAcceleratorsClass::Add($Type.FullName, $Type)
+    }
+}
+$MyInvocation.MyCommand.ScriptBlock.Module.OnRemove = {
+    foreach ($Type in ($ExportableEnums + $ExportableClasses)) {
+        $null = $TypeAcceleratorsClass::Remove($Type.FullName)
+    }
+}.GetNewClosure()
+#endregion Class exporter
+'@)
+
+# Export-ModuleMember
+$null = $sb.AppendLine("Export-ModuleMember -Function @($($publicFunctions | ForEach-Object { "'$_'" } | Join-String -Separator ', '))")
+
+[System.IO.File]::WriteAllText($psm1Path, $sb.ToString(), [System.Text.UTF8Encoding]::new($true))
+
+# ── write manifest ────────────────────────────────────────────────────────────
+$psd1Path = Join-Path $outputPath "$moduleName.psd1"
+$manifest = @{
+    Path              = $psd1Path
+    ModuleVersion     = $resolvedVersion
+    RootModule        = "$moduleName.psm1"
+    FunctionsToExport = $publicFunctions.ToArray()
+    PowerShellVersion = '7.6'
+    Description       = 'PowerShell module for reading and writing TOML data.'
+    Author            = 'PSModule'
+    CompanyName       = 'PSModule'
+    GUID              = '6f1b6f8d-1234-4321-abcd-ef0123456789'
+}
+New-ModuleManifest @manifest
+
+if (-not [string]::IsNullOrWhiteSpace($resolvedPrerelease)) {
+    Write-Output "Built $moduleName $resolvedVersion-$resolvedPrerelease -> $outputPath"
+} else {
+    Write-Output "Built $moduleName $resolvedVersion -> $outputPath"
+}
+Write-Output "Public functions: $($publicFunctions -join ', ')"