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.