| | | 1 | | # Portions derived from PowerShell-Yaml (https://github.com/cloudbase/powershell-yaml) |
| | | 2 | | # Copyright (c) 2016–2024 Cloudbase Solutions Srl |
| | | 3 | | # Licensed under the Apache License, Version 2.0 (Apache-2.0). |
| | | 4 | | # You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 |
| | | 5 | | # Modifications Copyright (c) 2025 Kestrun Contributors |
| | | 6 | | |
| | | 7 | | <# |
| | | 8 | | .SYNOPSIS |
| | | 9 | | Converts a YAML string to a PowerShell object or hashtable. |
| | | 10 | | .DESCRIPTION |
| | | 11 | | The ConvertFrom-KrYaml cmdlet converts a YAML string to a PowerShell object or |
| | | 12 | | hashtable. By default, it returns a PSCustomObject, but you can specify the |
| | | 13 | | -AsHashtable switch to get a hashtable instead. |
| | | 14 | | .PARAMETER Yaml |
| | | 15 | | The YAML string to convert. This parameter is mandatory and accepts input from the pipeline. |
| | | 16 | | .PARAMETER YamlBytes |
| | | 17 | | The YAML content as a byte array to convert. This parameter is mandatory when using the 'Bytes' parameter set. |
| | | 18 | | .PARAMETER AllDocuments |
| | | 19 | | If specified, all documents in a multi-document YAML stream will be returned as an array. By default, only the first |
| | | 20 | | .PARAMETER UseMergingParser |
| | | 21 | | If specified, the YAML parser will support the merging key (<<) for merging mappings. |
| | | 22 | | This is useful for YAML documents that use anchors and aliases to merge mappings. |
| | | 23 | | .EXAMPLE |
| | | 24 | | $yaml = @" |
| | | 25 | | name: John |
| | | 26 | | age: 30 |
| | | 27 | | skills: |
| | | 28 | | - PowerShell |
| | | 29 | | - YAML |
| | | 30 | | "@ |
| | | 31 | | $obj = $yaml | ConvertFrom-KrYaml |
| | | 32 | | # Outputs a PSCustomObject with properties Name, Age, and Skills. |
| | | 33 | | .EXAMPLE |
| | | 34 | | $yaml = @" |
| | | 35 | | --- |
| | | 36 | | name: John |
| | | 37 | | age: 30 |
| | | 38 | | --- |
| | | 39 | | name: Jane Doe |
| | | 40 | | age: 25 |
| | | 41 | | "@ |
| | | 42 | | $objs = $yaml | ConvertFrom-KrYaml -AllDocuments |
| | | 43 | | # Outputs an array of two PSCustomObjects, one for each document in the YAML stream. |
| | | 44 | | .EXAMPLE |
| | | 45 | | $yaml = @" |
| | | 46 | | defaults: &defaults |
| | | 47 | | adapter: postgres |
| | | 48 | | host: localhost |
| | | 49 | | development: |
| | | 50 | | database: dev_db |
| | | 51 | | <<: *defaults |
| | | 52 | | test: |
| | | 53 | | database: test_db |
| | | 54 | | <<: *defaults |
| | | 55 | | "@ |
| | | 56 | | $obj = $yaml | ConvertFrom-KrYaml -UseMergingParser |
| | | 57 | | # Outputs a PSCustomObject with merged properties for 'development' and 'test' sections |
| | | 58 | | # using the 'defaults' anchor. |
| | | 59 | | $obj | Format-List |
| | | 60 | | .EXAMPLE |
| | | 61 | | $yamlBytes = [System.Text.Encoding]::UTF8.GetBytes(@" |
| | | 62 | | name: John |
| | | 63 | | age: 30 |
| | | 64 | | "@) |
| | | 65 | | $obj = ConvertFrom-KrYaml -YamlBytes $yamlBytes |
| | | 66 | | # Outputs a PSCustomObject with properties Name and Age. |
| | | 67 | | .NOTES |
| | | 68 | | This cmdlet requires PowerShell 7.0 or later. |
| | | 69 | | It uses the Kestrun.Utilities.Yaml library for YAML deserialization. |
| | | 70 | | #> |
| | | 71 | | function ConvertFrom-KrYaml { |
| | | 72 | | [KestrunRuntimeApi('Everywhere')] |
| | | 73 | | [CmdletBinding(DefaultParameterSetName = 'String')] |
| | | 74 | | param( |
| | | 75 | | [Parameter(ValueFromPipeline = $true, Position = 0 , ParameterSetName = 'String')] |
| | | 76 | | [string]$Yaml, |
| | | 77 | | |
| | | 78 | | [Parameter(ParameterSetName = 'Bytes')] |
| | | 79 | | [byte[]]$YamlBytes, |
| | | 80 | | |
| | | 81 | | [Parameter()] |
| | | 82 | | [switch]$AllDocuments = $false, |
| | | 83 | | |
| | | 84 | | [Parameter()] |
| | | 85 | | [switch]$UseMergingParser = $false |
| | | 86 | | ) |
| | | 87 | | |
| | | 88 | | begin { |
| | 1 | 89 | | $builder = [System.Text.StringBuilder]::new() |
| | | 90 | | } |
| | | 91 | | process { |
| | 1 | 92 | | if ($PSCmdlet.ParameterSetName -eq 'Bytes') { |
| | 1 | 93 | | $str = [System.Text.Encoding]::UTF8.GetString($YamlBytes) |
| | 1 | 94 | | if ($builder.Length -gt 0) { |
| | 0 | 95 | | [void]$builder.Append("`n") |
| | | 96 | | } |
| | 1 | 97 | | [void]$builder.Append($str) |
| | 1 | 98 | | } elseif ($PSCmdlet.ParameterSetName -eq 'String') { |
| | 1 | 99 | | if ($Yaml -is [string]) { |
| | 1 | 100 | | if ($builder.Length -gt 0) { |
| | 0 | 101 | | [void]$builder.Append("`n") |
| | | 102 | | } |
| | 1 | 103 | | [void]$builder.Append($Yaml) |
| | | 104 | | } |
| | | 105 | | } |
| | | 106 | | } |
| | | 107 | | |
| | | 108 | | end { |
| | 1 | 109 | | $d = $builder.ToString() |
| | 1 | 110 | | if ([string]::IsNullOrEmpty($d)) { |
| | | 111 | | return |
| | | 112 | | } |
| | 1 | 113 | | $yamlStream = [Kestrun.Utilities.Yaml.YamlLoader]::GetYamlDocuments($d, $UseMergingParser) |
| | 1 | 114 | | $documents = $yamlStream.Documents |
| | 1 | 115 | | if (!$documents -or !$documents.Count) { |
| | | 116 | | return |
| | | 117 | | } |
| | 1 | 118 | | $firstRoot = $documents[0].RootNode |
| | | 119 | | |
| | | 120 | | # Extract datesAsStrings values (if present) from the parsed YAML object BEFORE conversion so we can restore the |
| | 1 | 121 | | $rawDatesAsStrings = $null |
| | 1 | 122 | | if ($firstRoot -is [System.Collections.IDictionary] -and $firstRoot.Keys -contains 'datesAsStrings') { |
| | 0 | 123 | | $seq = $firstRoot['datesAsStrings'] |
| | 0 | 124 | | if ($seq -is [System.Collections.IList]) { |
| | | 125 | | # Collect the original values as strings, preserving their lexical form |
| | 0 | 126 | | $rawDatesAsStrings = @() |
| | 0 | 127 | | foreach ($item in $seq) { |
| | 0 | 128 | | $rawDatesAsStrings += $item.ToString() |
| | | 129 | | } |
| | | 130 | | } |
| | | 131 | | } |
| | | 132 | | |
| | 1 | 133 | | if ($documents.Count -eq 1 -and -not $AllDocuments) { |
| | | 134 | | # Always request ordered conversion so original key order from YAML is preserved by default. |
| | 1 | 135 | | $single = [Kestrun.Utilities.Yaml.YamlTypeConverter]::ConvertYamlDocumentToPSObject($firstRoot, $true) |
| | 1 | 136 | | $single = Convert-DateTimeOffsetToDateTime $single |
| | 3 | 137 | | if ($rawDatesAsStrings -and ($single -is [System.Collections.IDictionary]) -and ($single.Keys -contains 'dat |
| | 0 | 138 | | $seq = $single['datesAsStrings'] |
| | 0 | 139 | | if ($seq -is [System.Collections.IList]) { |
| | 0 | 140 | | for ($i = 0; $i -lt $seq.Count -and $i -lt $rawDatesAsStrings.Count; $i++) { |
| | | 141 | | # Only replace if parser turned it into DateTime |
| | 0 | 142 | | if ($seq[$i] -is [datetime] -or $seq[$i] -is [DateTimeOffset]) { |
| | 0 | 143 | | $seq[$i] = $rawDatesAsStrings[$i] |
| | | 144 | | } |
| | | 145 | | } |
| | | 146 | | } |
| | | 147 | | } |
| | 1 | 148 | | return $single |
| | | 149 | | } |
| | 0 | 150 | | if (-not $AllDocuments) { |
| | | 151 | | # Always request ordered conversion so original key order from YAML is preserved by default. |
| | 0 | 152 | | $single = [Kestrun.Utilities.Yaml.YamlTypeConverter]::ConvertYamlDocumentToPSObject($firstRoot, $true) |
| | 0 | 153 | | $single = Convert-DateTimeOffsetToDateTime $single |
| | 0 | 154 | | if ($rawDatesAsStrings -and ($single -is [System.Collections.IDictionary]) -and ($single.Keys -contains 'dat |
| | 0 | 155 | | $seq = $single['datesAsStrings'] |
| | 0 | 156 | | if ($seq -is [System.Collections.IList]) { |
| | 0 | 157 | | for ($i = 0; $i -lt $seq.Count -and $i -lt $rawDatesAsStrings.Count; $i++) { |
| | 0 | 158 | | if ($seq[$i] -is [datetime] -or $seq[$i] -is [DateTimeOffset]) { |
| | 0 | 159 | | $seq[$i] = $rawDatesAsStrings[$i] |
| | | 160 | | } |
| | | 161 | | } |
| | | 162 | | } |
| | | 163 | | } |
| | 0 | 164 | | return $single |
| | | 165 | | } |
| | 0 | 166 | | $ret = @() |
| | 0 | 167 | | foreach ($i in $documents) { |
| | | 168 | | # Always preserve order in each document. |
| | 0 | 169 | | $val = [Kestrun.Utilities.Yaml.YamlTypeConverter]::ConvertYamlDocumentToPSObject($i.RootNode, $true) |
| | 0 | 170 | | $val = Convert-DateTimeOffsetToDateTime $val |
| | 0 | 171 | | if ($rawDatesAsStrings -and ($val -is [System.Collections.IDictionary]) -and ($val.Keys -contains 'datesAsSt |
| | 0 | 172 | | $seq = $val['datesAsStrings'] |
| | 0 | 173 | | if ($seq -is [System.Collections.IList]) { |
| | 0 | 174 | | for ($i2 = 0; $i2 -lt $seq.Count -and $i2 -lt $rawDatesAsStrings.Count; $i2++) { |
| | 0 | 175 | | if ($seq[$i2] -is [datetime] -or $seq[$i2] -is [DateTimeOffset]) { |
| | 0 | 176 | | $seq[$i2] = $rawDatesAsStrings[$i2] |
| | | 177 | | } |
| | | 178 | | } |
| | | 179 | | } |
| | | 180 | | } |
| | 0 | 181 | | $ret += $val |
| | | 182 | | } |
| | 0 | 183 | | return $ret |
| | | 184 | | } |
| | | 185 | | } |