Edit

Share via

TabExpansion2

  • Reference
Module:
Microsoft.PowerShell.Core

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 [psobject] InputObject
-Encoding      Encoding     ParameterName [Encoding] Encoding
-Count         Count        ParameterName [long] Count
-Offset        Offset       ParameterName [long] Offset

Example 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
True

Parameters

-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 $true forces 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 $true prevents 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

Outputs

CommandCompletion