You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This package provides automatic (tab) completion in BASH and ZSH for Symfony Console Component based applications. With zero configuration, this package allows completion of available command names and the options they provide. Custom completion behaviour can be added for option and argument values by name.
11
+
This package provides automatic (tab) completion in BASH and ZSH for Symfony Console Component based applications. With zero configuration, this package allows completion of available command names and the options they provide. User code can define custom completion behaviour for arugment and option values.
2. Add an instance of `CompletionCommand` to your application's `Application::getDefaultCommands()` method:
23
+
23
24
```php
24
25
protected function getDefaultCommands()
25
26
{
@@ -42,48 +43,83 @@ If you don't need any custom completion behaviour, all you need to do is add the
42
43
eval$([program] _completion --generate-hook)
43
44
```
44
45
45
-
By default this registers completion for the absolute path to you application. You can specify a command name to complete for instead using the `-p` option, which is useful if you're using an alias to run the program.
46
+
By default this registers completion for the absolute path to you application, which will work if the program on accessible on your PATH. You can specify a program name to complete for instead using the `--program` option, which is required if you're using an alias to run the program.
47
+
48
+
4. If you want the completion to apply automatically for all new shell sessions, add the command from step 3 to your shell's profile (eg. `~/.bash_profile` or `~/.zshrc`)
46
49
47
-
4. Add the command from step 3 to your bash profile if you want the completion to apply automatically for all new terminal sessions.
50
+
Note: The type of shell (ZSH/BASH) is automatically detected using the `SHELL` environment variable at run time. In some circumstances, you may need to explicitly specify the shell type with the `--shell-type` option.
48
51
49
-
Note: If `[program]` is an alias you will need to specify the aliased name with the `-p|--program` option, as completion may not work otherwise: `_completion --generate-hook -p [myalias]`.
50
52
51
-
Second note: The type of shell (ZSH/BASH) is automatically detected using the `SHELL` environment variable at run time. In some circumstances, you may need to explicitly specify the shell type with the `--shell-type` option.
53
+
## How it works
52
54
53
-
### How it works
55
+
The `--generate-hook` option of `CompletionCommand` generates a small shell script that registers a function with your shell's completion system to act as a bridge to the completion command in your application. When you request completion for your program (by pressing tab with your program name as the first word on the command line), the bridge function is run; passing the current command line contents and cursor position to `[program] _completion`, and feeding the resulting output back to the shell.
54
56
55
-
The `--generate-hook` option of `CompletionCommand` generates a few lines of BASH that, when executed, register your application as a completion handler for your itself in the current shell session. When you request completion for your program (by pressing tab), the completion command on your application is run with no arguments: `[program] _completion`. This uses environment variables set by BASH to get the current command line contents and cursor position, then completes from your console command definitions.
56
57
58
+
## Defining value completions
57
59
58
-
## Custom completion
60
+
By default, no completion results will be returned for option and argument values. There are two ways of defining custom completion values for values: extend `CompletionCommand`, or implement `CompletionAwareInterface` interface.
59
61
60
-
Custom completion behaviour for argument and option values can be added by sub-classing `CompletionCommand`.
62
+
### Implementing `CompletionAwareInterface`
61
63
62
-
The following examples are for an application with this signature: `myapp (walk|run) [-w|--weather=""] direction`
64
+
`CompletionAwareInterface` allows a command to be responsible for completing its own option and argument values. When completion is run with a command name specified (eg. `myapp mycommand ...`) and the named command implements this interface, the appropriate interface method is called automatically:
63
65
64
66
```php
65
-
class MyCompletionCommand extends CompletionCommand {
67
+
class MyCommand extends Command impements CompletionAwareInterface
68
+
{
69
+
...
70
+
71
+
public function completeOptionValues($optionName, CompletionContext $context)
72
+
{
73
+
if ($optionName == 'some-option') {
74
+
return ['myvalue', 'other-value', 'word'];
75
+
}
76
+
}
66
77
67
-
protected function runCompletion()
78
+
public function completeArgumentValues($argumentName, CompletionContext $context)
This method of generating completions doesn't support use of `CompletionInterface` implementations at the moment, which make it easy to share completion behaviour between commands. To use this functionality, you'll need write your value completions by extending `CompletionCommand`.
88
+
89
+
90
+
### Extending `CompletionCommand`
91
+
92
+
Argument and option value completions can also be defined by extending `CompletionCommand` and overriding the `configureCompletion` method:
93
+
94
+
```php
95
+
class MyCompletionCommand extends CompletionCommand
96
+
{
97
+
protected function configureCompletion(CompletionHandler $handler)
98
+
{
99
+
$handler->addHandlers(array(
70
100
// Instances of Completion go here.
71
101
// See below for examples.
72
102
));
73
-
return $this->handler->runCompletion();
74
103
}
75
104
}
76
105
```
77
106
107
+
#### The `Completion` class
108
+
109
+
The following snippets demonstrate how the `Completion` class works with `CompletionHandler`, and some possible configurations. The examples are for an application with the signature:
110
+
111
+
`myapp (walk|run) [-w|--weather=""] direction`
112
+
113
+
78
114
##### Command-specific argument completion with an array
79
115
80
116
```php
81
-
$this->handler->addHandler(
117
+
$handler->addHandler(
82
118
new Completion(
83
-
'walk',
84
-
'direction',
85
-
Completion::TYPE_ARGUMENT,
86
-
array(
119
+
'walk', // match command name
120
+
'direction', // match argument/option name
121
+
Completion::TYPE_ARGUMENT, // match definition type (option/argument)
122
+
array( // array or callback for results
87
123
'north',
88
124
'east',
89
125
'south',
@@ -93,46 +129,48 @@ $this->handler->addHandler(
93
129
);
94
130
```
95
131
96
-
This will complete for this:
132
+
This will complete the `direction` argument for this:
133
+
97
134
```bash
98
135
$ myapp walk [tab]
99
136
```
100
137
101
138
but not this:
139
+
102
140
```bash
103
141
$ myapp run [tab]
104
142
```
105
143
106
144
##### Non-command-specific (global) argument completion with a function
107
145
108
146
```php
109
-
$this->handler->addHandler(
110
-
Completion::makeGlobalHandler(
147
+
$handler->addHandler(
148
+
new Completion(
149
+
Completion::ALL_COMMANDS,
111
150
'direction',
112
151
Completion::TYPE_ARGUMENT,
113
152
function() {
114
-
$values = array();
115
-
116
-
// Fill the array up with stuff
117
-
return $values;
153
+
return range(1, 10);
118
154
}
119
155
)
120
156
);
121
157
```
122
158
123
-
This will complete for both commands:
159
+
This will complete the `direction` argument for both commands:
160
+
124
161
```bash
125
162
$ myapp walk [tab]
126
163
$ myapp run [tab]
127
164
```
128
165
129
166
##### Option completion
130
167
131
-
Option handlers work the same way as argument handlers, except you use `Completion::TYPE_OPTION` for the type..
168
+
Option handlers work the same way as argument handlers, except you use `Completion::TYPE_OPTION` for the type.
132
169
133
170
```php
134
-
$this->handler->addHandler(
135
-
Completion::makeGlobalHandler(
171
+
$handler->addHandler(
172
+
new Completion(
173
+
Completion::ALL_COMMANDS,
136
174
'weather',
137
175
Completion::TYPE_OPTION,
138
176
array(
@@ -144,10 +182,30 @@ $this->handler->addHandler(
144
182
);
145
183
```
146
184
147
-
### Example: completing references from a Git repository
185
+
##### Completing the for both arguments and options
186
+
187
+
To have a completion run for both options and arguments matching the specified name, you can use the type `Completion::ALL_TYPES`. Combining this with `Completion::ALL_COMMANDS` and consistent option/argument naming throughout your application, it's easy to share completion behaviour between commands, options and arguments:
This library provides the completion class`ShellPathCompletion` which defers path completion to the shell's built-in path completion behaviour rather than implementing it in PHP.
222
+
This library provides the completion implementation`ShellPathCompletion` which defers path completion to the shell's built-in path completion behaviour rather than implementing it in PHP.
165
223
166
224
```php
167
225
new Completion\ShellPathCompletion(
@@ -176,3 +234,4 @@ new Completion\ShellPathCompletion(
176
234
177
235
* Option shortcuts are not offered as completion options, however requesting completion (ie. pressing tab) on a valid option shortcut will complete.
178
236
* Completion is not implemented for the `--option="value"` style of passing a value to an option, however `--option value` and `--option "value"` work and are functionally identical.
237
+
* Value completion is always run for options marked as `InputOption::VALUE_OPTIONAL` since there is currently no way to determine the desired behaviour from the command line contents (ie. skip the optional value or complete for it)
0 commit comments