about_TabExpansionPlusPlus.help.txt

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
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.