diff --git a/README.md b/README.md index 24d5ab0..b57c1c5 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,10 @@ works on YAML text at the representation level and never projects to PowerShell objects, which is what lets it keep tags, anchors, complex keys, and mapping order intact. +For interactive use, the conversion commands also export the short aliases +`cfy` for `ConvertFrom-Yaml` and `cty` for `ConvertTo-Yaml`. Prefer the +full command names in shared scripts and documentation. + ## Convert YAML to PowerShell values Ordinary string-key mappings become ordered `PSCustomObject` values. A top-level diff --git a/src/functions/public/Conversion/Conversion.md b/src/functions/public/Conversion/Conversion.md index 5cf8f43..7c6c03f 100644 --- a/src/functions/public/Conversion/Conversion.md +++ b/src/functions/public/Conversion/Conversion.md @@ -7,6 +7,15 @@ Convert between YAML text and PowerShell values. | [`ConvertFrom-Yaml`](https://psmodule.io/Yaml/Functions/Conversion/ConvertFrom-Yaml/) | Parse one or more YAML documents into PowerShell values. | | [`ConvertTo-Yaml`](https://psmodule.io/Yaml/Functions/Conversion/ConvertTo-Yaml/) | Serialize supported PowerShell values as YAML 1.2-compatible text. | +Short aliases are available for interactive pipelines: + +| Alias | Command | +| --- | --- | +| `cfy` | `ConvertFrom-Yaml` | +| `cty` | `ConvertTo-Yaml` | + +Use the full command names in shared scripts and examples where clarity matters. + Conversion projects YAML through to PowerShell values: a parsed document becomes objects, arrays and scalars you can index, filter and pass down the pipeline, and a PowerShell value becomes YAML text. If you need to keep YAML *as* YAML, with its diff --git a/src/functions/public/Conversion/ConvertFrom-Yaml.ps1 b/src/functions/public/Conversion/ConvertFrom-Yaml.ps1 index 59b55ff..482ff63 100644 --- a/src/functions/public/Conversion/ConvertFrom-Yaml.ps1 +++ b/src/functions/public/Conversion/ConvertFrom-Yaml.ps1 @@ -16,6 +16,9 @@ function ConvertFrom-Yaml { a ToString that renders the value as YAML text, so a parsed value can be shown in its source notation. Scalar documents keep their own ToString. + The short alias cfy is exported for interactive use. Prefer the full + command name in shared scripts. + .EXAMPLE 'name: Ada' | ConvertFrom-Yaml @@ -44,6 +47,7 @@ function ConvertFrom-Yaml { .LINK https://psmodule.io/Yaml/Functions/Conversion/ConvertFrom-Yaml/ #> + [Alias('cfy')] [CmdletBinding()] [OutputType([object])] param ( diff --git a/src/functions/public/Conversion/ConvertTo-Yaml.ps1 b/src/functions/public/Conversion/ConvertTo-Yaml.ps1 index 848911e..c6573ee 100644 --- a/src/functions/public/Conversion/ConvertTo-Yaml.ps1 +++ b/src/functions/public/Conversion/ConvertTo-Yaml.ps1 @@ -12,6 +12,9 @@ function ConvertTo-Yaml { Multiple pipeline records are collected into one top-level sequence. + The short alias cty is exported for interactive use. Prefer the full + command name in shared scripts. + .EXAMPLE [ordered]@{ name = 'Ada'; active = $true } | ConvertTo-Yaml @@ -35,6 +38,7 @@ function ConvertTo-Yaml { .LINK https://psmodule.io/Yaml/Functions/Conversion/ConvertTo-Yaml/ #> + [Alias('cty')] [CmdletBinding()] [OutputType([string])] param ( diff --git a/tests/Packaging.Tests.ps1 b/tests/Packaging.Tests.ps1 index 7da3ce8..5faad19 100644 --- a/tests/Packaging.Tests.ps1 +++ b/tests/Packaging.Tests.ps1 @@ -20,6 +20,10 @@ BeforeAll { . (Join-Path $PSScriptRoot 'TestBootstrap.ps1') $repositoryRoot = Split-Path -Parent $PSScriptRoot $loadedYamlModule = $yamlModule + $conversionAliases = [ordered]@{ + cfy = 'ConvertFrom-Yaml' + cty = 'ConvertTo-Yaml' + } $artifactManifestPath = if ($null -ne $loadedYamlModule) { Join-Path $loadedYamlModule.ModuleBase 'Yaml.psd1' } else { @@ -126,6 +130,24 @@ Describe 'Dependency-free package source' { $configuration | Should -Not -Match '(?ms)Build:\s+Docs:\s+.*Skip:\s*true' } + It 'exports the documented conversion command aliases' { + foreach ($aliasName in $conversionAliases.Keys) { + $alias = Get-Alias -Name $aliasName -ErrorAction Stop + + $alias.Source | Should -Be $loadedYamlModule.Name + $alias.Definition | Should -Be $conversionAliases[$aliasName] + } + } + + It 'uses aliases that do not conflict with built-in PowerShell commands' { + $builtInCommands = Get-Command -Module Microsoft.PowerShell.* -CommandType Alias, Function, Cmdlet | + Select-Object -ExpandProperty Name + + foreach ($aliasName in $conversionAliases.Keys) { + $builtInCommands | Should -Not -Contain $aliasName + } + } + It 'uses zensical configuration and does not skip site build' { $configuration = Get-Content -Path ( Join-Path $repositoryRoot '.github\PSModule.yml' @@ -158,6 +180,11 @@ Describe 'Generated artifact package' { 'Merge-Yaml', 'Test-Yaml' ) + @($manifest.AliasesToExport | Sort-Object) | + Should -Be @( + 'cfy', + 'cty' + ) @($manifest.FileList) | Should -Contain 'Yaml.psm1' $packagedFiles = @( Get-ChildItem -Path $moduleBase -Recurse -File |