public/prompts/Read-SpectreText.ps1
|
using module "..\..\private\completions\Completers.psm1" using module "..\..\private\completions\Transformers.psm1" function Read-SpectreText { <# .SYNOPSIS Prompts the user with a question and returns the user's input. .DESCRIPTION This function uses Spectre Console to prompt the user with a question and returns the user's input. :::caution I would advise against this and instead use `Read-Host` because the Spectre Console prompt doesn't have access to the PowerShell session history. Without session history you can't use the up and down arrow keys to navigate through your previous commands. This text entry also doesn't allow you to use arrow keys to go back and forwards through the text you're entering. ::: .PARAMETER Message The question to prompt the user with. .PARAMETER DefaultAnswer The default answer if the user does not provide any input. .PARAMETER AnswerColor The color of the user's answer input. The default behaviour uses the standard terminal text color. .PARAMETER AllowEmpty If specified, the user can provide an empty answer. .PARAMETER Choices An array of choices that the user can choose from. If specified, the user will be prompted with a list of choices to choose from, with validation. With autocomplete and can tab through the choices. .EXAMPLE # **Example 1** # This example demonstrates a simple text prompt with a default answer. $name = Read-SpectreText -Message "What's your name?" -DefaultAnswer "Prefer not to say" # Type "↲" to provide no answer Write-SpectreHost "Your name is '$name'" .EXAMPLE # **Example 2** # This example demonstrates a simple text prompt with a default answer and a color. $favouriteColor = Read-SpectreText -Message "What's your favorite color?" -DefaultAnswer "pink" # Type "orange", "↲" to enter your favourite color Write-SpectreHost "Your favourite color is '$favouriteColor'" .EXAMPLE # **Example 3** # This example demonstrates a simple text prompt with a default answer, a color, and a list of choices. $favouriteColor = Read-SpectreText -Message "What's your favorite color?" -AnswerColor "Cyan1" -Choices "Black", "Green", "Magenta", "I'll never tell!" # Type "orange", "↲", "magenta", "↲" to enter text that must match a choice in the choices list, orange will be rejected, magenta will be accepted Write-SpectreHost "Your favourite color is '$favouriteColor'" #> [Reflection.AssemblyMetadata("title", "Read-SpectreText")] param ( [Parameter(Mandatory)] [Alias("Title", "Question", "Prompt")] [string] $Message, [string] $DefaultAnswer, [ColorTransformationAttribute()] [ArgumentCompletionsSpectreColors()] [Spectre.Console.Color] $AnswerColor, [switch] $AllowEmpty, [int] $TimeoutSeconds, [string[]] $Choices ) $spectrePrompt = [Spectre.Console.TextPrompt[string]]::new($Message, [System.StringComparer]::InvariantCultureIgnoreCase) $spectrePrompt.DefaultValueStyle = [Spectre.Console.Style]::new($script:DefaultValueColor) if ($DefaultAnswer) { $spectrePrompt = [Spectre.Console.TextPromptExtensions]::DefaultValue($spectrePrompt, $DefaultAnswer) } if ($AnswerColor) { $spectrePrompt.PromptStyle = [Spectre.Console.Style]::new($AnswerColor) } $spectrePrompt.AllowEmpty = $AllowEmpty if ($null -ne $Choices) { $spectrePrompt = [Spectre.Console.TextPromptExtensions]::AddChoices($spectrePrompt, $Choices) } return Invoke-SpectrePromptAsync -Prompt $spectrePrompt -TimeoutSeconds $TimeoutSeconds } |