TabExpansionPlusPlus extends the tab expansion and Intellisense features
of PowerShell to help make PowerShell scripters more productive.
V3 of PowerShell has excellent support for tab expansion and
Intellisense, but it is missing some useful features. This module
addresses some of those shortcomings.
TabExpansionPlusPlus adds support for the following:
* Complete attribute argument names, e.g.
* Exclude hidden files from results.
* Easily add custom argument completion.
* Easily set options like 'IgnoreHiddenShares'.
In addition to making it simple to add custom argument completion,
TabExpansionPlusPlus provides many useful custom argument completers that
can also serve as good examples of how to add your own.
CUSTOM ARGUMENT COMPLETION
Argument completion is when PowerShell tries to complete a parameter's
argument, for example:
Get-Process -Name <TAB> # complete process names
PowerShell has built in argument completion support for many commands.
For commands with no built in support, PowerShell will try to find
a user provided handler.
For PowerShell commands (cmdlets, scripts, functions), you can provide
a handler for a parameter for all commands. For example, you might
want to use the same completion for any command with a ComputerName
parameter. You can also provide a handler for a parameter to a
specific command. PowerShell handles the complexity of determining
which parameter's argument needs completion including handling positional
arguments even when there are multiple parameter sets.
For native commands (the CommandType is Application), PowerShell has
no parameter metadata, so custom argument handlers are dispatched based
on the command name.
TabExpansionPlusPlus makes it simple to write a handler by providing functions
to register the handler and to create the result object that PowerShell
A handler is passed a number of parameters depending on the kind of
PowerShell commands (cmdlets, scripts, functions):
Native commands (PowerShell V3 or V4):
Native commands (PowerShell V5 and beyond):
PowerShell will pass the following values for these parameters:
The name of the command. Note that if the command line used
an alias, this value will be the actual command, not the alias.
The name of the parameter whose argument is being completed.
Note that if the command line used a parameter alias, this value
will be the actual parameter, not the alias.
This value will come from the command line. It might be an an
This value is the parsed represenation of the command line. It
is only necessary for very advanced scenarios.
This value is similar to $PSBoundParameters - it is a hashtable
where the key is parameter name and the value is the actual
argument value. Note that sometimes the value cannot be
determined safely by PowerShell, if this is the case, there
won't be a key with the parameter even though it appears on
the command line.
This value is the index of the cursor where completion was invoked.
It is only available in PowerShell V5 and beyond.
REGISTERING ARGUMENT COMPLETERS
You the function Register-ArgumentCompleter to register argument
Here is a complete example to handle: Get-Command -Verb <TAB>
Get-Verb "$wordToComplete*" |
New-CompletionResult $_.Verb ("Group: " + $_.Group)
-Command Get-Command `
-Parameter Verb `
-Description 'Complete valid verbs for: Get-Command -Verb <TAB>' `
By convention, TabExpansionPlusPlus completers are placed in files with
ArgumentCompleters as part of the name but they can be in any ps1 or psm1
PowerShell V5 adds support for registering argument completers without
needing TabExpansionPlusPlus. The recommendation is that module authors
that want to register argument completers use the following pattern:
if (Get-Command Register-ArgumentCompleter -ea Ignore)
-Command Get-Command `
-Parameter Verb `
Note that this example does not use the -Description parameter because
it is only available in the function from TabExpansionPlusPlus. PowerShell's
builtin cmdlet does not have this parameter.
When registering this way, a module author can avoid errors while working
with PowerShell V5 with no extra modules installed, or with TabExpansionPlusPlus
installed when using any version of PowerShell V3 or greater.
WRITING CUSTOM ARGUMENT COMPLETERS
A typical argument completer often uses the exact command that you
are trying to provide a completion for. For example, if you wanted
to complete the -Name parameter to Get-Process, you would normally
The completer is responsible for sorting the results in a useful way.
Most often this means sorting alphanumerically on the completion text,
but in some uncommon situations you may prefer sorting based on some
other factor, for example sorting by the frequency of the use of the item.
Completers must return instances System.Management.Automation.CompletionResult.
A completion result has 4 values:
* The completion text
The actual text that appears on the command line or in your script.
* The list item text
Only used for Intellisense, this is the text that appears in the
drop down window. It is sometimes more user friendly to use part
of the completion text instead of the full text when the completion
text is long.
* The type of completion
Only used for Intellisense. This will almost always be
ParameterValue. First, it controls the glyph that is displayed in
the Intellisense window. Second, when Intellisense is invoked
automatically (as opposed to when CTRL-SPACE is used), the results
displayed are filtered based on the context. For example, after
typing '-', automatic Intellisense only displays results with type
* The tooltip text
Only used for Intellisense. The tooltip text is displayed for
the currently selected item in the Intellisense drop down. It
is only displayed after a brief pause. The tooltip text cannot
be the empty string. Ideally the tooltip text should display
extra information about the completion. Some examples include
the status of some object or the full text of the completion
if the list item text only includes a part of the completion.
New-CompletionResult is a useful function for creating your results
because it simplifies several things. First, by default it assumes
your result is a ParameterValue as this is the most common type of
result. Second, if you don't provide the list item text or tooltip
text, it defaults to the completion text you provide. While this
is fine, it is still recommended that you provide a more useful value
for the tooltip. Last, it automatically adds quotes to your completion
text if quotes would be required.
TabExpansionPlusPlus contains many good examples of how to write your own
custom completers, be sure to look at a few to see the sorts of things
you can do.
CUSTOM COMPLETER PERFORMANCE
Automatic Intellisense in the ISE times out after 500ms, so if your
completer runs slowly, it may not be useful for Intellisense. Sometimes
it is possible to cache data to speed up your completer. TabExpansionPlusPlus
provides a couple of useful utilities to help.
First, there are two functions to give you a simple way to save and retrieve
your cached data:
These functions are simple wrappers around a hashtable that is kept in the
TabExpansionPlusPlus module. You should prefer these functions over using
global variables if your completer is defined in a script. If your
completer is defined in a module, a module scoped variable is a better
because the data will be removed if the module is unloaded.
One strategy to caching is to build the cache the first time your
completer runs. This is memory efficient, but if the cache takes a long
time to build, you might not get any Intellisense the first time around
or worse, the pipeline might get stopped and your completer never gets
a chance to save the expensive work it did to build the cache.
COMPLETERS FOR NATIVE COMMAND TREES
Some native commands accept a variety of arguments depending on previously
specified arguments. Netsh.exe is a great example. One quick example -
netsh firewall <TAB>
Here one would expect to complete on of the valid commands that are valid
in the firewall context such as add, delete, dump, help, set, or show.
For well structured commands, you can build a representation of the command
structure once, cache the structure, then pass it to
You can build this structure using the command New-CommandTree. Most often
you'll just specify a command and possibly pass a script block that specifies
sub-commands. Occasionally you may want completions that are dynamic, e.g.
net STOP <TAB>
should only complete services that are started. You can do this by specifing
a sub-command that is a script block. See the function NetExeCompletion in
the module TabExpansionPlusPlus for an example of all of the capabilities of
DEBUGGING A CUSTOM COMPLETER
Debugging a custom completer can be a little confusing. One simple way
to debug is set a line breakpoint in your custom completer and then call
TabExpansion2 explicitly. Here is an example:
PS> sbp -script .\Microsoft.PowerShell.Core.ArgumentCompleters.ps1 -line 62
PS> $line = 'Get-PSSnapin -Name '
PS> TabExpansion2 -inputScript $line -cursorColumn $line.Length
Hit Line breakpoint on 'Microsoft.PowerShell.Core.ArgumentCompleters.ps1:62'
CUSTOM COMPLETER SUPPORT FUNCTIONS
TabExpansionPlusPlus provides several functions that are useful for argument
completers but are not exported because they are not useful outside of
argument completion. Those functions are described here:
This function is described in some detail in the section above
titled WRITING CUSTOM ARGUMENT COMPLETERS. In general, this command
should be used to create all results in a custom completer.
This function is primarily useful when the Command argument to
the ArgumentCompleter attribute is specified with a ScriptBlock.
This function helps avoid registering completers that can never
work because they accidently try to register a command based on
a parameter alias.
This function is used to cache data that is expensive to compute.
It is provided as an alternative to using the attribute
This function is used to retrived previously cached data that
helps speed up a completer.
This function is used to build a data structure that is used by
Get-CommandTreeCompletion. You can specify sub-commands,
arguments (which do not change the command context), and script
blocks (which provide for dynamic completion, and also do not
change the command context).
This function completes command arguments based on the context
from the command line and command tree pased in.
TabExpansionPlusPlus requires PowerShell V3 or later.
This is a utility function to see the various registered custom
This function can be used to register a custom argument completer. It
is usually easier to use the ArgumentCompleter attribute on a function,
this function can be used in situations where the attribute might not
Note that this function is also a cmdlet in PowerShell V5, but with
one small difference - the cmdlet does not have a -Description parameter.
This function is used to control the behavior of a few minor features
in TabExpansionPlusPlus and in TabExpansion2.
The function Get-CommandTreeCompletion takes an array of this type to
assist in completing command arguments to native commands.
This type has 3 essential forms:
This form can have a collection of children that are also of type
NativeCommandTreeNode. This form is used both as a valid completion
and to navigate the command tree to it's children.
This form is used to specify valid completions that do not change
the command context. When Get-CommandTreeCompletion analyzes the
command line, it will ignore items of this type if they are not part
of the argument being completed.
* Script block
This form is used dynamic completions. If this form is found in
when Get-CommandTreeCompletion has finished analyzing the command
line and set the appropriate context, the script block will be
invoked to perform the completion. The arguments are:
The function New-CommandTree can be used to simplify constructing the command
tree. TabExpansionPlusPlus does not define an alias for this function, but it is
suggested to define an alias locally in your completer function, for examples
see NetExeCompletion or NetshExeCompletion in WindowsExe.ArgumentCompleters.ps1.
CONTRIBUTING TO TABEXPANSIONPLUSPLUS
If you write any generally useful custom argument completers or if
you add any other useful additions, feel free to submit a pull
request or submit feedback on the github page.
PowerTab is highly recommended if you use PowerShell V2. PowerTab also
provides an Intellisense like UI for the console which makes it a nice
alternative to TabExpansionPlusPlus In V3, other than the UI, the capabilities
of TabExpansionPlusPlus and PowerTab are very similar.