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
# BASH completion for Symfony Console applications
2
2
3
-
This package provides automatic BASH completion for Symfony Console Component based applications. With minimal 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.
3
+
This package provides automatic BASH completion 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.
4
4
5
-
## Basic use
5
+
Example of zero-config use with Composer:
6
6
7
-
If you don't need any custom completion behaviour:
If you don't need any custom completion behaviour, all you need to do is add the completion command to your application's available commands:
8
12
9
13
1. Install `stecman/symfony-console-completion` through composer
10
-
2. Add an instance of `CompletionCommand` to your application's `Application::getDefaultCommands()`:
14
+
2. Add an instance of `CompletionCommand` to your application's `Application::getDefaultCommands()` method:
11
15
```
12
16
protected function getDefaultCommands()
13
17
{
@@ -17,12 +21,15 @@ If you don't need any custom completion behaviour:
17
21
}
18
22
```
19
23
20
-
3. Run `eval $([program] _completion -g)` in a terminal.
21
-
4. Add the above command to your bash profile if you want the completion to apply automatically for new terminal sessions.
24
+
3. Run `eval $([program] _completion --generate-hook)` in a terminal, replacing `[program]` with the command you use to run your application (eg. 'composer'). 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.
25
+
4. Add the command from step 3 to your bash profile if you want the completion to apply automatically for all new terminal sessions.
26
+
27
+
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]`.
28
+
29
+
### How it works
22
30
23
-
The `-g` option generates a few lines of bash that, when run, register your application as a completion handler for your program name. Completion is handled by running the completion command on your application with no arguments: `[program] _completion`.
31
+
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.
24
32
25
-
If you need to use completion with an alias, specify the program name to complete for with the `-p` option: `_completion -g -p [alias-name]`.
26
33
27
34
## Custom completion
28
35
@@ -34,25 +41,27 @@ The following examples are for an application with this signature: `myapp (walk|
34
41
35
42
protected function runCompletion()
36
43
{
37
-
$handler = $this->handler;
38
-
$handler->addHandlers(array(
44
+
$this->handler->addHandlers(array(
39
45
40
-
... // See below for what goes in here
46
+
// Instances of Completion go here.
47
+
// See below for examples.
41
48
42
49
));
43
50
44
-
return $handler->runCompletion();
51
+
return $this->handler->runCompletion();
45
52
}
46
53
47
54
}
48
55
49
56
50
57
**Command-specific argument completion with an array:**
51
-
52
-
new Completion(
53
-
'walk', 'direction', Completion::TYPE_ARGUMENT,
54
-
array('north', 'east', 'south', 'west')
55
-
)
58
+
59
+
$this->handler->addHandler(
60
+
new Completion(
61
+
'walk', 'direction', Completion::TYPE_ARGUMENT,
62
+
array('north', 'east', 'south', 'west')
63
+
)
64
+
);
56
65
57
66
This will complete for this:
58
67
@@ -65,16 +74,18 @@ but not this:
65
74
66
75
**Non-command-specific (global) argument completion with a function**
67
76
68
-
Completion::makeGlobalHandler(
69
-
'direction', Completion::TYPE_ARGUMENT,
70
-
function(){
71
-
$values = array();
77
+
$this->handler->addHandler(
78
+
Completion::makeGlobalHandler(
79
+
'direction', Completion::TYPE_ARGUMENT,
80
+
function(){
81
+
$values = array();
72
82
73
-
// Fill the array up with stuff
83
+
// Fill the array up with stuff
74
84
75
-
return $values;
76
-
}
77
-
)
85
+
return $values;
86
+
}
87
+
)
88
+
);
78
89
79
90
This will complete for both commands:
80
91
@@ -86,16 +97,29 @@ This will complete for both commands:
86
97
87
98
Option handlers work the same way as argument handlers, except you use `Completion::TYPE_OPTION` for the type..
88
99
89
-
Completion::makeGlobalHandler(
90
-
'weather', Completion::TYPE_OPTION,
91
-
array('raining', 'sunny', 'everything is on fire!')
92
-
)
100
+
$this->handler->addHandler(
101
+
Completion::makeGlobalHandler(
102
+
'weather', Completion::TYPE_OPTION,
103
+
array('raining', 'sunny', 'everything is on fire!')
104
+
)
105
+
);
106
+
93
107
94
-
Option completion is only supported for non-quoted values currently:
108
+
### Example: completing references from a Git repository
95
109
96
-
myapp walk -w [tab]
97
-
myapp walk --weather [tab]
110
+
Completion::makeGlobalHandler(
111
+
'ref',
112
+
Completion::TYPE_OPTION,
113
+
function () {
114
+
$raw = shell_exec('git show-ref --abbr');
115
+
if (preg_match_all('/refs\/(?:heads|tags)?\/?(.*)/', $raw, $matches)) {
116
+
return $matches[1];
117
+
}
118
+
}
119
+
)
98
120
99
-
## Notes
121
+
## Behaviour notes
100
122
101
-
* Option shorcuts are not offered as completion options, however requesting completion (ie. pressing tab) on a valid option shortcut will complete.
123
+
* Option shortcuts are not offered as completion options, however requesting completion (ie. pressing tab) on a valid option shortcut will complete.
124
+
* 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.
125
+
* There is currently no way to hand-off to BASH to complete folder/file names.
0 commit comments