TabExpansion2
A helper function that wraps the CompleteInput() method of the CommandCompletion class to
provide tab completion for PowerShell scripts.
Syntax
TabExpansion2
[-inputScript] <String>
[[-cursorColumn] <Int32>]
[[-options] <Hashtable>]
[<CommonParameters>] TabExpansion2
[-ast] <Ast>
[-tokens] <Token[]>
[-positionOfCursor] <IScriptPosition>
[[-options] <Hashtable>]
[<CommonParameters>] Description
TabExpansion2 is a built-in function that provides tab completion for user input. PowerShell calls
this function when the user presses the Tab or Ctrl+Space key while
typing a command. The function returns a list of possible completions for the current input.
TabExpansion2 isn't normally called directly by users. However, it can be useful for testing tab
completion. To use TabExpansion2, you need to provide the current input script and the cursor
position in the script. The function returns a CommandCompletion object that contains a list of
possible completions for the current input. This input script can be a string or an abstract syntax
tree (AST) that represents the script.
You can override the default behavior of TabExpansion2 by defining a custom function with the same
name in your PowerShell session. This custom function can provide completions for custom commands or
parameters. While it is possible to override TabExpansion2, it's not supported. You should create
a custom function only if you have a specific need to customize the tab completion behavior.
Examples
Example 1 - Get tab completion for command parameter
This example shows the same results you would get by entering Format-Hex -<Tab> at the PowerShell
command prompt. The TabExpansion2 function returns a CommandCompletion object that contains a
list of possible completions for the - token.
TabExpansion2 -inputScript ($s = 'Format-Hex -') -cursorColumn $s.Length |
Select-Object -ExpandProperty CompletionMatches
CompletionText ListItemText ResultType ToolTip
-------------- ------------ ---------- -------
-Path Path ParameterName [string[]] Path
-LiteralPath LiteralPath ParameterName [string[]] LiteralPath
-InputObject InputObject ParameterName [Object] InputObject
-Encoding Encoding ParameterName [string] Encoding
-Raw Raw ParameterName [switch] Raw
-Verbose Verbose ParameterName [switch] Verbose
-Debug Debug ParameterName [switch] Debug
-ErrorAction ErrorAction ParameterName [ActionPreference] ErrorAction
-WarningAction WarningAction ParameterName [ActionPreference] WarningAction
-InformationAction InformationAction ParameterName [ActionPreference] InformationAction
-ErrorVariable ErrorVariable ParameterName [string] ErrorVariable
-WarningVariable WarningVariable ParameterName [string] WarningVariable
-InformationVariable InformationVariable ParameterName [string] InformationVariable
-OutVariable OutVariable ParameterName [string] OutVariable
-OutBuffer OutBuffer ParameterName [int] OutBuffer
-PipelineVariable PipelineVariable ParameterName [string] PipelineVariableExample 2 - Get tab completion for parameter values
This example shows how to get tab completion for parameter values. In this example, we expect that
Stage parameter has three possible values and that one of the values is Three. You can use
this technique to test that tab completion for your function returns the expected results.
function GetData {
param (
[ValidateSet('One', 'Two', 'Three')]
[string]$Stage
)
Write-Verbose "Retrieving data for stage $Stage"
}
$result = TabExpansion2 -inputScript ($line = 'GetData -Stage ') -cursorColumn $line.Length |
Select-Object -ExpandProperty CompletionMatches
$result.Count -eq 3
$result.CompletionText -contains 'Three'
True
TrueParameters
-ast
An abstract syntax tree (AST) object that represents the script that you want to expand using tab completion.
| Type: | Ast |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-cursorColumn
The column number of the cursor in the input script string. The cursor position is used to determine the token that gets expanded by tab completion.
| Type: | Int32 |
| Position: | 1 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-inputScript
A string that represents the script that you want to expand using tab completion.
| Type: | String |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-options
A hashtable of option values to pass to the CompleteInput() API. The API accepts the following
boolean options:
IgnoreHiddenShares- When set to$true, ignore hidden UNC shares such as\\COMPUTER\ADMIN$and\\COMPUTER\C$. By default, PowerShell includes hidden shares.RelativePaths- By default, PowerShell decides how to expand paths based on the input you provided. Setting this value to$trueforces PowerShell to replace paths with relative paths. Setting this value to$false, forces PowerShell to replace them with absolute paths.LiteralPaths- By default, PowerShell replace special file characters, such as square brackets and back-ticks, with their escaped equivalents. Setting this value to$trueprevents the replacement.
| Type: | Hashtable |
| Position: | 3 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-positionOfCursor
The column number of the cursor in the input AST. The cursor position is used to determine the token that gets expanded by tab completion.
| Type: | IScriptPosition |
| Position: | 2 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-tokens
An array of tokens parsed from the input script. The tokens are used to determine the token that gets expanded by tab completion.
| Type: | Token[] |
| Position: | 1 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
None
