diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Config/Set-SpectreColors.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Config/Set-SpectreColors.md index f58e9a53..49926d3a 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Config/Set-SpectreColors.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Config/Set-SpectreColors.md @@ -4,11 +4,18 @@ title: Set-SpectreColors + + + + ### Synopsis Sets the accent color and default value color for Spectre Console. + + --- + ### Description This function sets the accent color and default value color for Spectre Console. The accent color is used for highlighting important information, while the default value color is used for displaying default values. @@ -19,8 +26,11 @@ An example of the accent color is the highlight used in `Read-SpectreSelection`: An example of the default value color is the default value displayed in `Read-SpectreText`: ![Default value color example](/defaultcolor.png) + + --- + ### Examples Sets the accent color to Red and the default value color to Yellow. @@ -33,39 +43,77 @@ Sets the accent color to Green and keeps the default value color as Grey. Set-SpectreColors -AccentColor Green ``` + --- + ### Parameters #### **AccentColor** + The accent color to set. Must be a valid Spectre Console color name. Defaults to "Blue". + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |1 |false | + + #### **DefaultValueColor** + The default value color to set. Must be a valid Spectre Console color name. Defaults to "Grey". + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |2 |false | + + #### **DefaultTableHeaderColor** +The default table header color to set. Must be a valid Spectre Console color name. Defaults to "Default" which will be the standard console foreground color. + + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |3 |false | + + #### **DefaultTableTextColor** +The default table text color to set. Must be a valid Spectre Console color name. Defaults to "Default" which will be the standard console foreground color. + + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |4 |false | + + + + --- + ### Syntax ```powershell Set-SpectreColors [[-AccentColor] ] [[-DefaultValueColor] ] [[-DefaultTableHeaderColor] ] [[-DefaultTableTextColor] ] [] -Set-SpectreColors [[-AccentColor] ] [[-DefaultValueColor] ] [[-DefaultTableHeaderColor] ] [[-DefaultTableTextColor] ] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Demo/Get-SpectreDemoColors.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Demo/Get-SpectreDemoColors.md index ef1aa838..3f208742 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Demo/Get-SpectreDemoColors.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Demo/Get-SpectreDemoColors.md @@ -8,19 +8,29 @@ title: Get-SpectreDemoColors + + + + ### Synopsis Retrieves a list of Spectre Console colors and displays them with their corresponding markup. ![Spectre color demo](/colors.png) + + --- + ### Description The Get-SpectreDemoColors function retrieves a list of Spectre Console colors and displays them with their corresponding markup. It also provides information on how to use the colors as parameters for commands or in Spectre Console markup. + + --- + ### Examples Displays a list of Spectre Console colors and their corresponding markup. @@ -28,8 +38,10 @@ Displays a list of Spectre Console colors and their corresponding markup. PS> Get-SpectreDemoColors ``` + --- + ### Syntax ```powershell Get-SpectreDemoColors [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Demo/Get-SpectreDemoEmoji.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Demo/Get-SpectreDemoEmoji.md index 64a5899b..9bd9bd7d 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Demo/Get-SpectreDemoEmoji.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Demo/Get-SpectreDemoEmoji.md @@ -8,18 +8,28 @@ title: Get-SpectreDemoEmoji + + + + ### Synopsis Retrieves a collection of emojis available in Spectre Console. ![Example emojis](/emoji.png) + + --- + ### Description The Get-SpectreDemoEmoji function retrieves a collection of emojis available in Spectre Console. It displays the general emojis, faces, and provides information on how to use emojis in Spectre Console markup. + + --- + ### Examples Retrieves and displays the collection of emojis available in Spectre Console. @@ -27,15 +37,20 @@ Retrieves and displays the collection of emojis available in Spectre Console. Get-SpectreDemoEmoji ``` + --- + ### Notes Emoji support is dependent on the operating system, terminal, and font support. For more information on Spectre Console markup and emojis, refer to the following links: - Spectre Console Markup: https://spectreconsole.net/markup - Spectre Console Emojis: https://spectreconsole.net/appendix/emojis + + --- + ### Syntax ```powershell Get-SpectreDemoEmoji [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Demo/Start-SpectreDemo.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Demo/Start-SpectreDemo.md index 929b30e4..19b87490 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Demo/Start-SpectreDemo.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Demo/Start-SpectreDemo.md @@ -4,18 +4,28 @@ title: Start-SpectreDemo + + + + ### Synopsis Runs a demo of the PwshSpectreConsole module. ![Spectre demo animation](/demo.gif) + + --- + ### Description This function runs a demo of the PwshSpectreConsole module, showcasing some of its features. It displays various examples of Spectre.Console functionality wrapped in PowerShell functions, such as text entry, select lists, multi-select lists, and panels. + + --- + ### Examples Runs the PwshSpectreConsole demo. @@ -23,8 +33,10 @@ Runs the PwshSpectreConsole demo. PS C:\> Start-SpectreDemo ``` + --- + ### Syntax ```powershell Start-SpectreDemo [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreBarChart.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreBarChart.md index b86d38b2..3965f676 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreBarChart.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreBarChart.md @@ -4,18 +4,28 @@ title: Format-SpectreBarChart + + + + ### Synopsis Formats and displays a bar chart using the Spectre Console module. ![Example bar chart](/barchart.png) + + --- + ### Description This function takes an array of data and displays it as a bar chart using the Spectre Console module. The chart can be customized with a title and width. + + --- + ### Examples This example uses the new helper for generating chart items New-SpectreChartItem and shows the various ways of passing color values in @@ -28,39 +38,76 @@ $data += New-SpectreChartItem -Label "Bananas" -Value 2.2 -Color "#FFFF00" Format-SpectreBarChart -Data $data -Title "Fruit Sales" -Width 50 ``` + --- + ### Parameters #### **Data** + An array of objects containing the data to be displayed in the chart. Each object should have a Label, Value, and Color property. + + + + + |Type |Required|Position|PipelineInput | |---------|--------|--------|--------------| |`[Array]`|true |1 |true (ByValue)| + + #### **Title** + The title to be displayed above the chart. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |2 |false | + + #### **Width** + The width of the chart in characters. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |3 |false | + + #### **HideValues** + Hides the values from being displayed on the chart. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + + + --- + ### Syntax ```powershell Format-SpectreBarChart [-Data] [[-Title] ] [[-Width] ] [-HideValues] [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreBreakdownChart.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreBreakdownChart.md index 1115d692..8118350c 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreBreakdownChart.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreBreakdownChart.md @@ -4,18 +4,28 @@ title: Format-SpectreBreakdownChart + + + + ### Synopsis Formats data into a breakdown chart. ![Example breakdown chart](/breakdownchart.png) + + --- + ### Description This function takes an array of data and formats it into a breakdown chart using BreakdownChart. The chart can be customized with a specified width and color. + + --- + ### Examples This example uses the new helper for generating chart items New-SpectreChartItem and the various ways of passing color values in. @@ -28,39 +38,76 @@ $data += New-SpectreChartItem -Label "Bananas" -Value 2.2 -Color "#FFFF00" Format-SpectreBreakdownChart -Data $data -Width 50 ``` + --- + ### Parameters #### **Data** + An array of data to be formatted into a breakdown chart. + + + + + |Type |Required|Position|PipelineInput | |---------|--------|--------|--------------| |`[Array]`|true |1 |true (ByValue)| + + #### **Width** + The width of the chart. Defaults to the width of the console. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |2 |false | + + #### **HideTags** + Hides the tags on the chart. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + #### **HideTagValues** + Hides the tag values on the chart. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + + + --- + ### Syntax ```powershell Format-SpectreBreakdownChart [-Data] [[-Width] ] [-HideTags] [-HideTagValues] [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreJson.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreJson.md index 2b1c9918..cbf97a56 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreJson.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreJson.md @@ -8,20 +8,29 @@ title: Format-SpectreJson + + + + ### Synopsis Formats an array of objects into a Spectre Console Json. -Formats an array of objects into a Spectre Console Json. Thanks to [trackd](https://github.com/trackd) for adding this. ![Spectre json example](/json.png) + + --- + ### Description This function takes an array of objects and converts them into Json using the Spectre Console Json Library. + + --- + ### Examples This example formats an array of objects into a table with a double border and the accent color of the script. @@ -55,39 +64,77 @@ $data = @( Format-SpectreJson -Data $data -Title "Employee Data" -Border "Rounded" -Color "Green" ``` + --- + ### Parameters #### **Data** + The array of objects to be formatted into Json. + + + + + |Type |Required|Position|PipelineInput | |----------|--------|--------|--------------| |`[Object]`|true |1 |true (ByValue)| + + #### **Depth** + The maximum depth of the Json. Default is defined by the version of powershell. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |2 |false | + + #### **Title** + The title of the Json. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |3 |false | + + #### **NoBorder** + If specified, the Json will not be surrounded by a border. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + #### **Border** + The border style of the Json. Default is "Rounded". + + + Valid Values: * Ascii @@ -97,41 +144,79 @@ Valid Values: * Rounded * Square + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |4 |false | + + #### **Color** + The color of the Json border. Default is the accent color of the script. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |5 |false | + + #### **Width** + The width of the Json panel. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |6 |false | + + #### **Height** + The height of the Json panel. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |7 |false | + + #### **Expand** + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + + + --- + ### Syntax ```powershell Format-SpectreJson [-Data] [[-Depth] ] [[-Title] ] [-NoBorder] [[-Border] ] [[-Color] ] [[-Width] ] [[-Height] ] [-Expand] [] -Format-SpectreJson [-Data] [[-Depth] ] [[-Title] ] [-NoBorder] [[-Border] ] [[-Color] ] [[-Width] ] [[-Height] ] [-Expand] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectrePanel.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectrePanel.md index d3239e8e..8b6108db 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectrePanel.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectrePanel.md @@ -4,18 +4,28 @@ title: Format-SpectrePanel + + + + ### Synopsis Formats a string as a Spectre Console panel with optional title, border, and color. ![Spectre panel example](/panel.png) + + --- + ### Description This function takes a string and formats it as a Spectre Console panel with optional title, border, and color. The resulting panel can be displayed in the console using the Write-Host command. + + --- + ### Examples This example displays a panel with the title "My Panel", a rounded border, and a red border color. @@ -23,25 +33,47 @@ This example displays a panel with the title "My Panel", a rounded border, and a Format-SpectrePanel -Data "Hello, world!" -Title "My Panel" -Border "Rounded" -Color "Red" ``` + --- + ### Parameters #### **Data** + The string to be formatted as a panel. + + + + + |Type |Required|Position|PipelineInput | |----------|--------|--------|--------------| |`[Object]`|true |1 |true (ByValue)| + + #### **Title** + The title to be displayed at the top of the panel. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |2 |false | + + #### **Border** + The type of border to be displayed around the panel. + + + Valid Values: * Ascii @@ -51,42 +83,83 @@ Valid Values: * Rounded * Square + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |3 |false | + + #### **Expand** + Switch parameter that specifies whether the panel should be expanded to fill the available space. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + #### **Color** + The color of the panel border. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |4 |false | + + #### **Width** + The width of the panel. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |5 |false | + + #### **Height** + The height of the panel. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |6 |false | + + + + --- + ### Syntax ```powershell Format-SpectrePanel [-Data] [[-Title] ] [[-Border] ] [-Expand] [[-Color] ] [[-Width] ] [[-Height] ] [] -Format-SpectrePanel [-Data] [[-Title] ] [[-Border] ] [-Expand] [[-Color] ] [[-Width] ] [[-Height] ] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreTable.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreTable.md index 14707217..c750393f 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreTable.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreTable.md @@ -4,18 +4,28 @@ title: Format-SpectreTable + + + + ### Synopsis Formats an array of objects into a Spectre Console table. Thanks to [trackd](https://github.com/trackd) and [fmotion1](https://github.com/fmotion1) for the updates to support markdown and color in the table contents. ![Example table](/table.png) + + --- + ### Description This function takes an array of objects and formats them into a table using the Spectre Console library. The table can be customized with a border style and color. + + --- + ### Examples This example formats an array of objects into a table with a double border and the accent color of the script. @@ -45,18 +55,29 @@ Get-ChildItem | Format-SpectreTable -Property $Properties -AllowMarkup 1..10 | Format-SpectreTable -Title Numbers ``` + --- + ### Parameters #### **Data** + The array of objects to be formatted into a table. Takes pipeline input. + + + + + |Type |Required|Position|PipelineInput |Aliases | |----------|--------|--------|--------------|-----------| |`[Object]`|true |named |true (ByValue)|InputObject| + + #### **Property** + Specifies the object properties that appear in the display and the order in which they appear. Type one or more property names, separated by commas, or use a hash table to display a calculated property. Wildcards are permitted. @@ -69,28 +90,54 @@ The calculated property can be a script block or a hash table. Valid key-value p * Width - `` - must be greater than `0` * Alignment - value can be `Left`, `Center`, or `Right` + + + + + |Type |Required|Position|PipelineInput| |------------|--------|--------|-------------| |`[Object[]]`|false |1 |false | -|`[Object[]]`|false |1 |false | + + #### **Wrap** + Displays text that exceeds the column width on the next line. By default, text that exceeds the column width is truncated Currently there is a bug with this, spectre.console/issues/1185 + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + #### **View** + The View parameter lets you specify an alternate format or custom view for the table. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |named |false | + + #### **Border** + The border style of the table. Default is "Double". + + + Valid Values: * Ascii @@ -112,61 +159,127 @@ Valid Values: * SimpleHeavy * Square + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |named |false | + + #### **Color** + The color of the table border. Default is the accent color of the script. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |named |false | + + #### **HeaderColor** + The color of the table header text. Default is the DefaultTableHeaderColor. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |named |false | + + #### **TextColor** + The color of the table text. Default is the DefaultTableTextColor. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |named |false | + + #### **Width** + The width of the table. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |named |false | + + #### **HideHeaders** + Hides the headers of the table. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + #### **Title** + The title of the table. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |named |false | + + #### **AllowMarkup** + Allow Spectre markup in the table elements e.g. [green]message[/]. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + + + --- + ### Syntax ```powershell Format-SpectreTable -Data [-Wrap] [-Border ] [-Color ] [-HeaderColor ] [-TextColor ] [-Width ] [-HideHeaders] [-Title ] [-AllowMarkup] [] @@ -176,11 +289,4 @@ Format-SpectreTable -Data [[-Property] ] [-Wrap] [-Border [-Wrap] [-View ] [-Border ] [-Color ] [-HeaderColor ] [-TextColor ] [-Width ] [-HideHeaders] [-Title ] [-AllowMarkup] [] -Format-SpectreTable -Data [-Wrap] [-Border ] [-Color ] [-HeaderColor ] [-TextColor ] [-Width ] [-HideHeaders] [-Title ] [-AllowMarkup] [] -``` -```powershell -Format-SpectreTable -Data [[-Property] ] [-Wrap] [-Border ] [-Color ] [-HeaderColor ] [-TextColor ] [-Width ] [-HideHeaders] [-Title ] [-AllowMarkup] [] -``` -```powershell -Format-SpectreTable -Data [-Wrap] [-View ] [-Border ] [-Color ] [-HeaderColor ] [-TextColor ] [-Width ] [-HideHeaders] [-Title ] [-AllowMarkup] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreTree.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreTree.md index 4e7f8f67..60d5801b 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreTree.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/Format-SpectreTree.md @@ -4,17 +4,27 @@ title: Format-SpectreTree + + + + ### Synopsis Formats a hashtable as a tree using Spectre Console. + + --- + ### Description This function takes a hashtable and formats it as a tree using Spectre Console. The hashtable should have a 'Label' key and a 'Children' key. The 'Label' key should contain the label for the root node of the tree, and the 'Children' key should contain an array of hashtables representing the child nodes of the root node. Each child hashtable should have a 'Label' key and a 'Children' key, following the same structure as the root node. + + --- + ### Examples This example formats a hashtable as a tree with a heavy border and green color. @@ -44,16 +54,26 @@ $data = @{ Format-SpectreTree -Data $data -Guide BoldLine -Color "Green" ``` + --- + ### Parameters #### **Data** + The hashtable to format as a tree. + + + + + |Type |Required|Position|PipelineInput | |-------------|--------|--------|--------------| |`[Hashtable]`|true |1 |true (ByValue)| + + #### **Guide** Valid Values: @@ -63,21 +83,38 @@ Valid Values: * DoubleLine * Line + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |2 |false | + + #### **Color** + The color to use for the tree. This can be a Spectre Console color name or a hex color code. Default is the accent color defined in the script. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |3 |false | + + + + --- + ### Syntax ```powershell Format-SpectreTree [-Data] [[-Guide] ] [[-Color] ] [] -Format-SpectreTree [-Data] [[-Guide] ] [[-Color] ] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/New-SpectreChartItem.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/New-SpectreChartItem.md index 710fbb23..be7223ac 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/New-SpectreChartItem.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Formatting/New-SpectreChartItem.md @@ -8,17 +8,27 @@ title: New-SpectreChartItem + + + + ### Synopsis Creates a new SpectreChartItem object. + + --- + ### Description The New-SpectreChartItem function creates a new SpectreChartItem object with the specified label, value, and color for use in Format-SpectreBarChart and Format-SpectreBreakdownChart. + + --- + ### Examples This example creates an array of new SpectreChartItem objects you can pass into the chart functions. @@ -29,34 +39,62 @@ $data += New-SpectreChartItem -Label "Expenses" -Value 500 -Color "#ff0000" $data += New-SpectreChartItem -Label "Profit" -Value 500 -Color ([Spectre.Console.Color]::Blue) ``` + --- + ### Parameters #### **Label** + The label for the chart item. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|true |1 |false | + + #### **Value** + The value for the chart item. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Double]`|true |2 |false | + + #### **Color** + The color for the chart item. Must be a valid Spectre color as name, hex or a Spectre.Console.Color object. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|true |3 |false | + + + + --- + ### Syntax ```powershell New-SpectreChartItem [-Label] [-Value] [-Color] [] -New-SpectreChartItem [-Label] [-Value] [-Color] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Images/Get-SpectreImage.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Images/Get-SpectreImage.md index e63e80fb..32e4986f 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Images/Get-SpectreImage.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Images/Get-SpectreImage.md @@ -4,17 +4,27 @@ title: Get-SpectreImage + + + + ### Synopsis Displays an image in the console using CanvasImage. + + --- + ### Description Displays an image in the console using CanvasImage. The image can be resized to a maximum width if desired. + + --- + ### Examples Displays the image located at "C:\Images\myimage.png" with a maximum width of 80 characters. @@ -22,25 +32,46 @@ Displays the image located at "C:\Images\myimage.png" with a maximum width of 80 Get-SpectreImage -ImagePath "C:\Images\myimage.png" -MaxWidth 80 ``` + --- + ### Parameters #### **ImagePath** + The path to the image file to be displayed. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |1 |false | + + #### **MaxWidth** + The maximum width of the image. If not specified, the image will be displayed at its original size. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |2 |false | + + + + --- + ### Syntax ```powershell Get-SpectreImage [[-ImagePath] ] [[-MaxWidth] ] [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Images/Get-SpectreImageExperimental.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Images/Get-SpectreImageExperimental.md index 30024151..f693de98 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Images/Get-SpectreImageExperimental.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Images/Get-SpectreImageExperimental.md @@ -8,20 +8,30 @@ title: Get-SpectreImageExperimental + + + + ### Synopsis Displays an image in the console using block characters and ANSI escape codes. :::caution This is experimental. ::: + + --- + ### Description This function loads an image from a file and displays it in the console using block characters and ANSI escape codes. The image is scaled to fit within the specified maximum width while maintaining its aspect ratio. If the image is an animated GIF, each frame is displayed in sequence with a configurable delay between frames. + + --- + ### Examples Displays the image "MyImage.png" in the console with a maximum width of 80 characters. @@ -34,50 +44,99 @@ Displays the animated GIF "MyAnimation.gif" in the console with a maximum width PS C:\> Get-SpectreImageExperimental -ImagePath "C:\Images\MyAnimation.gif" -MaxWidth 80 ``` + --- + ### Parameters #### **ImagePath** + The path to the image file to display. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |1 |false | + + #### **ImageUrl** +The URL to the image file to display. If specified, the image is downloaded to a temporary file and then displayed. + + + + + + |Type |Required|Position|PipelineInput| |-------|--------|--------|-------------| |`[Uri]`|false |2 |false | + + #### **Width** + The width of the image in characters. The image is scaled to fit within this width while maintaining its aspect ratio. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |3 |false | + + #### **LoopCount** +The number of times to repeat the animation. The default value is 0, which means the animation will repeat forever. Press ctrl-c to stop the animation. + + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |4 |false | + + #### **Resampler** + The resampling algorithm to use when scaling the image. Valid values are "Bicubic" and "NearestNeighbor". The default value is "Bicubic". + + + Valid Values: * Bicubic * NearestNeighbor + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |5 |false | + + + + --- + ### Syntax ```powershell Get-SpectreImageExperimental [[-ImagePath] ] [[-ImageUrl] ] [[-Width] ] [[-LoopCount] ] [[-Resampler] ] [] -Get-SpectreImageExperimental [[-ImagePath] ] [[-ImageUrl] ] [[-Width] ] [[-LoopCount] ] [[-Resampler] ] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Add-SpectreJob.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Add-SpectreJob.md index e8f9903d..177b0d70 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Add-SpectreJob.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Add-SpectreJob.md @@ -4,20 +4,30 @@ title: Add-SpectreJob + + + + ### Synopsis Adds a Spectre job to a list of jobs. :::note This is only used inside `Invoke-SpectreCommandWithProgress` where the Spectre ProgressContext object is exposed. ::: + + --- + ### Description This function adds a Spectre job to the list of jobs you want to wait for with Wait-SpectreJobs. + + --- + ### Examples This is an example of how to use the Add-SpectreJob function to add two jobs to a jobs list that can be passed to Wait-SpectreJobs when you're inside Invoke-SpectreCommandWithProgress. @@ -33,35 +43,63 @@ Invoke-SpectreCommandWithProgress -ScriptBlock { } ``` + --- + ### Parameters #### **Context** + The Spectre context to add the job to. The context object is only available inside Invoke-SpectreCommandWithProgress. [https://spectreconsole.net/api/spectre.console/progresscontext/](https://spectreconsole.net/api/spectre.console/progresscontext/) + + + + + |Type |Required|Position|PipelineInput| |-------------------|--------|--------|-------------| |`[ProgressContext]`|true |1 |false | + + #### **JobName** + The name of the job to add. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|true |2 |false | + + #### **Job** + The PowerShell job to add to the context. + + + + + |Type |Required|Position|PipelineInput| |-------|--------|--------|-------------| |`[Job]`|true |3 |false | + + + + --- + ### Syntax ```powershell Add-SpectreJob [-Context] [-JobName] [-Job] [] -Add-SpectreJob [-Context] [-JobName] [-Job] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Invoke-SpectreCommandWithProgress.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Invoke-SpectreCommandWithProgress.md index a8f52174..f5c629af 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Invoke-SpectreCommandWithProgress.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Invoke-SpectreCommandWithProgress.md @@ -4,18 +4,28 @@ title: Invoke-SpectreCommandWithProgress + + + + ### Synopsis Invokes a Spectre command with a progress bar. + + --- + ### Description This function takes a script block as a parameter and executes it while displaying a progress bar. The context and task objects are defined at [https://spectreconsole.net/api/spectre.console/progresscontext/](https://spectreconsole.net/api/spectre.console/progresscontext/). The context requires at least one task to be added for progress to be displayed. The task object is used to update the progress bar by calling the Increment() method or other methods defined in Spectre console [https://spectreconsole.net/api/spectre.console/progresstask/](https://spectreconsole.net/api/spectre.console/progresstask/). + + --- + ### Examples This example will display a progress bar while the script block is executing. @@ -50,18 +60,31 @@ Invoke-SpectreCommandWithProgress -ScriptBlock { } ``` + --- + ### Parameters #### **ScriptBlock** + The script block to execute. + + + + + |Type |Required|Position|PipelineInput| |---------------|--------|--------|-------------| |`[ScriptBlock]`|true |1 |false | + + + + --- + ### Syntax ```powershell Invoke-SpectreCommandWithProgress [-ScriptBlock] [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Invoke-SpectreCommandWithStatus.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Invoke-SpectreCommandWithStatus.md index f8a7b6de..ba7f64ee 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Invoke-SpectreCommandWithStatus.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Invoke-SpectreCommandWithStatus.md @@ -4,17 +4,27 @@ title: Invoke-SpectreCommandWithStatus + + + + ### Synopsis Invokes a script block with a Spectre status spinner. + + --- + ### Description This function starts a Spectre status spinner with the specified title and spinner type, and invokes the specified script block. The spinner will continue to spin until the script block completes. + + --- + ### Examples Starts a Spectre status spinner with the "dots" spinner type, a yellow color, and the title "Waiting for process to complete". The spinner will continue to spin for 5 seconds. @@ -22,18 +32,32 @@ Starts a Spectre status spinner with the "dots" spinner type, a yellow color, an Invoke-SpectreCommandWithStatus -ScriptBlock { Start-Sleep -Seconds 5 } -Spinner dots -Title "Waiting for process to complete" -Color yellow ``` + --- + ### Parameters #### **ScriptBlock** + The script block to invoke. + + + + + |Type |Required|Position|PipelineInput| |---------------|--------|--------|-------------| |`[ScriptBlock]`|true |1 |false | + + #### **Spinner** + The type of spinner to display. + + + Valid Values: * Aesthetic @@ -112,28 +136,53 @@ Valid Values: * Triangle * Weather + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |2 |false | + + #### **Title** + The title to display above the spinner. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|true |3 |false | + + #### **Color** + The color of the spinner. Valid values can be found with Get-SpectreDemoColors. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |4 |false | + + + + --- + ### Syntax ```powershell Invoke-SpectreCommandWithStatus [-ScriptBlock] [[-Spinner] ] [-Title] [[-Color] ] [] -Invoke-SpectreCommandWithStatus [-ScriptBlock] [[-Spinner] ] [-Title] [[-Color] ] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Invoke-SpectreScriptBlockQuietly.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Invoke-SpectreScriptBlockQuietly.md index 345053ec..d26d8467 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Invoke-SpectreScriptBlockQuietly.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Invoke-SpectreScriptBlockQuietly.md @@ -8,6 +8,10 @@ title: Invoke-SpectreScriptBlockQuietly + + + + ### Synopsis This is a test function for invoking a script block in a background job inside Invoke-SpectreCommandWithProgress to help with https://github.com/ShaunLawrie/PwshSpectreConsole/issues/7 Some commands cause output that interferes with the progress bar, this function is an attempt to suppress that output when all other attempts have failed. @@ -15,14 +19,20 @@ Some commands cause output that interferes with the progress bar, this function This is experimental. ::: + + --- + ### Description This function invokes a script block in a background job and returns the output. It also provides an option to suppress the output even more if there is garbage being printed to stderr if using Level = Quieter. + + --- + ### Examples This example invokes the git command in a background job and suppresses the output completely even though it would have written to stderr and thrown an error. @@ -35,29 +45,53 @@ Invoke-SpectreScriptBlockQuietly -Level Quieter -Command { } ``` + --- + ### Parameters #### **Command** + The script block to be invoked. + + + + + |Type |Required|Position|PipelineInput| |---------------|--------|--------|-------------| |`[ScriptBlock]`|false |1 |false | + + #### **Level** + Suppresses the output by varying amounts. + + + Valid Values: * Quiet * Quieter + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |2 |false | + + + + --- + ### Syntax ```powershell Invoke-SpectreScriptBlockQuietly [[-Command] ] [[-Level] ] [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Wait-SpectreJobs.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Wait-SpectreJobs.md index ec3e6e85..72ebb55c 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Wait-SpectreJobs.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Progress/Wait-SpectreJobs.md @@ -4,21 +4,31 @@ title: Wait-SpectreJobs + + + + ### Synopsis Waits for Spectre jobs to complete. :::note This is only used inside `Invoke-SpectreCommandWithProgress` where the Spectre ProgressContext object is exposed. ::: + + --- + ### Description This function waits for Spectre jobs to complete by checking the progress of each job and updating the corresponding task value. Adapted from https://key2consulting.com/powershell-how-to-display-job-progress/ + + --- + ### Examples Waits for two jobs to complete @@ -34,33 +44,62 @@ Invoke-SpectreCommandWithProgress -ScriptBlock { } ``` + --- + ### Parameters #### **Context** + The Spectre progress context object. [https://spectreconsole.net/api/spectre.console/progresscontext/](https://spectreconsole.net/api/spectre.console/progresscontext/) + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Object]`|true |1 |false | + + #### **Jobs** + An array of Spectre jobs which are decorated PowerShell jobs. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Array]`|true |2 |false | + + #### **TimeoutSeconds** + The maximum number of seconds to wait for the jobs to complete. Defaults to 60 seconds. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |3 |false | + + + + --- + ### Syntax ```powershell Wait-SpectreJobs [-Context] [-Jobs] [[-TimeoutSeconds] ] [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreConfirm.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreConfirm.md index fcdc42f8..468728e4 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreConfirm.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreConfirm.md @@ -4,17 +4,27 @@ title: Read-SpectreConfirm + + + + ### Synopsis Displays a simple confirmation prompt with the option of selecting yes or no and returns a boolean representing the answer. + + --- + ### Description Displays a simple confirmation prompt with the option of selecting yes or no. Additional options are provided to display either a success or failure response message in addition to the boolean return value. + + --- + ### Examples This example displays a simple prompt. The user can select either yes or no [Y/n]. A different message is displayed based on the user's selection. The prompt uses the AnsiConsole.MarkupLine convenience method to support colored text and other supported markup. @@ -27,52 +37,96 @@ $readSpectreConfirmSplat = @{ Read-SpectreConfirm @readSpectreConfirmSplat ``` + --- + ### Parameters #### **Prompt** + The prompt to display to the user. The default value is "Do you like cute animals?". + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |1 |false | + + #### **DefaultAnswer** + The default answer to the prompt if the user just presses enter. The default value is "y". + + + Valid Values: * y * n * none + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |2 |false | + + #### **ConfirmSuccess** + The text and markup to display if the user chooses yes. If left undefined, nothing will display. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |3 |false | + + #### **ConfirmFailure** + The text and markup to display if the user chooses no. If left undefined, nothing will display. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |4 |false | + + #### **Color** + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |5 |false | + + + + --- + ### Syntax ```powershell Read-SpectreConfirm [[-Prompt] ] [[-DefaultAnswer] ] [[-ConfirmSuccess] ] [[-ConfirmFailure] ] [[-Color] ] [] -Read-SpectreConfirm [[-Prompt] ] [[-DefaultAnswer] ] [[-ConfirmSuccess] ] [[-ConfirmFailure] ] [[-Color] ] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreMultiSelection.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreMultiSelection.md index d4cd2de6..3dea1a18 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreMultiSelection.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreMultiSelection.md @@ -4,17 +4,27 @@ title: Read-SpectreMultiSelection + + + + ### Synopsis Displays a multi-selection prompt using Spectre Console and returns the selected choices. + + --- + ### Description This function displays a multi-selection prompt using Spectre Console and returns the selected choices. The prompt allows the user to select one or more choices from a list of options. The function supports customizing the title, choices, choice label property, color, and page size of the prompt. + + --- + ### Examples Displays a multi-selection prompt with the title "Select your favourite fruits", the list of fruits, the "Name" property as the label for each fruit, the color green for highlighting the selected fruits, and 3 fruits per page. @@ -22,55 +32,107 @@ Displays a multi-selection prompt with the title "Select your favourite fruits", Read-SpectreMultiSelection -Title "Select your favourite fruits" -Choices @("apple", "banana", "orange", "pear", "strawberry") -Color "Green" -PageSize 3 ``` + --- + ### Parameters #### **Title** + The title of the prompt. Defaults to "What are your favourite [color]?". + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |1 |false | + + #### **Choices** + The list of choices to display in the selection prompt. ChoiceLabelProperty is required if the choices are complex objects rather than an array of strings. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Array]`|false |2 |false | + + #### **ChoiceLabelProperty** + If the object is complex then the property of the choice object to use as the label in the selection prompt is required. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |3 |false | + + #### **Color** + The color to use for highlighting the selected choices. Defaults to the accent color of the script. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |4 |false | + + #### **PageSize** + The number of choices to display per page. Defaults to 5. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |5 |false | + + #### **AllowEmpty** + Allow the multi-selection to be submitted without any options chosen. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + + + --- + ### Syntax ```powershell Read-SpectreMultiSelection [[-Title] ] [[-Choices] ] [[-ChoiceLabelProperty] ] [[-Color] ] [[-PageSize] ] [-AllowEmpty] [] -Read-SpectreMultiSelection [[-Title] ] [[-Choices] ] [[-ChoiceLabelProperty] ] [[-Color] ] [[-PageSize] ] [-AllowEmpty] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreMultiSelectionGrouped.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreMultiSelectionGrouped.md index 09cb3c11..569971d1 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreMultiSelectionGrouped.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreMultiSelectionGrouped.md @@ -4,17 +4,27 @@ title: Read-SpectreMultiSelectionGrouped + + + + ### Synopsis Displays a multi-selection prompt with grouped choices and returns the selected choices. + + --- + ### Description Displays a multi-selection prompt with grouped choices and returns the selected choices. The prompt allows the user to select one or more choices from a list of options. The choices can be grouped into categories, and the user can select choices from each category. + + --- + ### Examples This example displays a multi-selection prompt with two groups of choices: "Primary Colors" and "Secondary Colors". The prompt uses the "Name" property of each choice as the label. The user can select one or more choices from each group. @@ -31,55 +41,107 @@ Read-SpectreMultiSelectionGrouped -Title "Select your favorite colors" -Choices ) ``` + --- + ### Parameters #### **Title** + The title of the prompt. The default value is "What are your favourite [color]?". + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |1 |false | + + #### **Choices** + An array of choice groups. Each group is a hashtable with two keys: "Name" and "Choices". The "Name" key is a string that represents the name of the group, and the "Choices" key is an array of strings that represents the choices in the group. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Array]`|false |2 |false | + + #### **ChoiceLabelProperty** + The name of the property to use as the label for each choice. If this parameter is not specified, the choices are displayed as strings. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |3 |false | + + #### **Color** + The color of the selected choices. The default value is the accent color of the script. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |4 |false | + + #### **PageSize** + The number of choices to display per page. The default value is 10. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |5 |false | + + #### **AllowEmpty** + Allow the multi-selection to be submitted without any options chosen. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + + + --- + ### Syntax ```powershell Read-SpectreMultiSelectionGrouped [[-Title] ] [[-Choices] ] [[-ChoiceLabelProperty] ] [[-Color] ] [[-PageSize] ] [-AllowEmpty] [] -Read-SpectreMultiSelectionGrouped [[-Title] ] [[-Choices] ] [[-ChoiceLabelProperty] ] [[-Color] ] [[-PageSize] ] [-AllowEmpty] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectrePause.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectrePause.md index 540d603c..7360d61e 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectrePause.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectrePause.md @@ -4,17 +4,27 @@ title: Read-SpectrePause + + + + ### Synopsis Pauses the script execution and waits for user input to continue. + + --- + ### Description The Read-SpectrePause function pauses the script execution and waits for user input to continue. It displays a message prompting the user to press the enter key to continue. If the end of the console window is reached, the function clears the message and moves the cursor up to the previous line. + + --- + ### Examples This example pauses the script execution and displays the message "Press any key to continue...". The function waits for the user to press a key before continuing. @@ -22,25 +32,46 @@ This example pauses the script execution and displays the message "Press any key Read-SpectrePause -Message "Press any key to continue..." ``` + --- + ### Parameters #### **Message** + The message to display to the user. The default message is "[]Press [[/] to continue[/]". + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |1 |false | + + #### **NoNewline** + Indicates whether to write a newline character before displaying the message. By default, a newline character is written. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + + + --- + ### Syntax ```powershell Read-SpectrePause [[-Message] ] [-NoNewline] [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreSelection.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreSelection.md index 025f9d83..19cbd9d4 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreSelection.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreSelection.md @@ -4,17 +4,27 @@ title: Read-SpectreSelection + + + + ### Synopsis Displays a selection prompt using Spectre Console. + + --- + ### Description This function displays a selection prompt using Spectre Console. The user can select an option from the list of choices provided. The function returns the selected option. + + --- + ### Examples This command displays a selection prompt with the title "Select your favorite color" and the choices "Red", "Green", and "Blue". The active selection is colored in green. @@ -22,48 +32,92 @@ This command displays a selection prompt with the title "Select your favorite co Read-SpectreSelection -Title "Select your favorite color" -Choices @("Red", "Green", "Blue") -Color "Green" ``` + --- + ### Parameters #### **Title** + The title of the selection prompt. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |1 |false | + + #### **Choices** + The list of choices to display in the selection prompt. ChoiceLabelProperty is required if the choices are complex objects rather than an array of strings. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Array]`|false |2 |false | + + #### **ChoiceLabelProperty** + If the object is complex then the property of the choice object to use as the label in the selection prompt is required. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |3 |false | + + #### **Color** + The color of the selected option in the selection prompt. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |4 |false | + + #### **PageSize** + The number of choices to display per page in the selection prompt. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |5 |false | + + + + --- + ### Syntax ```powershell Read-SpectreSelection [[-Title] ] [[-Choices] ] [[-ChoiceLabelProperty] ] [[-Color] ] [[-PageSize] ] [] -Read-SpectreSelection [[-Title] ] [[-Choices] ] [[-ChoiceLabelProperty] ] [[-Color] ] [[-PageSize] ] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreText.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreText.md index 3e1fa0ce..9a36371f 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreText.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Prompts/Read-SpectreText.md @@ -4,20 +4,30 @@ title: Read-SpectreText + + + + ### Synopsis Prompts 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. This means that you can't use the up and down arrow keys to navigate through your previous commands. ::: + + --- + ### Description This function uses Spectre Console to prompt the user with a question and returns the user's input. + + --- + ### Examples This will prompt the user with the question "What's your name?" and return the user's input. If the user does not provide any input, the function will return "Prefer not to say". @@ -30,49 +40,93 @@ This will prompt the user with the question "What's your favorite color?" and re Read-SpectreText -Question "What's your favorite color?" -AnswerColor "Cyan1" -Choices "Black", "Green","Magenta", "I'll never tell!" ``` + --- + ### Parameters #### **Question** + The question to prompt the user with. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |1 |false | + + #### **DefaultAnswer** + The default answer if the user does not provide any input. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |2 |false | + + #### **AnswerColor** + The color of the user's answer input. The default behaviour uses the standard terminal text color. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |3 |false | + + #### **AllowEmpty** + If specified, the user can provide an empty answer. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + #### **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. + + + + + |Type |Required|Position|PipelineInput| |------------|--------|--------|-------------| |`[String[]]`|false |4 |false | + + + + --- + ### Syntax ```powershell Read-SpectreText [[-Question] ] [[-DefaultAnswer] ] [[-AnswerColor] ] [-AllowEmpty] [[-Choices] ] [] -Read-SpectreText [[-Question] ] [[-DefaultAnswer] ] [[-AnswerColor] ] [-AllowEmpty] [[-Choices] ] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Get-SpectreEscapedText.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Get-SpectreEscapedText.md index ae794eb9..80f67ed3 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Get-SpectreEscapedText.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Get-SpectreEscapedText.md @@ -4,19 +4,29 @@ title: Get-SpectreEscapedText + + + + ### Synopsis Escapes text for use in Spectre Console. [ShaunLawrie/PwshSpectreConsole/issues/5](https://github.com/ShaunLawrie/PwshSpectreConsole/issues/5) + + --- + ### Description This function escapes text for use where Spectre Console accepts markup. It is intended to be used as a helper function for other functions that output text to the console using Spectre Console which contains special characters that need escaping. See [https://spectreconsole.net/markup](https://spectreconsole.net/markup) for more information about the markup language used in Spectre Console. + + --- + ### Examples This example shows some data that requires escaping being embedded in a string passed to Format-SpectrePanel. @@ -25,18 +35,31 @@ $data = "][[][]]][[][][][" Format-SpectrePanel -Title "Unescaped data" -Data "I want escaped $($data | Get-SpectreEscapedText) [yellow]and[/] [red]unescaped[/] data" ``` + --- + ### Parameters #### **Text** + The text to be escaped. + + + + + |Type |Required|Position|PipelineInput | |----------|--------|--------|--------------| |`[String]`|true |1 |true (ByValue)| + + + + --- + ### Syntax ```powershell Get-SpectreEscapedText [-Text] [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreCalendar.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreCalendar.md index 82c6c067..dd901325 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreCalendar.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreCalendar.md @@ -1,27 +1,41 @@ --- +sidebar: + badge: + text: New + variant: tip title: Write-SpectreCalendar --- + + + + ### Synopsis Writes a Spectre Console Calendar text to the console. + + --- + ### Description Writes a Spectre Console Calendar text to the console. + + --- + ### Examples -> EXAMPLE 1 +This example shows how to use the Write-SpectreCalendar function with an events table defined as a hashtable in the command. ```powershell Write-SpectreCalendar -Date 2024-07-01 -Events @{'2024-07-10' = 'Beach time!'; '2024-07-20' = 'Barbecue' } ``` -> EXAMPLE 2 +This example shows how to use the Write-SpectreCalendar function with an events table as an object argument. ```powershell $events = @{ @@ -31,37 +45,70 @@ $events = @{ Write-SpectreCalendar -Date 2024-01-01 -Events $events ``` + --- + ### Parameters #### **Date** + The date to display the calendar for. + + + + + |Type |Required|Position|PipelineInput| |------------|--------|--------|-------------| |`[DateTime]`|false |1 |false | + + #### **Alignment** + The alignment of the calendar. + + + Valid Values: * Left * Right * Center + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |2 |false | + + #### **Color** + The color of the calendar. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |3 |false | + + #### **Border** + The border of the calendar. + + + Valid Values: * Ascii @@ -83,34 +130,68 @@ Valid Values: * SimpleHeavy * Square + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |4 |false | + + #### **Culture** + The culture of the calendar. + + + + + |Type |Required|Position|PipelineInput| |---------------|--------|--------|-------------| |`[CultureInfo]`|false |5 |false | + + #### **Events** + The events to highlight on the calendar. Takes a hashtable with the date as the key and the event as the value. + + + + + |Type |Required|Position|PipelineInput| |-------------|--------|--------|-------------| |`[Hashtable]`|false |6 |false | + + #### **HideHeader** + Hides the header of the calendar. (Date) + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + + + --- + ### Syntax ```powershell Write-SpectreCalendar [[-Date] ] [[-Alignment] ] [[-Color] ] [[-Border] ] [[-Culture] ] [[-Events] ] [-HideHeader] [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreFigletText.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreFigletText.md index 69c981b1..c769b4b8 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreFigletText.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreFigletText.md @@ -4,23 +4,32 @@ title: Write-SpectreFigletText + + + + ### Synopsis Writes a Spectre Console Figlet text to the console. + + --- + ### Description This function writes a Spectre Console Figlet text to the console. The text can be aligned to the left, right, or center, and can be displayed in a specified color. + + --- + ### Examples Displays the text "Hello Spectre!" in the center of the console, in red color. ```powershell Write-SpectreFigletText -Text "Hello Spectre!" -Alignment "Center" -Color "Red" -Write-SpectreFigletText -Text "Hello Spectre!" -Alignment "Center" -Color "Red" ``` Displays the text "Woah!" using a custom figlet font. @@ -36,47 +45,86 @@ Write-SpectreFigletText -Text "Whoa?!" -FigletFontPath "C:\Users\shaun\Downloads ░░ ░░ ░░ ░░ ░░░░░░ ░░░░░░░░ ░░ ░░ ``` + --- + ### Parameters #### **Text** + The text to display in the Figlet format. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |1 |false | + + #### **Alignment** + The alignment of the text. The default value is "Left". + + + Valid Values: * Left * Right * Center + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |2 |false | + + #### **Color** + The color of the text. The default value is the accent color of the script. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |3 |false | + + #### **FigletFontPath** + The path to the Figlet font file to use. If this parameter is not specified, the default built-in Figlet font is used. The figlet font format is usually *.flf, see https://spectreconsole.net/widgets/figlet for more. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |4 |false | + + + + --- + ### Syntax ```powershell Write-SpectreFigletText [[-Text] ] [[-Alignment] ] [[-Color] ] [[-FigletFontPath] ] [] -Write-SpectreFigletText [[-Text] ] [[-Alignment] ] [[-Color] ] [[-FigletFontPath] ] [] ``` diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreHost.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreHost.md index c3233bf2..1ba9ee45 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreHost.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreHost.md @@ -5,19 +5,29 @@ description: The Write-SpectreHost function writes a message to the console usin + + + + ### Synopsis Writes a message to the console using Spectre Console markup. + + --- + ### Description The Write-SpectreHost function writes a message to the console using Spectre Console. It supports ANSI markup and can optionally append a newline character to the end of the message. The markup language is defined at [https://spectreconsole.net/markup](https://spectreconsole.net/markup) Supported emoji are defined at [https://spectreconsole.net/appendix/emojis](https://spectreconsole.net/appendix/emojis) + + --- + ### Examples This example writes the message "Hello, world!" to the console with the word world flashing blue with an underline followed by an emoji throwing a shaka. @@ -25,25 +35,46 @@ This example writes the message "Hello, world!" to the console with the word wor Write-SpectreHost -Message "Hello, [blue underline rapidblink]world[/]! :call_me_hand:" ``` + --- + ### Parameters #### **Message** + The message to write to the console. + + + + + |Type |Required|Position|PipelineInput | |----------|--------|--------|--------------| |`[String]`|true |1 |true (ByValue)| + + #### **NoNewline** + If specified, the message will not be followed by a newline character. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | + + + + --- + ### Syntax ```powershell Write-SpectreHost [-Message] [-NoNewline] [] diff --git a/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreRule.md b/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreRule.md index 8f499f70..b7cc9eb4 100644 --- a/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreRule.md +++ b/PwshSpectreConsole.Docs/src/content/docs/reference/Writing/Write-SpectreRule.md @@ -4,17 +4,27 @@ title: Write-SpectreRule + + + + ### Synopsis Writes a Spectre horizontal-rule to the console. + + --- + ### Description The Write-SpectreRule function writes a Spectre horizontal-rule to the console with the specified title, alignment, and color. + + --- + ### Examples This example writes a Spectre rule with the title "My Rule", centered alignment, and red color. @@ -22,39 +32,70 @@ This example writes a Spectre rule with the title "My Rule", centered alignment, Write-SpectreRule -Title "My Rule" -Alignment Center -Color Red ``` + --- + ### Parameters #### **Title** + The title of the rule. + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|true |1 |false | + + #### **Alignment** + The alignment of the text in the rule. The default value is Left. + + + Valid Values: * Left * Right * Center + + + + + |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[String]`|false |2 |false | + + #### **Color** + The color of the rule. The default value is the accent color of the script. + + + + + |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Color]`|false |3 |false | + + + + --- + ### Syntax ```powershell Write-SpectreRule [-Title] [[-Alignment] ] [[-Color] ] [] -Write-SpectreRule [-Title] [[-Alignment] ] [[-Color] ] [] ```