TabExpansion2

TabExpansion2
    [-inputScript] <String>
    [[-cursorColumn] <Int32>]
    [[-options] <Hashtable>]
    [<CommonParameters>]

TabExpansion2
    [-ast] <Ast>
    [-tokens] <Token[]>
    [-positionOfCursor] <IScriptPosition>
    [[-options] <Hashtable>]
    [<CommonParameters>]

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.

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] PipelineVariable

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 Get-Data {
    param (
        [ValidateSet('One', 'Two', 'Three')]
        [string]$Stage
    )
    Write-Verbose "Retrieving data for stage $Stage"
}

$result = TabExpansion2 -inputScript ($line = 'Get-Data -Stage ') -cursorColumn $line.Length |
    Select-Object -ExpandProperty CompletionMatches
$result.Count -eq 3
$result.CompletionText -contains 'Three'

True
True

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.