repository·prerelease·Indexed 42 days ago
https://github.com/shaunlawrie/pwshspectreconsoleA PowerShell module that wraps the Spectre.Console .NET library, providing a simplified interface for creating beautiful, interactive console applications. It enables advanced visual features like styled text, emojis, charts, and live-updating UIs (TUIs) using idiomatic PowerShell commands such as Read-SpectreSelection and Invoke-SpectreLive.
PwshSpectreConsole is a PowerShell wrapper for Spectre Console, a .NET library designed for creating highly visual and styled console applications.
While the original Spectre Console is written in C#, PwshSpectreConsole is implemented in PowerShell to make its core features more accessible to PowerShell users without requiring deep C# knowledge. It aims to bridge the gap between the advanced language features used in the C# library and the ease of use required for common PowerShell scripting use-cases.
Because Format-SpectrePanel only accepts a single renderable object, you must use layout containers to group multiple items before passing them to the panel function.
Use Format-SpectreRows to stack items vertically within a panel:
$message = "Thanks Jeff!"
$image = Get-SpectreImage -ImagePath ".\private\images\smiley.png" -MaxWidth 25
@($message, $image) | Format-SpectreRows | Format-SpectrePanelUse Format-SpectreColumns to place items side-by-side within a panel:
$message = "Thanks Jeff!"
$image = Get-SpectreImage -ImagePath ".\private\images\smiley.png" -MaxWidth 25
@($message, $image) | Format-SpectreColumns | Format-SpectrePanel@($message, $image) | Format-SpectreRows | Format-SpectrePanelYou can combine Invoke-SpectreCommandWithProgress with Add-SpectreJob and Wait-SpectreJobs to manage multiple background tasks while showing their progress in parallel.
For jobs with an estimated duration, you can use the -EstimatedDurationSeconds parameter with Wait-SpectreJobs. If the estimated time passes without the job completing, the progress bar will automatically switch to an indeterminate state.
$result = Invoke-SpectreCommandWithProgress -ScriptBlock {
param (
[Spectre.Console.ProgressContext] $Context
)
$job = Add-SpectreJob -Context $Context -JobName "Doing some work" -Job (
Start-Job { Start-Sleep -Seconds 10; return 1234 }
)
Wait-SpectreJobs -Context $Context -Jobs $job -EstimatedDurationSeconds 5
$result = Receive-Job -Job $job.Job
return $result
}When creating a layout, you can assign a -Name to it. This name allows you to access and update specific nested layouts within a larger root layout structure.
If you have a root layout $root and a nested layout named "row1", you can update the contents of that specific row using the indexer syntax and the .Update() method.
# Example of updating a nested layout named 'row1' within $root
$root = $root["row1"].Update(("hello row 1 again" | Format-SpectrePanel))A Renderable is an object that represents a visual element. Unlike previous versions that wrote directly to the console, most functions in v2 now return a renderable object.
This allows you to:
To return the object instead of writing it immediately, use the -PassThru switch on Write-* commandlets.
# Example of using renderable objects inside a table
$calendar = Write-SpectreCalendar -Date (Get-Date) -PassThru
$files = Get-ChildItem | Format-SpectreTable
$fruits = @(
(New-SpectreChartItem -Label "Bananas" -Value 2.2 -Color Yellow),
(New-SpectreChartItem -Label "Oranges" -Value 6.6 -Color Orange1),
(New-SpectreChartItem -Label "Apples" -Value 1 -Color Red)
) | Format-SpectreBarChart -Width 45
@{
Calendar = $calendar
Files = $files
Fruits = $fruits
} | Format-SpectreTable -Color Cyan1Install the PwshSpectreConsole module from the PowerShell Gallery using Install-Module. After installation, you can run Start-SpectreDemo to see a demonstration of the module's capabilities.
Install-Module PwshSpectreConsole -Scope CurrentUser
Start-SpectreDemoThe Canvas widget is not directly implemented as a PowerShell function in this module. To use it, you must interact with the underlying C# library directly. After creating and drawing on the canvas, use Out-SpectreHost to render it.
# Create a canvas
$canvas = [Spectre.Console.Canvas]::new(16, 16)
# Draw some shapes
for($i = 0; $i -lt $canvas.Width; $i++) {
# Cross
$canvas = $canvas.SetPixel($i, $i, [Spectre.Console.Color]::White)
$canvas = $canvas.SetPixel($canvas.Width - $i - 1, $i, [Spectre.Console.Color]::White)
# Border
$canvas = $canvas.SetPixel($i, 0, [Spectre.Console.Color]::Red)
$canvas = $canvas.SetPixel(0, $i, [Spectre.Console.Color]::Green)
$canvas = $canvas.SetPixel($i, $canvas.Height - 1, [Spectre.Console.Color]::Blue)
$canvas = $canvas.SetPixel($canvas.Width - 1, $i, [Spectre.Console.Color]::Yellow)
}
# Render the canvas
$canvas | Out-SpectreHostThe documentation site is generated from the comment-based help within module functions. To ensure correct Markdown generation, follow these rules:
DESCRIPTION: Used as the main description on the documentation site.PARAMETER: Documentation is kept and grouped under a 'Parameters' section.EXAMPLE: Used to generate code examples. You can provide multiple examples..EXAMPLE block cannot be a comment line. Doing so will break the Markdown generation process..EXAMPLE block so a user can copy and paste the entire block into a console.<#
.EXAMPLE
$data = @()
$data += New-SpectreChartItem -Label "Apples" -Value 10 -Color "Green"
Format-SpectreBarChart -Data $data -Label "Fruit Sales" -Width 50
#>In version 2, PwshSpectreConsole uses PowerShell formatting to render objects. By default, when rendered to the terminal, PowerShell adds a blank line before and after the item. To render an item without this additional whitespace, pipe the output to Out-SpectreHost.
$data | Format-SpectrePanel | Out-SpectreHostYou can find the full documentation for the module at the official website. For testing the latest features, use the prerelease documentation site.