Building PowerShell auto-completion using TabExpansionPlusPlus – Part 2 – How?


This is a series of 3 blog posts on one of the best kept secrets in PowerShell: “Argument Completion”:

In previous post, we looked at what “Argument Completion” is and how to use the predefined argument completers in TabExpansionPlusPlus.
Now it’s time to start building your own custom argument completers as part of your PowerShell toolmaking.

Creating your own custom “Argument Completer”.

Here are the 3 simple steps to take:

1. Create an “Argument Completer” function/scriptblock (that will provide the list of valid arguments).
2. Register the “Argument Completer” for the command with the specific parameter using the above function/scriptblock.
3. Validate the functionality of the “Argument Completer”.

Step 1: Create Argument Completer function

This function (or scriptblock) will be invoked every time that auto-completion is invoked.
The auto-completion text, tooltip and/or list items will be populated by this “argument completer” function.

Example
In the example below, we provide auto-completion for the cmdlet “Get-Verb” and it’s parameter “-Verb”.

Requirement #1: We want auto-completion to provide all available verbs for the –Verb parameter when
Intellisense is triggered.

Example from the PowerShell console (v5):

Get-Verb -Verb <TAB> to trigger auto-completion or <CTRL+SPACE> to (re)invoke auto-completion.
image_thumb8

Example from the PowerShell ISE:
Get-Verb -Verb <SPACE> to trigger auto-completion or <CTRL+SPACE> to (re)invoke auto-completion.
image_thumb23

Requirement #2: We also want tab completion or Intellisense to complete typed words in arguments using the $wordToComplete parameter value.

Example from the PowerShell console:
Get-Verb -Verb  D <TAB> or <CTRL+SPACE> to (re)invoke auto-completion.
image_thumb18

Example from the PowerShell ISE:
Get-Verb –Verb D <TAB> or <CTRL+SPACE> to (re)invoke auto-completion.
image

Code:
The code below will provide the above described requirements.

function VerbCompletion
{
      param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter)
      Get-Verb –Verb $wordToComplete* | ForEach-Object { New-CompletionResult CompletionText $_.Verb ToolTip (“Group: “ + $_.Group) }
}

The param() block must accept the following parameters:

  • $commandName = The name of the PowerShell command that the auto-completer applies to.
  • $parameterName = The name of the PowerShell command parameter that will be auto-completed.
  • $wordToComplete = The partial text that will be auto-completed.
  • $commandAst = The parsed representation of the command being completed.
  • $fakeBoundParameter = The equivalent to $PSBoundParameters that shows all parameter bindings before execution.

Step 2: Register the Argument Completer for the command with parameter using above function/scriptblock

After you have created a custom argument completer function, the Register-ArgumentCompleter command must be used to register your custom argument completer function with the appropriate PowerShell commands and parameters.

The following parameters should be specified in the call to Register-ArgumentCompleter

  • -CommandName = An array of PowerShell command names  that share the parameter. You can pass in a static array of command values or dynamically obtain them using Get-Command (PowerShell Core) or Get-CommandWithParameter (TabExpansionPlusPlus)
  • -Parameter = The name of the parameter that the auto-completer function will auto-complete values for.
  • -ScriptBlock = The PowerShell scriptblock that will be executed when the argument completer is invoked.
  • -Description = An optional description of the registered argument completer.

    Code:
    Register-ArgumentCompleter `
            -CommandName Get-Verb `
           
    -Parameter Verb `
            -ScriptBlock $function:VerbCompletion `
            -Description 'This argument completer handles the -Verb parameter of the Get-Verb command.'

    Now that the registration is completed, the custom argument completion for the cmdlet “Get-Verb” is available.

    image_thumb4

    Step 3: Validate functionality of Argument Completer

    After you have created your custom argument completer function and registered it, you should test auto-completion to ensure that the function is working as expected.
    The TabExpansionPlusPlus module includes a command to aid in this testing called Test-ArgumentCompleter.

    At a minimum, you must specify the following parameters to Test-ArgumentCompleter:

  • -CommandName = The name of the command whose argument completer will be tested.
  • -ParameterName = The name of the parameter, on the command specified in the -CommandName parameter, whose argument completer will be tested.

    Example
    ### Test the argument completer
    Test-ArgumentCompleter -CommandName Get-Verb -ParameterName Verb
    image_thumb25

    Hope this helps…

  • Advertisements

    3 thoughts on “Building PowerShell auto-completion using TabExpansionPlusPlus – Part 2 – How?

    Leave a Reply

    Fill in your details below or click an icon to log in:

    WordPress.com Logo

    You are commenting using your WordPress.com account. Log Out / Change )

    Twitter picture

    You are commenting using your Twitter account. Log Out / Change )

    Facebook photo

    You are commenting using your Facebook account. Log Out / Change )

    Google+ photo

    You are commenting using your Google+ account. Log Out / Change )

    Connecting to %s