Skip to content

Commit 4e472cf

Browse files
MariusStorhaugCopilot
MariusStorhaug
and
Copilot
committed
docs: describe YAML compatibility boundaries
Document command contracts, safety limits, pipeline behavior, supported data types, unknown-tag handling, and non-preserved YAML presentation details with working examples. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 7715d3e commit 4e472cf

2 files changed

Lines changed: 177 additions & 50 deletions

File tree

‎README.md‎

Lines changed: 138 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,170 @@
1-
# {{ NAME }}
1+
# Yaml
22

3-
{{ DESCRIPTION }}
3+
`Yaml` converts between YAML streams and PowerShell values. It uses
4+
YamlDotNet's low-level parser and emitter while applying YAML 1.2 core-schema
5+
rules in PowerShell, without activating .NET types from YAML tags.
46

5-
## Prerequisites
7+
## Installation
8+
9+
```powershell
10+
Install-PSResource -Name Yaml
11+
Import-Module -Name Yaml
12+
```
613

7-
This uses the following external resources:
8-
- The [PSModule framework](https://github.com/PSModule) for building, testing and publishing the module.
14+
The module exports:
915

10-
## Installation
16+
| Command | Purpose |
17+
| --- | --- |
18+
| `ConvertFrom-Yaml` | Parse one or more YAML documents into PowerShell values. |
19+
| `ConvertTo-Yaml` | Serialize supported PowerShell values as YAML 1.2-compatible text. |
20+
| `Test-Yaml` | Test YAML syntax, tags, duplicate keys, and configured resource limits. |
21+
22+
## Parse YAML
1123

12-
To install the module from the PowerShell Gallery, you can use the following command:
24+
Ordinary string-key mappings become ordered `PSCustomObject` values. A
25+
top-level sequence writes its items to the pipeline by default.
1326

1427
```powershell
15-
Install-PSResource -Name {{ NAME }}
16-
Import-Module -Name {{ NAME }}
28+
$config = @'
29+
name: example
30+
enabled: true
31+
ports: [80, 443]
32+
'@ | ConvertFrom-Yaml
33+
34+
$config.name
35+
$config.ports[0]
1736
```
1837

19-
## Usage
38+
Pipeline strings are joined with LF and parsed as one stream. This makes
39+
line-oriented input work as expected:
2040

21-
Here is a list of example that are typical use cases for the module.
22-
23-
### Example 1: Greet an entity
41+
```powershell
42+
$config = Get-Content -Path '.\config.yaml' | ConvertFrom-Yaml
43+
```
2444

25-
Provide examples for typical commands that a user would like to do with the module.
45+
Use `-NoEnumerate` when a top-level sequence must remain one pipeline record:
2646

2747
```powershell
28-
Greet-Entity -Name 'World'
29-
Hello, World!
48+
$servers = @'
49+
- name: web-1
50+
- name: web-2
51+
'@ | ConvertFrom-Yaml -NoEnumerate
3052
```
3153

32-
### Example 2
54+
Every YAML document is returned separately:
55+
56+
```powershell
57+
$documents = @(@'
58+
---
59+
name: first
60+
---
61+
name: second
62+
'@ | ConvertFrom-Yaml)
63+
```
3364

34-
Provide examples for typical commands that a user would like to do with the module.
65+
Use `-AsHashtable` for insertion-ordered dictionaries and mappings with
66+
complex, non-string, empty, or case-colliding keys:
3567

3668
```powershell
37-
Import-Module -Name PSModuleTemplate
69+
$mapping = @'
70+
? [region, port]
71+
: eu-1
72+
'@ | ConvertFrom-Yaml -AsHashtable
3873
```
3974

40-
### Find more examples
75+
## Serialize PowerShell values
4176

42-
To find more examples of how to use the module, please refer to the [examples](examples) folder.
77+
`ConvertTo-Yaml` supports `PSCustomObject` and explicit PSObject note-property
78+
bags, dictionaries, sequences, strings, characters, Booleans, integer and
79+
floating-point numbers, `BigInteger`, `DateTime`, `DateTimeOffset`, enums,
80+
null, and byte arrays.
4381

44-
Alternatively, you can use the Get-Command -Module 'This module' to find more commands that are available in the module.
45-
To find examples of each of the commands you can use Get-Help -Examples 'CommandName'.
82+
```powershell
83+
$yaml = [ordered]@{
84+
name = 'example'
85+
enabled = $true
86+
ports = @(80, 443)
87+
} | ConvertTo-Yaml -ExplicitDocumentStart
4688
47-
## Documentation
89+
$roundTrip = $yaml | ConvertFrom-Yaml
90+
```
4891

49-
Link to further documentation if available, or describe where in the repository users can find more detailed documentation about
50-
the module's functions and features.
92+
Multiple pipeline records are collected into one top-level YAML sequence:
5193

52-
## Contributing
94+
```powershell
95+
'one', 'two' | ConvertTo-Yaml
96+
```
97+
98+
Pass an array directly when it represents one input value:
5399

54-
Coder or not, you can contribute to the project! We welcome all contributions.
100+
```powershell
101+
$items = @('one', 'two')
102+
ConvertTo-Yaml -InputObject $items
103+
```
104+
105+
`-EnumsAsStrings` emits enum names instead of their underlying numeric values.
106+
`-Indent` accepts 2 through 9 spaces. `-Depth`, `-MaxNodes`, and
107+
`-MaxScalarLength` constrain serialization.
55108

56-
### For Users
109+
Repeated acyclic collection references are emitted with anchors and aliases.
110+
Cyclic graphs and unsupported runtime objects fail specifically; values are
111+
never silently truncated or converted with `ToString()`.
57112

58-
If you don't code, you still sit on valuable information that can make this project even better. If you experience that the
59-
product does unexpected things, throw errors or is missing functionality, you can help by submitting bugs and feature requests.
60-
Please see the issues tab on this project and submit a new issue that matches your needs.
113+
## Validate YAML
61114

62-
### For Developers
115+
```powershell
116+
if (Get-Content -Path '.\config.yaml' | Test-Yaml) {
117+
'The YAML stream is valid.'
118+
}
119+
```
63120

64-
If you do code, we'd love to have your contributions. Please read the [Contribution guidelines](CONTRIBUTING.md) for more information.
65-
You can either help by picking up an existing issue or submit a new one if you have an idea for a new feature or improvement.
121+
`Test-Yaml` uses the same parser and limits as `ConvertFrom-Yaml`. It returns
122+
`$false` for YAML-specific failures, including duplicate keys and resource
123+
limit violations. Unexpected runtime failures are not suppressed.
124+
125+
## Data model and safety
126+
127+
- Plain implicit scalars use the YAML 1.2 core schema. YAML 1.1-only Boolean
128+
words such as `yes` and untagged timestamps remain strings.
129+
- Standard explicit tags are handled without reflection: `str`, `null`,
130+
`bool`, `int`, `float`, `binary`, `timestamp`, `seq`, `map`, `set`, `omap`,
131+
and `pairs`.
132+
- Unknown application tags are discarded safely. Tagged scalars become
133+
strings and tagged collections retain their sequence or mapping shape.
134+
- Duplicate mapping keys are rejected after scalar construction, including
135+
structurally equal complex keys.
136+
- Aliases preserve collection reference identity where PowerShell can
137+
represent it.
138+
- YAML merge keys are not expanded; `<<` is ordinary mapping data under the
139+
YAML 1.2 core schema.
140+
- Parsing defaults to depth 100, 100000 nodes, 1000 aliases, and 1048576
141+
decoded characters per scalar. The corresponding limit parameters can be
142+
lowered for untrusted input.
143+
144+
Default object projection requires mapping keys that can be represented
145+
without loss as PowerShell properties. Use `-AsHashtable` when that restriction
146+
does not fit the data.
147+
148+
## Compatibility boundaries
149+
150+
The module preserves data values and graph sharing where representable. A
151+
PowerShell object does not retain YAML presentation details, so data round
152+
trips do **not** preserve comments, scalar style, tag spelling or handles,
153+
anchor names, mapping presentation, line endings, or source formatting.
154+
Unknown application tags are not reconstructed.
155+
156+
Exact numeric CLR widths and enum CLR types are also not reconstructed after a
157+
YAML round trip. The emitter writes a deliberately limited YAML
158+
1.2-compatible subset even though YamlDotNet describes its emitter as YAML
159+
1.1.
160+
161+
## Third-party component
162+
163+
The packaged module includes YamlDotNet 18.1.0
164+
`lib/netstandard2.0/YamlDotNet.dll`. See
165+
[`src/THIRD-PARTY-NOTICES.txt`](src/THIRD-PARTY-NOTICES.txt) and
166+
[`src/licenses/YamlDotNet.LICENSE.txt`](src/licenses/YamlDotNet.LICENSE.txt).
66167

67-
## Acknowledgements
168+
## Contributing
68169

69-
Here is a list of people and projects that helped this project in some way.
170+
See [CONTRIBUTING.md](CONTRIBUTING.md).

‎examples/General.ps1‎

Lines changed: 39 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,45 @@
1-
<#
2-
.SYNOPSIS
3-
This is a general example of how to use the module.
1+
<#
2+
.SYNOPSIS
3+
Demonstrates the public Yaml commands.
44
#>
55

6-
# Import the module
7-
Import-Module -Name 'PSModule'
6+
Import-Module -Name Yaml
87

9-
# Define the path to the font file
10-
$FontFilePath = 'C:\Fonts\CodeNewRoman\CodeNewRomanNerdFontPropo-Regular.tff'
8+
$yaml = @'
9+
---
10+
name: example
11+
enabled: true
12+
ports: [80, 443]
13+
'@
1114

12-
# Install the font
13-
Install-Font -Path $FontFilePath -Verbose
15+
# Parse a mapping to an ordered PSCustomObject.
16+
$config = $yaml | ConvertFrom-Yaml
17+
$config
1418

15-
# List installed fonts
16-
Get-Font -Name 'CodeNewRomanNerdFontPropo-Regular'
19+
# Keep a top-level sequence as one pipeline record.
20+
$servers = @'
21+
- name: web-1
22+
- name: web-2
23+
'@ | ConvertFrom-Yaml -NoEnumerate
24+
$servers.Count
1725

18-
# Uninstall the font
19-
Get-Font -Name 'CodeNewRomanNerdFontPropo-Regular' | Uninstall-Font -Verbose
26+
# Preserve mappings whose keys cannot be PowerShell property names.
27+
$complexMapping = @'
28+
? [region, port]
29+
: eu-1
30+
'@ | ConvertFrom-Yaml -AsHashtable
31+
$complexMapping
32+
33+
# Serialize supported PowerShell data and parse it again.
34+
$outputYaml = [ordered]@{
35+
name = 'example'
36+
enabled = $true
37+
ports = @(80, 443)
38+
} | ConvertTo-Yaml -ExplicitDocumentStart
39+
40+
$outputYaml
41+
$outputYaml | ConvertFrom-Yaml
42+
43+
# Test syntax, duplicate keys, tags, and resource limits without conversion.
44+
$isValid = $outputYaml | Test-Yaml
45+
$isValid

0 commit comments

Comments
 (0)