yaffs.net Git - yaffs-website/blob - vendor/stecman/symfony-console-completion/README.md

   1 # BASH/ZSH auto-complete for Symfony Console applications
   2
   3 [![Build Status](https://travis-ci.org/stecman/symfony-console-completion.svg?branch=master)](https://travis-ci.org/stecman/symfony-console-completion)
   4 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/stecman/symfony-console-completion/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/stecman/symfony-console-completion/?branch=master)
   5
   6 [![Latest Stable Version](https://poser.pugx.org/stecman/symfony-console-completion/v/stable.png)](https://packagist.org/packages/stecman/symfony-console-completion)
   7 [![Total Downloads](https://poser.pugx.org/stecman/symfony-console-completion/downloads.png)](https://packagist.org/packages/stecman/symfony-console-completion)
   8 [![Latest Unstable Version](https://poser.pugx.org/stecman/symfony-console-completion/v/unstable.svg)](https://packagist.org/packages/stecman/symfony-console-completion)
   9 [![License](https://poser.pugx.org/stecman/symfony-console-completion/license.svg)](https://packagist.org/packages/stecman/symfony-console-completion)
  10
  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 argument and option values.
  12
  13 Example of zero-config use with Composer:
  14
  15 ![Composer BASH completion](https://i.imgur.com/MoDWkby.gif)
  16
  17 ## Zero-config use
  18
  19 If you don't need any custom completion behaviour, you can simply add the completion command to your application:
  20
  21 1. Install `stecman/symfony-console-completion` using [composer](https://getcomposer.org/) by running:
  22    ```
  23    $ composer require stecman/symfony-console-completion
  24    ```
  25
  26 2. For standalone Symfony Console applications, add an instance of `CompletionCommand` to your application's `Application::getDefaultCommands()` method:
  27
  28    ```php
  29    protected function getDefaultCommands()
  30    {
  31       //...
  32        $commands[] = new \Stecman\Component\Symfony\Console\BashCompletion\CompletionCommand();
  33       //...
  34    }
  35    ```
  36
  37    For Symfony Framework applications, register the `CompletionCommand` as a service in `app/config/services.yml`:
  38
  39    ```yaml
  40    services:
  41    #...
  42        console.completion_command:
  43          class: Stecman\Component\Symfony\Console\BashCompletion\CompletionCommand
  44          tags:
  45              -  { name: console.command }
  46    #...
  47    ```
  48
  49 3. Register completion for your application by running one of the following in a terminal, replacing `[program]` with the command you use to run your application (eg. 'composer'):
  50
  51    ```bash
  52    # BASH ~4.x, ZSH
  53    source <([program] _completion --generate-hook)
  54
  55    # BASH ~3.x, ZSH
  56    [program] _completion --generate-hook | source /dev/stdin
  57
  58    # BASH (any version)
  59    eval $([program] _completion --generate-hook)
  60    ```
  61
  62    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.
  63
  64 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`)
  65
  66 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.
  67
  68
  69 ## How it works
  70
  71 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 between the shell and 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.
  72
  73
  74 ## Defining value completions
  75
  76 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`.
  77
  78 ### Implementing `CompletionAwareInterface`
  79
  80 `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:
  81
  82 ```php
  83 class MyCommand extends Command implements CompletionAwareInterface
  84 {
  85     ...
  86
  87     public function completeOptionValues($optionName, CompletionContext $context)
  88     {
  89         if ($optionName == 'some-option') {
  90             return ['myvalue', 'other-value', 'word'];
  91         }
  92     }
  93
  94     public function completeArgumentValues($argumentName, CompletionContext $context)
  95     {
  96         if ($argumentName == 'package') {
  97             return $this->getPackageNamesFromDatabase($context->getCurrentWord());
  98         }
  99     }
 100 }
 101 ```
 102
 103 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`.
 104
 105
 106 ### Extending `CompletionCommand`
 107
 108 Argument and option value completions can also be defined by extending `CompletionCommand` and overriding the `configureCompletion` method:
 109
 110 ```php
 111 class MyCompletionCommand extends CompletionCommand
 112 {
 113     protected function configureCompletion(CompletionHandler $handler)
 114     {
 115         $handler->addHandlers([
 116             // Instances of Completion go here.
 117             // See below for examples.
 118         ]);
 119     }
 120 }
 121 ```
 122
 123 #### The `Completion` class
 124
 125 The following snippets demonstrate how the `Completion` class works with `CompletionHandler`, and some possible configurations. The examples are for an application with the signature:
 126
 127     `myapp (walk|run) [-w|--weather=""] direction`
 128
 129
 130 ##### Command-specific argument completion with an array
 131
 132 ```php
 133 $handler->addHandler(
 134     new Completion(
 135         'walk',                    // match command name
 136         'direction',               // match argument/option name
 137         Completion::TYPE_ARGUMENT, // match definition type (option/argument)
 138         [                     // array or callback for results
 139             'north',
 140             'east',
 141             'south',
 142             'west'
 143         ]
 144     )
 145 );
 146 ```
 147
 148 This will complete the `direction` argument for this:
 149
 150 ```bash
 151 $ myapp walk [tab]
 152 ```
 153
 154 but not this:
 155
 156 ```bash
 157 $ myapp run [tab]
 158 ```
 159
 160 ##### Non-command-specific (global) argument completion with a function
 161
 162 ```php
 163 $handler->addHandler(
 164     new Completion(
 165         Completion::ALL_COMMANDS,
 166         'direction',
 167         Completion::TYPE_ARGUMENT,
 168         function() {
 169             return range(1, 10);
 170         }
 171     )
 172 );
 173 ```
 174
 175 This will complete the `direction` argument for both commands:
 176
 177 ```bash
 178 $ myapp walk [tab]
 179 $ myapp run [tab]
 180 ```
 181
 182 ##### Option completion
 183
 184 Option handlers work the same way as argument handlers, except you use `Completion::TYPE_OPTION` for the type.
 185
 186 ```php
 187 $handler->addHandler(
 188     new Completion(
 189         Completion::ALL_COMMANDS,
 190         'weather',
 191         Completion::TYPE_OPTION,
 192         [
 193             'raining',
 194             'sunny',
 195             'everything is on fire!'
 196         ]
 197     )
 198 );
 199 ```
 200
 201 ##### Completing the for both arguments and options
 202
 203 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:
 204
 205 ```php
 206 $handler->addHandler(
 207     new Completion(
 208         Completion::ALL_COMMANDS,
 209         'pacakge',
 210         Completion::ALL_TYPES,
 211         function() {
 212             // ...
 213         }
 214     )
 215 );
 216 ```
 217
 218 ## Example completions
 219
 220 ### Completing references from a Git repository
 221
 222 ```php
 223 new Completion(
 224     Completion::ALL_COMMANDS,
 225     'ref',
 226     Completion::TYPE_OPTION,
 227     function () {
 228         $raw = shell_exec('git show-ref --abbr');
 229         if (preg_match_all('/refs\/(?:heads|tags)?\/?(.*)/', $raw, $matches)) {
 230             return $matches[1];
 231         }
 232     }
 233 )
 234 ```
 235
 236 ### Completing filesystem paths
 237
 238 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, so that users get the path completion behaviour they expect from their shell.
 239
 240 ```php
 241 new Completion\ShellPathCompletion(
 242     Completion::ALL_COMMANDS,
 243     'path',
 244     Completion::TYPE_OPTION
 245 )
 246
 247 ```
 248
 249 ## Behaviour notes
 250
 251 * Option shortcuts are not offered as completion options, however requesting completion (ie. pressing tab) on a valid option shortcut will complete.
 252 * 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.
 253 * 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)