en-us/about_psf_tabexpansion.help.txt

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