🌟 [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@688896dc3ef70fb35bd74ae5328e76d5e57fe08a # v6.1.15
     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

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to Toml
+
+Thank you for your interest in improving the Toml module!
+
+## Reporting issues
+
+If you find a bug, have a feature request, or notice something unclear in the documentation, please open an issue in the [issue tracker](https://github.com/PSModule/Toml/issues).
+
+Include as much detail as possible, such as:
+
+- The version of the module you are using.
+- The version of PowerShell you are running (`$PSVersionTable`).
+- A minimal TOML snippet or script that reproduces the issue.
+- The expected behavior and the actual behavior.
+
+## Submitting changes
+
+1. Fork the repository and create a feature branch from `main`.
+2. Make focused, well-scoped changes.
+3. Add or update tests in `tests/` for any changed behavior.
+4. Run the local build and test suite:
+
+   ```powershell
+   pwsh -File .\build.ps1
+   Import-Module .\output\Toml\Toml.psd1 -Force
+   Invoke-Pester -Path .\tests\Toml.Tests.ps1
+   ```
+
+5. Ensure `PSScriptAnalyzer` reports no errors or warnings:
+
+   ```powershell
+   Invoke-ScriptAnalyzer -Path .\src -Recurse -Severity Error,Warning
+   ```
+
+6. Open a pull request with a clear description of the change and the problem it solves.
+
+## Coding conventions
+
+- Follow the existing file and folder structure under `src/`.
+- Keep functions small and focused.
+- Use `[ordered]` hashtables where key order matters.
+- Add comment-based help to public functions.
+- Write Pester tests for public commands and parser edge cases.
+
+## Code of conduct
+
+Be respectful and constructive. We welcome contributors of all experience levels.

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.