Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ShaunLawrie/PwshSyntaxHighlight
🌈 Render PowerShell in the Terminal with Syntax Highlighting
https://github.com/ShaunLawrie/PwshSyntaxHighlight
powershell powershell-module psgallery
Last synced: about 2 months ago
JSON representation
🌈 Render PowerShell in the Terminal with Syntax Highlighting
- Host: GitHub
- URL: https://github.com/ShaunLawrie/PwshSyntaxHighlight
- Owner: ShaunLawrie
- License: mit
- Created: 2023-05-20T04:23:20.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-05-25T10:57:49.000Z (over 1 year ago)
- Last Synced: 2024-08-01T21:56:52.077Z (5 months ago)
- Topics: powershell, powershell-module, psgallery
- Language: PowerShell
- Homepage: https://shaunlawrie.com/
- Size: 130 KB
- Stars: 36
- Watchers: 3
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# 🌈 PwshSyntaxHighlight
[](https://www.powershellgallery.com/packages/PwshSyntaxHighlight)
[](https://www.powershellgallery.com/packages/PwshSyntaxHighlight)
[](https://github.com/ShaunLawrie/PwshSyntaxHighlight/blob/main/LICENSE)
PwshSyntaxHighlight is a simple syntax highlighter for rendering PowerShell code blocks inside the terminal. This is a standalone version of the codeblock renderer I built for [PowerShell AI](https://github.com/dfinke/PowerShellAI).
# Install
```pwsh
Install-Module PwshSyntaxHighlight -Scope CurrentUser
```
# Usage
## 1. Generate Sample Code
Create some sample code to use in the examples below using a multi-line string variable like this.
```pwsh
$sampleCode = @'
function Test-ThisThingOut {
param (
[string] $Parameter
)
$message = "$Parameter is the parameter"
Write-Host "Hello PwshSyntaxHighlight! $message"
}
'@
```
## 2. Render Code Blocks
Pass the code as the `-Text` parameter to render a code block, use `-SyntaxHighlight` to enable highlighting and `-ShowLineNumbers` to show a gutter down the left containing the code line numbers.
```pwsh
Write-CodeBlock -Text $sampleCode -SyntaxHighlight -ShowLineNumbers
```
## 3. Use Themes
There are only two basic themes available at the moment, GitHub (default) and Matrix, if you're interested you could open a PR for more.
```pwsh
Write-CodeBlock -Text $sampleCode -SyntaxHighlight -ShowLineNumbers -Theme Matrix
```
## 4. Highlight Specific Lines
```pwsh
# Provide a list of lines to highlight to draw attention to them with -HighlightLines
Write-CodeBlock $sampleCode -HighlightLines 2, 3, 4 -ShowLineNumbers
```
## 5. Highlight Extents
By passing a collection of Extents into `Write-CodeBlock` you can have the extents highlighted in the rendered code. This is how errors are highlighted in the [PowerShell AI Function Builder demo on YouTube](https://youtu.be/MbHTrVdTJXE).
Parsing PowerShell code with the built-in Abstract Syntax Tree is too much for me to document here but you can check out the awesome details available at [powershell.one/powershell-internals/parsing-and-tokenization/abstract-syntax-tree](https://powershell.one/powershell-internals/parsing-and-tokenization/abstract-syntax-tree) if you're interested.
```pwsh
# Create a script block from the sample code
$scriptBlock = [ScriptBlock]::Create($sampleCode)
# Get a list of items from the abstract syntax tree that are double quoted strings
$astItems = $scriptBlock.Ast.FindAll({$args[0].StringConstantType -eq "DoubleQuoted"}, $true)
# Get the extents for all of those double quoted strings
$extents = $astItems | Select-Object -ExpandProperty Extent
$sampleCode | Write-CodeBlock -HighlightExtents $extents -ShowLineNumbers
```
## 6. Export Screenshots as PNG (Windows Only)
[@I_Am_Jakoby](https://twitter.com/I_Am_Jakoby/status/1660673439705837570) added the ability to take screenshots when this is run from a Windows based terminal 🤙
Use `-ClearHost` and `-ScreenShot` to clear the host, and save an image of the terminal window.
```pwsh
Write-CodeBlock $sampleCode -SyntaxHighlight -ShowLineNumbers -ClearHost -ScreenShot
```
The screenshot will include the window border and look a bit like this:
## 7. Export Screenshots as HTML (Windows Only)
Another [@I_Am_Jakoby](https://twitter.com/I_Am_Jakoby) special 🙏
Use `-Html` to save the code block as an html document.
```pwsh
Write-CodeBlock $sampleCode -SyntaxHighlight -ShowLineNumbers -Html
```
The command will save an HTML file you can open in your browser:
*The colors don't match what you see in the terminal which will be corrected with https://github.com/ShaunLawrie/PwshSyntaxHighlight/issues/2*