Private/New-HelpLabel.ps1
|
<#
.SYNOPSIS Adds labels with unique accelerator keys to objects. .DESCRIPTION Uses the specified property as the label text and inserts an ampersand before its first unused letter or digit other than S. Keys are case-insensitive and unique within one invocation. Processes objects in input order, preserves their properties, and adds or replaces HelpLabel. Reports an error if the property is missing, contains an ampersand, or has no available key. .PARAMETER InputObject Objects to extend, supplied directly as an array or through the pipeline. .PARAMETER PropertyName Property containing the label text, for example Username. .EXAMPLE $BestResults | New-HelpLabel -PropertyName 'Username' Adds HelpLabel to each object using a unique accelerator from Username. .OUTPUTS System.Management.Automation.PSCustomObject. The input objects with HelpLabel added. .COMPONENT Category: Sub Function .FUNCTIONALITY Adds HelpLabel from a specified property, using the first available case-insensitive letter or digit other than S as a unique key. #> function New-HelpLabel { [CmdletBinding()] param( [Parameter(Mandatory, ValueFromPipeline)] [pscustomobject[]]$InputObject, [Parameter(Mandatory)] [ValidateNotNullOrEmpty()] [string]$PropertyName ) begin { $Info = Measure-FunctionRuntime -Begin $UsedKeys = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase) } process { foreach ($Object in $InputObject) { $Property = $Object.PSObject.Properties[$PropertyName] if ($null -eq $Property) { throw "The input object does not contain property '$PropertyName'." } $Label = [string]$Property.Value if ($Label.Contains('&')) { throw "Property '$PropertyName' must not contain an ampersand." } $KeyIndex = -1 for ($Index = 0; $Index -lt $Label.Length; $Index++) { if ([char]::IsLetterOrDigit($Label[$Index]) -and [char]::ToUpperInvariant($Label[$Index]) -ne [char]'S' -and $UsedKeys.Add([string]$Label[$Index])) { $KeyIndex = $Index break } } if ($KeyIndex -lt 0) { throw "No unused accelerator key is available for '$Label' in property '$PropertyName'." } $Object | Add-Member -MemberType NoteProperty -Name HelpLabel -Value $Label.Insert($KeyIndex, '&') -Force -PassThru } } end { Measure-FunctionRuntime -End -Details $Info } } |