|
| 1 | +--- |
| 2 | +title: Tab Completion: Training Completers |
| 3 | +--- |
| 4 | +# Training Completers |
| 5 | + |
| 6 | +[Back to Tab Expansion](https://psframework.org/documentation/documents/psframework/tab-completion.html) |
| 7 | + |
| 8 | +## Synopsis |
| 9 | + |
| 10 | +Dynamic tab completion is great, but sometimes you just cannot determine legal values reliably, all by yourself. |
| 11 | +This is where the ability to "train" your completers comes in - that is, to either manually add values, or automagically learn from the user's input! |
| 12 | + |
| 13 | +## Description |
| 14 | + |
| 15 | +There are fundamentally two ways to train your completers: |
| 16 | + |
| 17 | ++ Automatically, based on the input a command receives. This is designed for convenient use and can happen _after_ validating the input (to prevent learning undesirable values). |
| 18 | ++ Manually, by adding them with the `Add-PSFTeppCompletion` command. |
| 19 | + |
| 20 | +No matter which way they are added, they can be combined with dynamic completion. |
| 21 | +Learned values can also be unlearned (see below). |
| 22 | + |
| 23 | +## Automatic Training |
| 24 | + |
| 25 | +To enable automatic training of completers, three steps must be taken: |
| 26 | + |
| 27 | ++ The Completer must be configured for Auto-Training |
| 28 | ++ The Completer must be assigned via Attribute, _not_ via command! |
| 29 | ++ The code must call `Update-PSFTeppCompletion` when it wants to train input |
| 30 | + |
| 31 | +Logically, Automatic Training _cannot_ be combined with `[PsfValidateSet(...)]`, as the validation would happen before the training, preventing new values from being accepted. |
| 32 | + |
| 33 | +> Example |
| 34 | +
|
| 35 | +```powershell |
| 36 | +Register-PSFTeppScriptblock -Name "alcohol.type" -ScriptBlock { |
| 37 | + @{ Text = 'Beer'; ToolTip = 'Elixir of the gods'} |
| 38 | + @{ Text = 'Mead'; ToolTip = 'Elixir of the angry gods' } |
| 39 | + @{ Text = 'Whiskey'; ToolTip = 'Unleash the Irishman in you!' } |
| 40 | + @{ Text = 'Wine'; ToolTip = 'For the discriminating somelier' } |
| 41 | + @{ Text = 'Vodka'; ToolTip = 'Beware, before it is too late' } |
| 42 | + @{ Text = 'Rum (3y)'; ToolTip = 'Barkeepers Delight' } |
| 43 | + @{ Text = 'Rum (5y)'; ToolTip = 'Well aged, combines well' } |
| 44 | + @{ Text = 'Rum (7y)'; ToolTip = 'Oldtimer, use for cocktails that need some character' } |
| 45 | +} -AutoTraining |
| 46 | +
|
| 47 | +function Get-Alcohol { |
| 48 | + [CmdletBinding()] |
| 49 | + Param ( |
| 50 | + [PsfArgumentCompleter('alcohol.type')] |
| 51 | + [string] |
| 52 | + $Type, |
| 53 | +
|
| 54 | + [string] |
| 55 | + $Unit = "Pitcher" |
| 56 | + ) |
| 57 | + if ($Type -eq 'Kölsch') { throw "Would go bad before serving!" } |
| 58 | + Update-PSFTeppCompletion |
| 59 | +
|
| 60 | + Write-Host "Drinking a $Unit of $Type" |
| 61 | +} |
| 62 | +``` |
| 63 | + |
| 64 | +With this, the command comes with a few pre-defined beverages it can complete: |
| 65 | + |
| 66 | +```powershell |
| 67 | +Get-Alcohol -Type <TAB> |
| 68 | +``` |
| 69 | + |
| 70 | +But now when we provide a new value: |
| 71 | + |
| 72 | +```powershell |
| 73 | +Get-Alcohol -Type Mojito |
| 74 | +``` |
| 75 | + |
| 76 | +It will now also offer the new value (however without a friendly tooltip): |
| 77 | + |
| 78 | +```powershell |
| 79 | +Get-Alcohol -Type <TAB> |
| 80 | +``` |
| 81 | + |
| 82 | +## Manual Training |
| 83 | + |
| 84 | +Manual Training requires no particular configuration and allows assignment via command _or_ attribute. |
| 85 | +It also allows adding tooltips to your completion. |
| 86 | +Finally, it can be applied to _any_ completer defined, including those configured for Automatic Training. |
| 87 | + |
| 88 | +> Example |
| 89 | +
|
| 90 | +```powershell |
| 91 | +Register-PSFTeppScriptblock -Name "alcohol.type" -ScriptBlock { |
| 92 | + @{ Text = 'Beer'; ToolTip = 'Elixir of the gods'} |
| 93 | + @{ Text = 'Mead'; ToolTip = 'Elixir of the angry gods' } |
| 94 | + @{ Text = 'Whiskey'; ToolTip = 'Unleash the Irishman in you!' } |
| 95 | + @{ Text = 'Wine'; ToolTip = 'For the discriminating somelier' } |
| 96 | + @{ Text = 'Vodka'; ToolTip = 'Beware, before it is too late' } |
| 97 | + @{ Text = 'Rum (3y)'; ToolTip = 'Barkeepers Delight' } |
| 98 | + @{ Text = 'Rum (5y)'; ToolTip = 'Well aged, combines well' } |
| 99 | + @{ Text = 'Rum (7y)'; ToolTip = 'Oldtimer, use for cocktails that need some character' } |
| 100 | +} |
| 101 | +
|
| 102 | +function Get-Alcohol { |
| 103 | + [CmdletBinding()] |
| 104 | + Param ( |
| 105 | + [string] |
| 106 | + $Type, |
| 107 | +
|
| 108 | + [string] |
| 109 | + $Unit = "Pitcher" |
| 110 | + ) |
| 111 | + if ($Type -eq 'Kölsch') { throw "Would go bad before serving!" } |
| 112 | +
|
| 113 | + Add-PSFTeppCompletion -Name alcohol.type -Options $Type |
| 114 | +
|
| 115 | + Write-Host "Drinking a $Unit of $Type" |
| 116 | +} |
| 117 | +
|
| 118 | +# Add some completion |
| 119 | +Add-PSFTeppCompletion -Name alcohol.type -Options @{ Text = 'Margarita'; Tooltip = 'A proper Mexican' } |
| 120 | +
|
| 121 | +# Actually assign the completion to the command |
| 122 | +Register-PSFTeppArgumentCompleter -Command Get-Alcohol -Parameter Type -Name 'alcohol.type' |
| 123 | +``` |
| 124 | + |
| 125 | +With this, we can now complete the alcohol types with the ones calculated by the scriptblock, plus the one we predefined: |
| 126 | + |
| 127 | +```powershell |
| 128 | +Get-Alcohol -Type <TAB> |
| 129 | +``` |
| 130 | + |
| 131 | +But now when we provide a new value: |
| 132 | + |
| 133 | +```powershell |
| 134 | +Get-Alcohol -Type Mojito |
| 135 | +``` |
| 136 | + |
| 137 | +It will now also offer the new value (however without a friendly tooltip): |
| 138 | + |
| 139 | +```powershell |
| 140 | +Get-Alcohol -Type <TAB> |
| 141 | +``` |
| 142 | + |
| 143 | +## Managing Learned Values |
| 144 | + |
| 145 | +There are two commands that can be used to interact with the learned values: |
| 146 | + |
| 147 | ++ `Get-PSFTeppCompletion` to see what has been learned |
| 148 | ++ `Remove-PSFTeppCompletion` to remove an undesired value from the list of trained values. |
| 149 | + |
| 150 | +> Example |
| 151 | +
|
| 152 | +```powershell |
| 153 | +# List Currently trained values |
| 154 | +Get-PSFTeppCompletion -Name alcohol.type |
| 155 | +``` |
| 156 | + |
| 157 | +```text |
| 158 | +Completion Text |
| 159 | +---------- ---- |
| 160 | +alcohol.type Mojito |
| 161 | +alcohol.type Margarita |
| 162 | +``` |
| 163 | + |
| 164 | +```powershell |
| 165 | +# Remove all currently trained values |
| 166 | +Get-PSFTeppCompletion -Name alcohol.type | Remove-PSFTeppCompletion |
| 167 | +``` |
| 168 | + |
| 169 | +## Persisting learned completions across sessions |
| 170 | + |
| 171 | +PSFramework Tab Completion does _not_ offer a direct feature to persist the trained completions across sessions. |
| 172 | +This can be implemented on your own however, using a combination of `Get-PSFTeppCompletion`, `Export-PSFClixml`, `Import-PSFClixml` and `Add-PSFTeppCompletion`. |
| 173 | + |
| 174 | +If you wish to implement this, be sure to do so responsibly in regards to secrets or sensitive data. |
| 175 | +Also consider aging entries. |
| 176 | + |
| 177 | +[Back to Tab Expansion](https://psframework.org/documentation/documents/psframework/tab-completion.html) |
0 commit comments