DOCSEARCHbyAlgolia
Submit Docs

PSReadLine Documentation

repository·master·Indexed 26 days ago

https://github.com/powershell/psreadline

A PowerShell module that replaces the standard command-line editing experience. It provides syntax coloring, customizable key bindings (Emacs/Cmd modes), intelligent history search, and multi-line editing. Includes guidance on installation via Install-Module, configuration using Set-PSReadLineOption and Set-PSReadLineKeyHandler, and creating custom key bindings with ScriptBlocks using the [Microsoft.PowerShell.PSConsoleReadLine] class.

Tokens
1.2K
Snippets
1
Records
4
Agent score
38%

What's inside PSReadLine

  1. Build PSReadLine from source

    master

    To build PSReadLine on Windows, Linux, or macOS, you need .NET 6.0 (or newer) and the PowerShell modules InvokeBuild and platyPS installed.

    Use the build.ps1 script to manage the build process:

    • Bootstrap: ./build.ps1 -Bootstrap
    • Build (Debug): ./build.ps1 -Configuration Debug
    • Test (.NET 6.0): ./build.ps1 -Test -Configuration Debug -Framework net6.0
    • Test (.NET 4.7.2, Windows only): ./build.ps1 -Test -Configuration Debug -Framework net472

    Artifacts are located in <repo-root>/bin/Debug.

    To test your local build without interference:

    1. Start a new session: pwsh -NonInteractive -NoProfile
    2. Import your local module: Import-Module <path-to-your-build>/PSReadLine/PSReadLine.psd1

  2. Configure PSReadLine Edit Modes and Key Bindings

    master

    You can change the command line editing experience using Set-PSReadLineOption and Set-PSReadLineKeyHandler.

    • Set Edit Mode: Use Set-PSReadLineOption -EditMode Emacs to enable Emacs key bindings.
    • View Bindings: Use Get-PSReadLineKeyHandler to see current key bindings.
    • Custom Key Bindings: Use Set-PSReadLineKeyHandler to map keys to specific functions. For example, you can make the arrow keys perform history searches based on the text currently typed.

  3. Install or upgrade PSReadLine

    master

    To install or upgrade to the latest stable version of PSReadLine, use Install-Module.

    Note for Windows PowerShell 5.1 users: You must first upgrade PowerShellGet to version 1.6.0 or higher from an elevated session to support installing prerelease modules.

    To install the latest stable version:

    Install-Module PSReadLine -Repository PSGallery -Scope CurrentUser -Force

    To install the latest prerelease version (contains newer features and bug fixes but may be less stable):

    Install-Module PSReadLine -Repository PSGallery -Scope CurrentUser -AllowPrerelease -Force

  4. Create custom key bindings with ScriptBlocks

    master

    You can implement complex logic for key bindings using the -ScriptBlock parameter in Set-PSReadLineKeyHandler. This allows you to manipulate the command line buffer directly using the [Microsoft.PowerShell.PSConsoleReadLine] class.

    Commonly used methods for custom handlers include:

    • [Microsoft.PowerShell.PSConsoleReadLine]::GetBufferState([ref]$line, [ref]$cursor)
    • [Microsoft.PowerShell.PSConsoleReadLine]::Insert($string)
    • [Microsoft.PowerShell.PSConsoleReadLine]::Replace($string)
    • [Microsoft.PowerShell.PSConsoleReadLine]::SetCursorPosition($position)
    # Example: Smart Quote Insertion
# Inserts a pair of quotes and places the cursor between them, 
# or moves the cursor past the existing quote if it matches.
Set-PSReadLineKeyHandler -Chord '"' "'" `
                         -BriefDescription SmartInsertQuote `
                         -LongDescription "Insert paired quotes if not already on a quote" `
                         -ScriptBlock {
    param($key, $arg)

    $line = $null
    $cursor = $null
    [Microsoft.PowerShell.PSConsoleReadLine]::GetBufferState([ref]$line, [ref]$cursor)

    if ($line.Length -gt $cursor -and $line[$cursor] -eq $key.KeyChar) {
        # Just move the cursor
        [Microsoft.PowerShell.PSConsoleReadLine]::SetCursorPosition($cursor + 1)
    }
    else {
        # Insert matching quotes, move cursor to be in between the quotes
        [Microsoft.PowerShell.PSConsoleReadLine]::Insert("$($key.KeyChar)" * 2)
        [Microsoft.PowerShell.PSConsoleReadLine]::GetBufferState([ref]$line, [ref]$cursor)
        [Microsoft.PowerShell.PSConsoleReadLine]::SetCursorPosition($cursor - 1)
    }
}