about_TabExpansionPlusPlus.help.txt
|
TOPIC about_TabExpansionPlusPlus SHORT DESCRIPTION TabExpansionPlusPlus extends the tab expansion and Intellisense features of PowerShell to help make PowerShell scripters more productive. LONG DESCRIPTION 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. [CmdletBinding(Def<TAB> -or- [Parameter(<TAB> * 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 requires. A handler is passed a number of parameters depending on the kind of handler: PowerShell commands (cmdlets, scripts, functions): param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) Native commands (PowerShell V3 or V4): param($wordToComplete, $commandAst) Native commands (PowerShell V5 and beyond): param($wordToComplete, $commandAst, $cursor) PowerShell will pass the following values for these parameters: $commandName The name of the command. Note that if the command line used an alias, this value will be the actual command, not the alias. $parameterName 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. $wordToComplete This value will come from the command line. It might be an an empty string. $commandAst This value is the parsed represenation of the command line. It is only necessary for very advanced scenarios. $fakeBoundParameter 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. $cursor 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 completers. Here is a complete example to handle: Get-Command -Verb <TAB> function VerbCompletion { param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter) Get-Verb "$wordToComplete*" | ForEach-Object { New-CompletionResult $_.Verb ("Group: " + $_.Group) } } Register-ArgumentCompleter ` -Command Get-Command ` -Parameter Verb ` -Description 'Complete valid verbs for: Get-Command -Verb <TAB>' ` -ScriptBlock $function:VerbCompletion By convention, TabExpansionPlusPlus completers are placed in files with ArgumentCompleters as part of the name but they can be in any ps1 or psm1 file. 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) { Register-ArgumentCompleter ` -Command Get-Command ` -Parameter Verb ` -ScriptBlock $function:VerbCompletion } 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 call Get-Process. 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 Parameter. * 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: Set-CompletionPrivateData Get-CompletionPrivateData 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 Get-CommandTreeCompletion. 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 New-CommandTree. 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: New-CompletionResult 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. Get-CommandWithParameter 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. Set-CompletionPrivateData This function is used to cache data that is expensive to compute. It is provided as an alternative to using the attribute InitializeArgumentCompleter. Get-CompletionPrivateData This function is used to retrived previously cached data that helps speed up a completer. New-CommandTree 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). Get-CommandTreeCompletion This function completes command arguments based on the context from the command line and command tree pased in. POWERSHELL COMPATIBILITY TabExpansionPlusPlus requires PowerShell V3 or later. FUNCTIONS Get-ArgumentCompleter This is a utility function to see the various registered custom argument completers. Register-ArgumentCompleter 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 be convenient. Note that this function is also a cmdlet in PowerShell V5, but with one small difference - the cmdlet does not have a -Description parameter. Set-TabExpansionOption This function is used to control the behavior of a few minor features in TabExpansionPlusPlus and in TabExpansion2. TYPES NativeCommandTreeNode 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: * Subcommand 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. * Argument 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: param($wordToComplete, $commandAst) 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. FEEDBACK https://github.com/lzybkr/TabExpansionPlusPlus 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. SEE ALSO 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. |