en-us/about_psf_tabexpansion.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 246 247 248 249 250 251 252 253 254 255 |
TOPIC
about_psf_tabexpansion SHORT DESCRIPTION Explains the PSFramework's Tab Expansion component LONG DESCRIPTION #-------------------------------------------------------------------------# # Component Commands # #-------------------------------------------------------------------------# - New-PSFTeppCompletionResult - Register-PSFTeppArgumentCompleter - Register-PSFTeppScriptblock #-------------------------------------------------------------------------# # Table of Contents # #-------------------------------------------------------------------------# - Introduction - Building the ScriptBlock - Assigning TEPP - Full Example #-------------------------------------------------------------------------# # Introduction # #-------------------------------------------------------------------------# In PowerShell, when you press the "TAB" key after a parameter, it will provide you with options, what you might want to specify as value for the parameter. By default, it will select this information from the current path. This is not always the most appropriate option. In fact, there is a way for the developer specifying the available options. This guide explains how the PSFramework can help a developer provide custom tab expansion options to the users. The system consists of three separate operations: 1) Gathering the information to display 2) Turning the information into something the system understands 3) Telling the system on what parameter of what function to present it. 1) and 2) are done by the developer through a ScriptBlock as shown in the next chapter. This will be ran when the user asks for completion options. 3) is usually done on module import (or profile execution). TEPP: The name TEPP is an acronym that comes from the original module that invented this feature: Tab Expansion Plus Plus. It was integrated into PowerShell with Version 5. If you want the custom Tab Expansion described in this guide and are running PowerShell versions 3 or 4, you will need to install this module. #-------------------------------------------------------------------------# # Building the ScriptBlock # #-------------------------------------------------------------------------# The basic scriptblock that is used to cover 1) and 2) looks like this: $ScriptBlock = { param ( $commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter ) # Insert stuff here } Basically, when the user hits "TAB" or "CTRL" + "SPACE", this script is run. It is also run automatically in the ISE after finishing a parameter name and pressing space. # The parameters are: # #---------------------# CommandName: The name of the command the specific parameter being provided tab completion for belongs to. It's possible to assign the same completion script to multiple parameters in multiple commands. In some cases it may be desirable to react to which command is being completed for. ParameterName: The name of the parameter the tab completion is provided for. Same as for the command itself, the same tab completion can be assigned for multiple parameters. In complex completion scenarios it may be necessary to know which parameter it is. WordToComplete: This is a critical info: It's what the user typed before triggering tab completion. You should only provide options that begin with these letters. CommandAst: Complicated stuff, but basically this contains information on the entire. line. We will not go further into the details of this parameter. If you already understand ast (Abstract Syntax Trees), then it is unlikely that this guide contains any news for you. FakeBoundParameters: Similar to when you use the $PSBoundparameters variable inside a function, this parameter gives you access to the values already bound to parameters. Note: This cannot give you access to input provided by pipeline! # Transforming the information # #------------------------------# PowerShell doesn't want text as output of the scriptblock. It wants a special kind of object. The PSFramework simplifies this functionality with the New-PSFTeppCompletionResult command. Example usage: New-PSFTeppCompletionResult -CompletionText 'name' -ToolTip 'name' This command is not exported by the module and invisible to the user for direct, manual execution on the commandline, but it is available to all scriptblocks. Note: This command was hidden, because the end user should never need to actually run this manually. It can be made visible by running the following line: { (Get-Item function:New-PSFTeppCompletionResult).Visibility = "Public" }.Invoke() # A basic script sample # #-----------------------# Let's assume we want to provide tab completion for the scripts in our scripts repository, but by the file name. not the full name, even if the user currently is in a different path. $ScriptBlock = { param ( $commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter ) # Get Path to folder $folder = Get-PSFConfigValue -FullName mymodule.path.scripts -Fallback "$env:USERPROFILE\Documents\WindowsPowerShell\Scripts" # Get all files that match $files = Get-ChildItem $folder | Where-Object Name -like "$wordToComplete*" | Sort-Object Name foreach ($file in $files) { New-PSFTeppCompletionResult -CompletionText $file.FullName -ToolTip $file.FullName } } In this scriptblock we do: - First retrieve the scripts-folder from the configuration system. Use the default scripts path if there is no custom path configured. - Then search that folder for any files whose names match the current input and sort them by name. - Finally, we generate a completion object for each result found. #-------------------------------------------------------------------------# # Assigning TEPP # #-------------------------------------------------------------------------# Finally, in order to make the scriptblock available to the command and parameter we want, two more steps are necessary when using the PSFramework tools: 1) Register the scriptblock under a name 2) Assign the named scriptblock to command and/or parameter. Continuing the example from the previous chapter, this could look like this: Register-PSFTeppScriptblock -ScriptBlock $scriptBlock -Name mymodule-scripts Register-PSFTeppArgumentCompleter -Command Invoke-Script -Parameter Path -Name mymodule-scripts This would ... - Assign the scriptblock under the name "mymodule-scripts" - Assign that scriptblock to the "Path" parameter of the "Invoke-Script" command. It could also be assigned to other commands or parameters at will, using copies of the second line as often as desired. Notes: - Registering the scriptblock and assigning it need not happen in the same file. - The scriptblock must be assigned first, before it can be assigned to commands or parameters. The net effect is that you can better distribute code placement. For example the final assignment of scriptblock to command could be done in the same file as the function declaration, while the scriptblock could be used on many commands and stored in an individual file. This makes it easier to manage in a version control system or multi-person project. #-------------------------------------------------------------------------# # Full Example # #-------------------------------------------------------------------------# Here's again the full implementation example. See the above chapters for explanation: # File 1 # #--------# $ScriptBlock = { param ( $commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameter ) # Get Path to folder $folder = Get-PSFConfigValue -FullName mymodule.path.scripts -Fallback "$env:USERPROFILE\Documents\WindowsPowerShell\Scripts" # Get all files that match $files = Get-ChildItem $folder | Where-Object Name -like "$wordToComplete*" | Sort-Object Name foreach ($file in $files) { New-PSFTeppCompletionResult -CompletionText $file.FullName -ToolTip $file.FullName } } Register-PSFTeppScriptblock -ScriptBlock $scriptBlock -Name mymodule-scripts # File 2 (Anywhen after running file 1) # #---------------------------------------# Register-PSFTeppArgumentCompleter -Command Invoke-Script -Parameter Path -Name mymodule-scripts KEYWORDS psframework tepp tab expansion |