-
Notifications
You must be signed in to change notification settings - Fork 129
Predictive IntelliSense #262
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
bafe2b2
bdd3ee9
dd58c11
d3ed694
5fd9c69
3dd0560
a7d6a75
6faa7dc
c454366
fb60588
f4edfcd
a6329e7
0641bb2
8dabf42
35ed896
5cf273d
07af6d2
da03165
8cdd56a
1bc65b1
6de0c3e
697327c
d6f6af4
889cad4
9439d35
51ec0f2
1f272cd
a58d4e8
800f653
ea14fcd
46b2382
b2f46ca
0cef8c3
ec0b745
493a3a7
8d0498e
34a3a62
3493c6b
04559ed
eaecab0
a97cbfe
0cfab18
07807c7
e6cf938
69f695c
6c8bcf3
20213c7
3994b0b
fee045f
872336a
be78ebd
6c6b8df
1d36316
24ad89b
a4df14c
539898d
78fb15f
2c33c3a
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
@@ -0,0 +1,347 @@ | ||||||||||
--- | ||||||||||
RFC: RFCXXXX | ||||||||||
Author: Jason Helmick | ||||||||||
Status: Draft | ||||||||||
Area: Shell | ||||||||||
Comments Due: 10/31/2020 | ||||||||||
--- | ||||||||||
|
||||||||||
# Motivation | ||||||||||
|
||||||||||
Tab completion has accelerated the success of both new and experienced PowerShell users. New users | ||||||||||
get the benefit of discovery; seeing available cmdlets and parameters as options while interactively | ||||||||||
typing. Experienced users receive the benefit of acceleration; typing less while using the **<tab>** key | ||||||||||
to quickly complete a command. | ||||||||||
|
||||||||||
The increasing amount of technology translates to an increase in cmdlets and full command | ||||||||||
complexity. Predictive IntelliSense is an addition to the concept of Tab Completion to assist the | ||||||||||
user in successfully completing full commands. | ||||||||||
|
||||||||||
## Predictive IntelliSense | ||||||||||
|
||||||||||
The prediction suggestion appears as colored text following the user’s cursor. This enables new and | ||||||||||
experienced users of PowerShell to discover, edit, and execute full commands based on matching | ||||||||||
predictions from the user’s history or additional providers. | ||||||||||
|
||||||||||
Additional providers enhance historic predictions by providing domain specific commands and task | ||||||||||
completions. Predictive IntelliSense includes an extension model to support the registration of | ||||||||||
additional providers. | ||||||||||
|
||||||||||
Predictions may be displayed in either **InlineView** or **ListView** depending on the user’s | ||||||||||
preference. Below, predictions are displayed with InlineView. | ||||||||||
|
||||||||||
 | ||||||||||
|
||||||||||
Below, predictions are displayed with a dropdown in ListView. | ||||||||||
|
||||||||||
 | ||||||||||
|
||||||||||
## Release plan | ||||||||||
|
||||||||||
Predictive IntelliSense is implemented in both the PowerShell engine and presented through the | ||||||||||
PSReadLine module. In an effort to support the most PowerShell users, the presentation of | ||||||||||
history-based predictions will be available to the following versions: | ||||||||||
|
||||||||||
- Windows Powershell 5.1 | ||||||||||
- PowerShell 7.0+ | ||||||||||
|
||||||||||
Additional plugins require the the extension framework implemented in the PowerShell engine. Support | ||||||||||
for additional plugins is available in the following versions: | ||||||||||
|
||||||||||
- PowerShell 7.1+ | ||||||||||
|
||||||||||
History-based predictions preview and ship plan: | ||||||||||
|
||||||||||
- PSReadLine 2.1.0-beta2 currently available for download from PSGallery | ||||||||||
- PSReadLine 2.1.0-GA will ship with PowerShell 7.1 | ||||||||||
- PSReadLine 2.1.0-GA will be available for download from PSGallery | ||||||||||
- History based prediction in the **InlineView** | ||||||||||
|
||||||||||
Extension/Plugin support preview and ship plan: | ||||||||||
|
||||||||||
- PSReadLine 2.2.0-beta1 planned availability in October | ||||||||||
- PSReadLine 2.2.0-GA will ship with PowerShell 7.2 | ||||||||||
- PSReadLine 2.2.0-GA will be available for download from PSGallery | ||||||||||
- Includes support for **InlineView** and **ListView** | ||||||||||
- Includes support for additional prediction source **Plugin** and **HistoryAndPlugin** | ||||||||||
- Note: Windows PowerShell 5.1 and PowerShell 7.0 will only support prediction source **History**. | ||||||||||
PowerShell 7.1+ will support prediction sources **History**, **Plugin**, and **HistoryAndPlugin** | ||||||||||
|
||||||||||
## Goals/Non-Goals | ||||||||||
|
||||||||||
Goals: | ||||||||||
|
||||||||||
- Provide suggestions from PSReadLine history | ||||||||||
- The user will be able to enable and disable Predictive IntelliSense | ||||||||||
- The user will be able to change between InlineView and ListView | ||||||||||
- The user will have keyboard shortcuts to navigate and edit a prediction | ||||||||||
- The user will be able to register additional providers when desired | ||||||||||
- The user may customize the color of a prediction to support accessibility needs | ||||||||||
|
||||||||||
Non-goals: | ||||||||||
|
||||||||||
- Due to the relatively short length of a session compared to your PSReadline history, | ||||||||||
PowerShell session history is not part of the historical suggestion | ||||||||||
- The extension framework doesn't allow a plugin implementation to call into the Runspace where | ||||||||||
PSReadLine is running when providing predictive suggestions. | ||||||||||
- VSCode implementation. We agree this is important for a consistent experience and are working to | ||||||||||
bring this feature in a future release, but the user experience for VS Code is outside the scope of this RFC. | ||||||||||
|
||||||||||
## Specification | ||||||||||
|
||||||||||
The proposal is to add Predictive IntelliSense and an extension model to improve the user | ||||||||||
interactive experience. | ||||||||||
|
||||||||||
### Key Design Considerations Predictive IntelliSense | ||||||||||
|
||||||||||
Predictive IntelliSense displays the most recent match command completion from command history. The | ||||||||||
prediction may change if a better match is found as the user types additional information. The | ||||||||||
predicted command may be accepted, edited, or ignored. | ||||||||||
|
||||||||||
 | ||||||||||
|
||||||||||
### Install and Remove Predictive IntelliSense | ||||||||||
|
||||||||||
Predictive IntelliSense is implemented in both the PowerShell engine and presented through the | ||||||||||
PSReadLine module. To receive the benefits of Predictive IntelliSense based on your PowerShell | ||||||||||
version, download and install the PSReadLine module from PSGallery | ||||||||||
|
||||||||||
theJasonHelmick marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
The current release is PSReadLine 2.1.0 Beta 2: | ||||||||||
|
||||||||||
```powershell | ||||||||||
Install-Module PSReadLine -RequiredVersion 2.1.0-beta2 -AllowPrerelease | ||||||||||
daxian-dbw marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
``` | ||||||||||
|
||||||||||
It is possible to unload or uninstall the PSReadLine module to disable Predictive IntelliSense. This | ||||||||||
creates a negative impact to customers as it would remove all features of PSReadLine. For this | ||||||||||
reason, Predictive IntelliSense has its own PSReadLine configuration to enable and disable | ||||||||||
predictions. | ||||||||||
|
||||||||||
### Enabling and Disabling Predictions | ||||||||||
|
||||||||||
By default, the feature Predictive IntelliSense is disabled. The impact of enabling this feature by | ||||||||||
theJasonHelmick marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
default may cause new and existing users to become confused at the shell prompt. The feature is | ||||||||||
enabled and disabled with a PSReadLine command Set-PSReadLineOption that is executed at the shell | ||||||||||
prompt or in the user’s Profile. | ||||||||||
|
||||||||||
Predictive IntelliSense in PSReadLine 2.1.0-beta2 currently supports the following arguments for | ||||||||||
prediction source; | ||||||||||
|
||||||||||
- None - This option disables Predictive IntelliSense | ||||||||||
- History - This option uses only the PSReadLine history for predictions | ||||||||||
|
||||||||||
Starting with PSReadLine 2.2.0-beta1, Predictive IntelliSense will support the following arguments | ||||||||||
for prediction source; | ||||||||||
|
||||||||||
- None - This option disables Predictive IntelliSense | ||||||||||
- History - This option uses only the PSReadLine history for predictions | ||||||||||
- Plugin – This option uses only registered plugin modules for predictions | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Sounds like we removed this one |
||||||||||
- HistoryAndPlugin – This option uses both for predictions | ||||||||||
|
||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I mentioned this in separate comment but will add here as well. It would be better to separate out Prediction from Source so that we can use History completion in Most Recently Used order rather than a predictive algorithm. Prediction Method Examples:
I guess source can be singular or additive so an array:
Is the plugin able to register itself to be accepted into the configuration list? I may want to try 3-4 different sources but end up with 1-2 as my defaults. Maybe have the 3rd-4th for specialized work on remote environments. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We should consider using There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @daxian-dbw Thoughts on using frecency algorithm versus Most Recent? I find myself expecting frequency. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The |
||||||||||
To enable Predictive IntelliSense, enter the following command in the shell or in the users Profile: | ||||||||||
|
||||||||||
```powershell | ||||||||||
Set-PSReadLineOption -PredictionSource History | ||||||||||
``` | ||||||||||
|
||||||||||
To disable Predictive IntelliSense, enter the following command in the shell or in the users Profile: | ||||||||||
|
||||||||||
```powershell | ||||||||||
Set-PSReadLineOption -PredictionSource None | ||||||||||
``` | ||||||||||
|
||||||||||
### Changing the Prediction View | ||||||||||
|
||||||||||
Beginning with 2.2.0-beta1, Predictions are displayed in one of two views depending on the user | ||||||||||
preference. The default view is InlineView. | ||||||||||
|
||||||||||
- InlineView – This is the default view and displays the prediction inline with the user’s typing. | ||||||||||
This view is similar to other shells Fish and ZSH. | ||||||||||
- ListView – ListView provides a dropdown list of predictions below the line the user is typing. | ||||||||||
Users may quickly scan the list, highlight and select the desired prediction. | ||||||||||
|
||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should be an option for InlineView alongside a secondary view. Inline and List complement each other. Inline can show the suggested completion with List showing multiple options at once. Additional Views to consider are
These additional views make me think Inline should be separate On/Off with additional views as a separate configuration with None only affecting what's in its list and not Inline setting. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @dragonwolf83 Thank you! We are open to considering additional views as we progress. I agree that InlineView and ListView can be complimentary - currently when using ListView, as you highlight selections, they are displayed fully on the same line as your cursor, similar to InlineView. Appreciate your thoughts and feedback as we move forward. |
||||||||||
Users may change the view at the command line using the keybinding F2 or `Set-PSReadLineOption. The | ||||||||||
Set-PSReadLineOption may be stored in the user's profile. | ||||||||||
Comment on lines
+163
to
+164
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
|
||||||||||
```powershell | ||||||||||
Set-PSReadLineOption -PredictionViewStyle ListView | ||||||||||
``` | ||||||||||
|
||||||||||
### Change the Prediction Color for Accessibility | ||||||||||
|
||||||||||
By default, predictions appear on the same line the user is typing in a different customizable | ||||||||||
color. To support accessibility needs, the prediction color is settable in the shell or user's | ||||||||||
profile. | ||||||||||
|
||||||||||
The default light-grey prediction text color; | ||||||||||
|
||||||||||
```powershell | ||||||||||
Set-PSReadLineOption -Colors @{ InLinePrediction = "$([char]0x1b)[38;5;238m"} | ||||||||||
``` | ||||||||||
|
||||||||||
Starting with PSReadLine 2.1.0-RC1, `Set-PSReadLineOption -Colors` array will include | ||||||||||
**InLinePrediction** to set the color of predictive text for **InLineView**. | ||||||||||
|
||||||||||
Beginning with PSReadLine 2.2.0-beta1, `Set-PSReadLineOption -Colors` array will include; | ||||||||||
|
||||||||||
- **ListPredictionColor** to set color for '>' and source names in **ListView** | ||||||||||
- **ListPredictionSelectionColor** to set color for the highlighted selection in **ListView** | ||||||||||
|
||||||||||
Examples of user changing prediction color: | ||||||||||
|
||||||||||
 | ||||||||||
theJasonHelmick marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
 | ||||||||||
 | ||||||||||
|
||||||||||
```powershell | ||||||||||
Set-PSReadLineOption -Colors @{ InLinePrediction = '#8A0303'} | ||||||||||
Set-PSReadLineOption -Colors @{ InLinePrediction = '#2F7004'} | ||||||||||
Set-PSReadLineOption -Colors @{ InLinePrediction = "$([char]0x1b)[36;7;238m"} | ||||||||||
``` | ||||||||||
|
||||||||||
Multiple types of color code values are supported in PSReadLine. For more information see | ||||||||||
Set-PSReadLineOption in | ||||||||||
[PSReadLine](https://docs.microsoft.com/en-us/powershell/module/PSReadline/Set-PSReadlineOption?view=powershell-7) | ||||||||||
|
||||||||||
Examples of different color code values: | ||||||||||
|
||||||||||
```powershell | ||||||||||
# Use a ConsoleColor enum | ||||||||||
Set-PSReadLineOption -Colors @{ InLinePrediction = 'DarkRed'} | ||||||||||
Set-PSReadLineOption -Colors @{ InLinePrediction = [ConsoleColor]::DarkRed} | ||||||||||
|
||||||||||
# 24 bit color escape sequence | ||||||||||
Set-PSReadLineOption -Colors @{ InLinePrediction = "$([char]0x1b)[38;5;100m"} | ||||||||||
|
||||||||||
# RGB value | ||||||||||
Set-PSReadLineOption -Colors @{ InLinePrediction = "#8181f7"} | ||||||||||
``` | ||||||||||
|
||||||||||
### Key Bindings for Predictions | ||||||||||
|
||||||||||
Key bindings control cursor movement and additional features within the prediction. To support users | ||||||||||
running Predictive IntelliSense on multiple platforms, key bindings are user-settable in the shell | ||||||||||
and a user’s PowerShell profile. | ||||||||||
|
||||||||||
Example of setting a key binding in the shell or user’s profile: | ||||||||||
|
||||||||||
```powershell | ||||||||||
Set-PSReadLineOption -HistorySearchCursorMovesToEnd | ||||||||||
Set-PSReadLineKeyHandler -Key UpArrow -Function HistorySearchBackward | ||||||||||
Set-PSReadLineKeyHandler -Key DownArrow -Function HistorySearchForward | ||||||||||
``` | ||||||||||
|
||||||||||
List of suggested key bindings defined in **SamplePSReadLineProfile.ps1** | ||||||||||
|
||||||||||
Key Binding | PSReadLine Function | Description | ||||||||||
------------- | ------------------- | ----------- | ||||||||||
Up Arrow | HistorySearchBackward | Move backward through history | ||||||||||
Down Arrow | HistorySearchForward | Move forward through history | ||||||||||
F7 | Profile Code | Opens Out-GridView with full history | ||||||||||
F1 | Profile Code | Opens the Help window for the current command or parameter | ||||||||||
F2 | Profile Code | Switches between InLineView and ListView | ||||||||||
Ctrl-b | Profile Code | Add command to history | ||||||||||
Ctrl-q | TabCompleteNext | Windows style Tab for Emacs mode | ||||||||||
Ctrl-Q | TabCompletePrevious | Windows style Tab for Emacs mode | ||||||||||
Ctrl-c | Copy | Clipboard interaction for Emacs mode | ||||||||||
Ctrl-v | Paste | Clipboard interaction for Emacs mode | ||||||||||
Ctrl-d,Ctrl-c | CaptureScreen | Captures screen for pasting to email or blog | ||||||||||
Alt-d | ShellKillWord | Token based movement bound to Emacs word movement | ||||||||||
Alt-Backspace | ShellBackwardKillWord | “ | ||||||||||
Alt-b | ShellBackwardWord | “ | ||||||||||
Alt-f | ShellForwardWord | “ | ||||||||||
Alt-B | SelectShellBackwardWord| “ | ||||||||||
Alt-F | SelectShellForwardWord | “ | ||||||||||
“ or ‘ | Profile Code | Insert Smart quotes | ||||||||||
( or { or [ | Profile Code | Insert matching braces | ||||||||||
Backspace | Profile Code | Delete previous character | ||||||||||
Alt-w | Profile Code | Save current line in history – don’t execute | ||||||||||
Ctrl-V | Profile Code | Paste clipboard as a Here string | ||||||||||
Alt-( | Profile Code | Insert parenthesis around selection or entire line | ||||||||||
Alt-‘ | Profile Code | Toggle quotes on argument under cursor | ||||||||||
Alt-% | Profile Code | Replace aliases with resolved commands | ||||||||||
|
||||||||||
### Search history based on cursor location | ||||||||||
|
||||||||||
The history from PSReadLine is searchable when the user begins typing into the shell. | ||||||||||
Users may search the entire prediction history for commands matching under the current cursor | ||||||||||
position. Users may search history based on 'Verb', 'Noun' and 'Parameter' of a cmdlet | ||||||||||
using the up/down arrow keys. | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is this section related to the predictive intellisense feature? It sounds like the history searching capability, which exists for a long time now. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @daxian-dbw I removed reference to prediction from the text to reduce confusion. User's may not have experience searching history in this manner especially with predictive text being shown, so felt it should be described in the RFC. If this still seems redundant and unnessiary to the existing feature in PSReadLine, I can remove the section. |
||||||||||
|
||||||||||
- Searching history from cmdlet verb. | ||||||||||
 | ||||||||||
|
||||||||||
- Searching histroy from cmdlet noun. | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
 | ||||||||||
|
||||||||||
- Searching history from parameter. | ||||||||||
 | ||||||||||
|
||||||||||
### Edit predictions before accepting the prediction | ||||||||||
|
||||||||||
Users may navigate prediction tokens to make changes to parameters, arguments, and additional | ||||||||||
pipeline commands. The prediction model will update the displayed prediction from the closest | ||||||||||
matches in PSReadLine history or added provider. | ||||||||||
|
||||||||||
In the example below, a user navigates the prediction, pausing to change the -Property argument and | ||||||||||
receiving an updated prediction. | ||||||||||
|
||||||||||
 | ||||||||||
|
||||||||||
## Prediction Extension Model | ||||||||||
|
||||||||||
Additional providers enhance historic predictions by providing domain specific commands and task | ||||||||||
theJasonHelmick marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||
completions. These providers register with the PowerShell engine which includes an extension model | ||||||||||
to support the registration. | ||||||||||
|
||||||||||
## Extension Model Goals/Non-Goals | ||||||||||
|
||||||||||
Goals: | ||||||||||
|
||||||||||
- Provide extension model to support additional providers | ||||||||||
- Support the discovery of providers using `Get-Subsystem` | ||||||||||
- Provide Module owners method of registration | ||||||||||
|
||||||||||
Non-goals: | ||||||||||
|
||||||||||
- Register/Unregister-Subsystem cmdlets are not planned because it's targeting binary subsystem | ||||||||||
implementations, which should deal with registration/unregistration via APIs. | ||||||||||
- Server-side provider privacy is the responsibility of the provider module | ||||||||||
|
||||||||||
## Extension Model Specification | ||||||||||
|
||||||||||
### Discovery of Provider Metadata and Registration | ||||||||||
|
||||||||||
Providers are registered automatically to the PowerShell engine when the user installs a provider | ||||||||||
module. Removal of registration occurs when the module is removed. | ||||||||||
|
||||||||||
Starting with PowerShell 7.1 Preview 7, and as an experimental feature of PowerShell 7.1-RC.1, the | ||||||||||
`Get-Subsystem` cmdlet is an experimental feature of the `PSSubsystemPluginModel`. To enable the | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should be Get-PSSubsystem throughout the doc:
Suggested change
|
||||||||||
experimental feature: | ||||||||||
|
||||||||||
```powershell | ||||||||||
Enable-ExperimentalFeature -Name PSSubsystemPluginModel | ||||||||||
``` | ||||||||||
|
||||||||||
To list the currently installed providers and their respective metadata such as version information: | ||||||||||
|
||||||||||
```powershell | ||||||||||
Get-SubSystem -Kind CommandPredictor | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should be Get-PSSubsystem
Suggested change
|
||||||||||
``` | ||||||||||
|
||||||||||
Example output with no additional providers registered; | ||||||||||
|
||||||||||
```output | ||||||||||
Kind SubsystemType IsRegistered Implementations | ||||||||||
---- ------------- ------------ --------------- | ||||||||||
CommandPredictor ICommandPredic… False {} | ||||||||||
``` | ||||||||||
|
||||||||||
Example output with an additional provider registered; | ||||||||||
|
||||||||||
```output | ||||||||||
Kind SubsystemType IsRegistered Implementations | ||||||||||
---- ------------- ------------ --------------- | ||||||||||
CommandPredictor ICommandPredic… True {Az Predictor} | ||||||||||
``` | ||||||||||
|
Uh oh!
There was an error while loading. Please reload this page.