about_PowerTab_handlers.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
TOPIC
    about_PowerTab_handlers
 
SHORT DESCRIPTION
    Tab expansion support in PowerTab can be extended with plug-ins by
    following the steps in this topic.
 
LONG DESCRIPTION
    PowerTab provides a framework to enrich the tab expansion experience in
    PowerShell. It also provides extension points to add tab expansion support
    for additional cmdlets, functions and applications that are not already
    supported by PowerTab. This is done through tab expansion handlers that
    add logic to PowerTab.
 
    Tab expansion handlers are given first chance to decide what to do with
    the command line. Once a handler has signaled that it has decided on the
    appropriate output, processing halts and the output of that handler is
    pressented to the user according to their preferences or the limitations of
    the PowerShell host.
 
    Order of operation:
    1: Command Handler (for the current command, if it exists)
    2: Parameter Handler (for the current parameter, if it exists)
    3: Enum Handler (internal to PowerTab, handles parameters with enum
        values)
    4: Core Handler (general PowerTab logic)
 
 
  CREATING A COMMAND HANDLER
      Command handlers are called when the last word (location of the cursor)
      will be the value to a parameter of the command that the command handler
      is registered to. The handler will be given first chance at the user
      input as well as information on the current context. Because of this,
      command handlers can override default PowerTab behavior for parameters
      of the command.
 
      Command handlers must follow this contract.
 
      NOTE: This applies to command and parameter handlers
      1: PowerTab WILL provide a context object that records what is known
          about the current command line, and a couple of reference variables
          (see about_PowerTab_context for details).
      2: If the handler will provide the tab expansion options for the given
          context, it MUST set the variable $TabExpansionHasOutput.Value to
          $true, even if no results will be produced. This will stop PowerTab
          from interpreting the context any further.
      3: The handler MUST output the options, as strings, to be displayed to
          the user, or no output at all.
      4: The handler MAY set the variable $QuoteSpaces.Value to $false to
          prevent PowerTab from quoting output values from the handler that
          contain spaces. The default is $true.
 
      Example:
 
          Register-TabExpansion "Get-Service" -Type Command {
              # 1:
              param($Context, [ref]$TabExpansionHasOutput, [ref]$QuoteSpaces)
 
              $Argument = $Context.Argument
              switch -exact ($Context.Parameter) {
                  'DisplayName' {
                      $TabExpansionHasOutput.Value = $true # 2:
                      Get-Service -DisplayName "*$Argument*" |
                          Select-Object -ExpandProperty DisplayName # 3:
                  }
                  'Name' {
                      $TabExpansionHasOutput.Value = $true # 2:
                      Get-Service -Name "$Argument*" |
                          Select-Object -ExpandProperty Name # 3:
                  }
              }
          }
 
 
  CREATING A PARAMETER HANDLER
      Parameter handlers are called when the last word (location of the cursor)
      will be the value to the parameter that the parameter handler is
      registered to. This handler will be called for any command, but only if
      the registered parameter is the current context.
 
      Parameter handlers must follow this contract.
 
      NOTE: This applies to command and parameter handlers
      1: PowerTab WILL provide a context object that records what is known
          about the current command line, and a couple of reference variables
          (see about_PowerTab_context for details).
      2: If the handler will provide the tab expansion options for the given
          context, it MUST set the variable $TabExpansionHasOutput.Value to
          $true, even if no results will be produced. This will stop PowerTab
          from interpreting the context any further.
      3: The handler MUST output the options, as strings, to be displayed to
          the user, or no output at all.
      4: The handler MAY set the variable $QuoteSpaces.Value to $false to
          prevent PowerTab from quoting output values from the handler that
          contain spaces. The default is $true.
 
      Example:
 
          Register-TabExpansion "PSDrive" -Type Parameter {
              # 1:
              param($Argument, [ref]$TabExpansionHasOutput, [ref]$QuoteSpaces)
 
              if ($Argument -notlike '^\$') {
                  $TabExpansionHasOutput.Value = $true # 2:
                  Get-PSDrive "$Argument*" |
                      Select-Object -ExpandProperty Name # 3:
              }
          }
 
 
  REGISTERING A HANDLER
      Once the hander's script block is defined, it must be registered with
      PowerTab. Here is the syntax of the registration command.
 
          Register-TabExpansion [-Name] <String> [-Handler] <ScriptBlock>
          [-Type <String>] [-Force]
 
      The name of the command or parameter to handle must be entered. There can
      only be one handler for a command name or parameter name.
 
      A command name can either be simple like "Get-FooBar" or fully qualified
      like "MyModule\Get-Foobar". Using the simple name will trigger on any
      module using that command name.
 
      A parameter name should only be the real name of the parameter like
      "ComputerName". Parameter name aliases will be resolved by PowerTab like
      "cn" or "comp".
 
 
SEE ALSO
 
    about_PowerTab_context
    http://powertab.codeplex.com/documentation