en-US/about_PSReadline.help.txt
|
TOPIC
about_PSReadline SHORT DESCRIPTION PSReadline provides an improved command line editing experience in the PowerShell console. LONG DESCRIPTION PSReadline provides a powerful command line editing experience for the PowerShell console. It provides: * Syntax coloring of the command line * A visual indication of syntax errors * A better multi-line experience (both editing and history) * Customizable key bindings * Cmd and Emacs modes * Many configuration options * Bash style completion (optional in Cmd mode, default in Emacs mode) * Emacs yank/kill ring * PowerShell token based "word" movement and kill The following functions are available in the class [PSConsoleUtilities.PSConsoleReadLine]: Cursor movement --------------- EndOfLine (Cmd: <End> Emacs: <End> or <Ctrl+E>) Move the cursor to the end of the input. BeginningOfLine (Cmd: <Home> Emacs: <Home> or <Ctrl+A>) Move the cursor to the start of the input. ForwardChar (Cmd: <RightArrow> Emacs: <RightArrow> or <Ctrl+F>) Move the cursor one character to the right. This may move the cursor to the next line of multi-line input. BackwardChar (Cmd: <LeftArrow> Emacs: <LeftArrow> or <Ctrl+B>) Move the cursor one character to the left. This may move the cursor to the previous line of multi-line input. ForwardWord (Cmd: unbound Emacs: <Alt+F>) Move the cursor forward to the end of the current word, or if between words, to the end of the next word. Word delimiter characters can be set with: Set-PSReadlineOption -WordDelimiters <string of delimiter characters> NextWord (Cmd: <Ctrl+RightArrow> Emacs: unbound) Move the cursor forward to the start of the next word. Word delimiter characters can be set with: Set-PSReadlineOption -WordDelimiters <string of delimiter characters> BackwardWord (Cmd: <Ctrl+LeftArrow> Emacs: <Alt+B>) Move the cursor back to the start of the current word, or if between words, the start of the previous word. Word delimiter characters can be set with: Set-PSReadlineOption -WordDelimiters <string of delimiter characters> ShellForwardWord (Cmd: unbound Emacs: unbound) Like ForwardWord except word boundaries are defined by PowerShell token boundaries. ShellNextWord (Cmd: unbound Emacs: unbound) Like NextWord except word boundaries are defined by PowerShell token boundaries. ShellBackwardWord (Cmd: unbound Emacs: unbound) Like BackardWord except word boundaries are defined by PowerShell token boundaries. GotoBrace (Cmd: <Ctrl+}> Emacs: unbound) Go to the matching parenthesis, curly brace, or square bracket. AddLine (Cmd: <Shift-Enter> Emacs: <Shift-Enter>) The continuation prompt is displayed on the next line and PSReadline waits for keys to edit the current input. This is useful to enter multi-line input as a single command even when a single line is complete input by itself. Basic editing ------------- CancelLine (Cmd: unbound Emacs: unbound) Cancel all editing to the line, leave the line of input on the screen but return from PSReadline without executing the input. RevertLine (Cmd: <ESC> Emacs: <Alt+R>) Reverts all of the input since the last input was accepted and executed. This is equivalent to doing Undo until there is nothing left to undo. BackwardDeleteChar (Cmd: <Backspace> Emacs: <Backspace> or <Ctrl+H>) Delete the character before the cursor. DeleteChar (Cmd: <Delete> Emacs: <Delete>) Delete the character under the cursor. AcceptLine (Cmd: <Enter> Emacs: <Enter> or <Ctrl+M>) Attempt to execute the current input. If the current input is incomplete (for example there is a missing closing parenthesis, bracket, or quote, then the continuation prompt is displayed on the next line and PSReadline waits for keys to edit the current input. AcceptAndGetNext (Cmd: unbound Emacs: <Ctrl+O> Like AcceptLine, but after the line completes, start editing the next line from history. BackwardDeleteLine (Cmd: <Ctrl+Home> Emacs: unbound) Delete the text from the start of the input to the cursor. ForwardDeleteLine (Cmd: <Ctrl+End> Emacs: unbound) Delete the text from the cursor to the end of the input. SelectBackwardChar (Cmd: <Shift+LeftArrow> Emacs: <Shift+LeftArrow>) Adjust the current selection to include the previous character. SelectForwardChar (Cmd: <Shift+RightArrow> Emacs: <Shift+RightArrow>) Adjust the current selection to include the next character. SelectBackwardWord (Cmd: <Shift+Ctrl+LeftArrow> Emacs: <Alt+Shift+B>) Adjust the current selection to include the previous word. SelectForwardWord (Cmd: unbound Emacs: <Alt+Shift+F>) Adjust the current selection to include the next word using ForwardWord. SelectNextWord (Cmd: <Shift+Ctrl+RightArrow> Emacs: unbound) Adjust the current selection to include the next word using NextWord. SelectShellForwardWord (Cmd: unbound Emacs: unbound) Adjust the current selection to include the next word using ShellForwardWord. SelectShellNextWord (Cmd: unbound Emacs: unbound) Adjust the current selection to include the next word using ShellNextWord. SelectShellBackwardWord (Cmd: unbound Emacs: unbound) Adjust the current selection to include the previous word using ShellBackwardWord. SelectBackwardsLine (Cmd: <Shift+Home> Emacs: <Shift+Home>) Adjust the current selection to include from the cursor to the start of the line. SelectLine (Cmd: <Shift+End> Emacs: <Shift+End>) Adjust the current selection to include from the cursor to the end of the line. SelectAll (Cmd: <Ctrl+A> Emacs: unbound) Select the entire line. Moves the cursor to the end of the line. SelfInsert (Cmd: <a>, <b>, ... Emacs: <a>, <b>, ...) Insert the key entered. Redo (Cmd: <Ctrl+Y> Emacs: unbound) Redo an insertion or deletion that was undone by Undo. Undo (Cmd: <Ctrl+Z> Emacs: <Ctrl+_>) Undo a previous insertion or deletion. History ------- ClearHistory (Cmd: unbound Emacs: unbound) Clears history in PSReadline. This does not affect PowerShell history. PreviousHistory (Cmd: <UpArrow> Emacs: <UpArrow>) Replace the current input with the 'previous' item from PSReadline history. NextHistory (Cmd: <DownArrow> Emacs: <DownArrow>) Replace the current input with the 'next' item from PSReadline history. ForwardSearchHistory (Cmd: <Ctrl+S> Emacs: <Ctrl+S>) Search forward from the current history line interactively. ReverseSearchHistory (Cmd: <Ctrl+R> Emacs: <Ctrl+R>) Search backward from the current history line interactively. HistorySearchBackward (Cmd: unbound Emacs: unbound) Replace the current input with the 'previous' item from PSReadline history that matches the characters between the start and the input and the cursor. HistorySearchForward (Cmd: unbound Emacs: unbound) Replace the current input with the 'next' item from PSReadline history that matches the characters between the start and the input and the cursor. BeginningOfHistory (Cmd: unbound Emacs: <Alt+<>) Replace the current input with the last item from PSReadline history. EndOfHistory (Cmd: unbound Emacs: <Alt+>>) Replace the current input with the last item in PSReadline history, which is the possibly empty input that was entered before any history commands. Tab Completion -------------- TabCompleteNext (Cmd: <Tab> Emacs: unbound) Attempt to complete the text surrounding the cursor with the next available completion. TabCompletePrevious (Cmd: <Shift-Tab> Emacs: unbound) Attempt to complete the text surrounding the cursor with the next previous completion. Complete (Cmd: unbound Emacs: <Tab>) Attempt to perform completion on the text surrounding the cursor. If there are multiple possible completions, the longest unambiguous prefix is used for completion. If trying to complete the longest unambiguous completion, a list of possible completions is displayed. MenuComplete (Cmd: unbound Emacs: unbound) Attempt to perform completion on the text surrounding the cursor. If there are multiple possible completions, a list of possible completions is displayed and you can select the correct completion using the arrow keys or Tab/Shift+Tab. Escape and Ctrl+G cancel the menu selection and reverts the line to the state before invoking MenuComplete. PossibleCompletions (Cmd: <Ctrl+Space> Emacs: <Alt+Equals>) Display the list of possible completions. SetMark (Cmd: unbound Emacs: <Alt+Space>) Mark the current loction of the cursor for use in a subsequent editing command. ExchangePointAndMark (Cmd: unbound Emacs: <Ctrl+X,Ctrl+X>) The cursor is placed at the location of the mark and the mark is moved to the location of the cursor. Kill/Yank --------- Kill and yank operate on a clipboard in the PSReadline module. There is a ring buffer called the kill ring - killed text will be added to the kill ring up and yank will copy text from the most recent kill. YankPop will cycle through items in the kill ring. When the kill ring is full, new items will replace the oldest items. A kill operation that is immediately preceded by another kill operation will append the previous kill instead of adding a new item or replacing an item in the kill ring. This is how you can cut a part of a line, say for example with multiple KillWord operations, then yank them back elsewhere as a single yank. KillLine (Cmd: unbound Emacs: <Ctrl+K>) Clear the input from the cursor to the end of the line. The cleared text is placed in the kill ring. BackwardKillLine (Cmd: unbound Emacs: <Ctrl+U> or <Ctrl+X,Backspace>) Clear the input from the start of the input to the cursor. The cleared text is placed in the kill ring. KillWord (Cmd: unbound Emacs: <Alt+D>) Clear the input from the cursor to the end of the current word. If the cursor is between words, the input is cleared from the cursor to the end of the next word. The cleared text is placed in the kill ring. BackwardKillWord (Cmd: unbound Emacs: <Alt+Backspace>) Clear the input from the start of the current word to the cursor. If the cursor is between words, the input is cleared from the start of the previous word to the cursor. The cleared text is placed in the kill ring. ShellKillWord (Cmd: unbound Emacs: unbound) Like KillWord except word boundaries are defined by PowerShell token boundaries. ShellBackwardKillWord (Cmd: unbound Emacs: unbound) Like BackwardKillWord except word boundaries are defined by PowerShell token boundaries. UnixWordRubout (Cmd: unbound Emacs: <Ctrl+W>) Like BackwardKillWord except word boundaries are defined by whitespace. KillRegion (Cmd: unbound Emacs: unbound) Kill the text between the cursor and the mark. Copy (Cmd: <Ctrl+Shift+C> Emacs: unbound) Copy selected region to the system clipboard. If no region is selected, copy the whole line. CopyOrCancelLine (Cmd: <Ctrl+C> Emacs: <Ctrl+C>) Either copy selected text to the clipboard, or if no text is selected, cancel editing the line with CancelLine. Cut (Cmd: <Ctrl+X> Emacs: unbound) Delete selected region placing deleted text in the system clipboard. Yank (Cmd: unbound Emacs: <Ctrl+Y>) Add the most recently killed text to the input. YankPop (Cmd: unbound Emacs: <Alt+Y>) If the previous operation was Yank or YankPop, replace the previously yanked text with the next killed text from the kill ring. ClearKillRing (Cmd: unbound Emacs: unbound) The contents of the kill ring are cleared. Paste (Cmd: <Ctrl+V> Emacs: unbound) This is similar to Yank, but uses the system clipboard instead of the kill ring. YankLastArg (Cmd: unbound Emacs: <Alt+.>, <Alt+_>) Insert the last argument from the previous command in history. Repeated operations will replace the last inserted argument with the last argument from the previous command (so Alt+. Alt+. will insert the last argument of the second to last history line.) With an argument, the first time YankLastArg behaves like YankNthArg. A negative argument on subsequent YankLastArg calls will change the direction while going through history. For example, if you hit Alt+. one too many times, you can type Alt+- Alt+. to reverse the direction. Arguments are based on PowerShell tokens. YankNthArg (Cmd: unbound Emacs: <Alt+Ctrl+Y>) Insert the first argument (not the command name) of the previous command in history. With an argument, insert the nth argument where 0 is typically the command. Negative arguments start from the end. Arguments are based on PowerShell tokens. Miscellaneous ------------- Abort (Cmd: unbound Emacs: <Ctrl+G>) Abort the current action, e.g. stop interactive history search. Does not cancel input like CancelLine. CharacterSearch (Cmd: <F3> Emacs: <Ctrl+]>) Read a key and search forwards for that character. With an argument, search forwards for the nth occurance of that argument. With a negative argument, searches backwards. CharacterSearchBackward (Cmd: <Shift+F3> Emacs: <Alt+Ctrl+]>) Like CharacterSearch, but searches backwards. With a negative argument, searches forwards. ClearScreen (Cmd: <Ctrl+L> Emacs: <Ctrl+L>) Clears the screen and displays the current prompt and input at the top of the screen. DigitArgument (Cmd: unbound Emacs: <Alt+[0..9]>,,<Alt+->) Used to pass numeric arguments to functions like CharacterSearch or YankNthArg. Alt+- toggles the argument to be negative/non-negative. To enter 80 '*' characters, you could type Alt+8 Alt+0 *. CaptureScreen (Cmd: unbound Emacs: unbound) Copies selected lines to the clipboard in both text and rtf formats. Use up/down arrow keys to the first line to select, then Shift+UpArrow/Shift+DownArrow to select multiple lines. After selecting, press Enter to copy the text. Escape/Ctrl+C/Ctrl+G will cancel so nothing is copied to the clipboard. DisableDemoMode (Cmd: unbound Emacs: unbound) Turn off demo mode. EnableDemoMode (Cmd: unbound Emacs: unbound) Turn on demo mode. Displays a window below the input line that shows which keys are typed. InvokePrompt (Cmd: unbound Emacs: unbound) Erases the current prompt and calls the prompt function to redisplay the prompt. Useful for custom key handlers that change state, e.g. change the current directory. WhatIsKey (Cmd: <Alt+?> Emacs: <Alt+?>) Read a key or chord and display the key binding. ShowKeyBindings (Cmd: <Ctrl+Alt+?> Emacs: <Ctrl+Alt+?>) Show all of the currently bound keys. ScrollDisplayUp (Cmd: <PageUp> Emacs: <PageUp>) Scroll the display up one screen. ScrollDisplayDown (Cmd: <PageDown> Emacs: <PageDown>) Scroll the display down one screen. ScrollDisplayTop (Cmd: unbound Emacs: <Ctrl+Home>) Scroll the display to the top. ScrollDisplayToCursor (Cmd: unbound Emacs: <Ctrl+End>) Scroll the display to the cursor. Custom Key Binding Support -------------------------- The following functions are public but cannot be directly bound to a key. They are used in custom key bindings. Ding Perform the Ding action based on the users perference. GetBufferState(out string input, out int cursor) GetBufferState(out Ast ast, out Token[] tokens, out ParseError[] parseErrors, out int cursor) These two functions retrieve useful information about the current state of the input buffer. The first is more commonly used for simple cases. The second is used if your binding is doing something more advanced with the Ast. Insert(char c) Insert(string s) Insert a character or string in a way that supports undo/redo. Replace(int start, int length, string replacement) Replace some of the input in a way that supports undo/redo as a single action. This is preferred over Delete followed by Insert to better support Undo. SetCursorPosition(int offset) Move the cursor to the given offset. Cursor movement is not tracked for undo. Custom Key Bindings ------------------- PSReadline supports custom key bindings using the cmdlet Set-PSReadlineKeyHandler. Most custom key bindings will call one of the above functions, for example: Set-PSReadlineKeyHandler -Key UpArrow -Function HistorySearchBackward You can bind a ScriptBlock to a key. This ScriptBlock can do pretty much anything you like. For example, say you wanted to run a specific command after hitting Ctrl+B, you could do this: Set-PSReadlineKeyHandler -Key Ctrl+B -BriefDescription build -LongDescription "Build the current directory" -ScriptBlock { [PSConsoleUtilities.PSConsoleReadLine]::RevertLine() [PSConsoleUtilities.PSConsoleReadLine]::Insert("build") [PSConsoleUtilities.PSConsoleReadLine]::AcceptLine() } In this example, multiple functions are called and the end result is running the 'build' command by entering Ctrl+B. POWERSHELL COMPATIBILITY PSReadline requires PowerShell version 3 or greater and the console host. It will not work in the ISE. FEEDBACK https://github.com/lzybkr/PSReadline CONTRIBUTING TO PSREADLINE Feel free to submit a pull request or submit feedback on the github page. SEE ALSO PSReadline is heavily influenced by the GNU Readline library: http://tiswww.case.edu/php/chet/readline/rltop.html |