Add functionality to defer to shell built-in filename completion

This change allows user to take advantage of the file/folder name completion
functions that are available under BASH and ZSH normally. Path completion
using ShellPathCompletion is currently only relative to the current working
directory and cannot be customised.

Ideally I'd like to be able to set the working directory for path completion,
and also to specify globs for matching say, only .txt files. Globs are
relatively straight forward to add using the _filedir/_path_files shell
functions we're using, however I couldn't find and nice way to change the
working directory for the functions without complexity or side-effects.

I've implemented deferring to the shell using an exit code. I'm not entirely
happy that this introduces code into the completion hooks that is specific
to ShellPathCompletion, however I'm less keen on the idea of allowing
dynamic injection of code into the shell hooks at the moment; that just seems
like a bad idea for some reason.

Summary of other changes:

* Adds interface for Completion
* BC break: removes CompletionCompletionHandler::isGlobal as it was fuzzy
  in meaning and can be represented better with an explicit comparison:

      $completion->getCommandName() == CompletionInterface::ALL_COMMANDS

Author: stecman

src/Completion.php

@@ -4,13 +4,10 @@
 namespace Stecman\Component\Symfony\Console\BashCompletion;
 
 
-class Completion {
-
-    const ALL_COMMANDS = null;
-
-    const TYPE_OPTION = 'option';
-    const TYPE_ARGUMENT = 'argument';
+use Stecman\Component\Symfony\Console\BashCompletion\Completion\CompletionInterface;
 
+class Completion implements CompletionInterface
+{
     /**
      * The option/argument name this helper should be run for
      * @var string
@@ -31,14 +28,15 @@ class Completion {
     protected $targetName;
 
     /**
-     * Array or Closure
-     * @var mixed
+     * Array of completion results or a callback to generate completion results
+     * The callback can be in any form accepted by call_user_func
+     * @var callable|array
      */
     protected $completion;
 
     public static function makeGlobalHandler($targetName, $type, $completion)
     {
-        return new Completion(self::ALL_COMMANDS, $targetName, $type, $completion);
+        return new Completion(CompletionInterface::ALL_COMMANDS, $targetName, $type, $completion);
     }
 
     public function __construct($commandName, $targetName, $type, $completion)
@@ -49,11 +47,6 @@ public function __construct($commandName, $targetName, $type, $completion)
         $this->completion = $completion;
     }
 
-    public function isGlobal()
-    {
-        return $this->commandName == '';
-    }
-
     /**
      * Return the result of the completion helper
      * @return array|mixed

src/Completion/CompletionInterface.php

@@ -0,0 +1,50 @@
+<?php
+
+
+namespace Stecman\Component\Symfony\Console\BashCompletion\Completion;
+
+
+interface CompletionInterface
+{
+    // Sugar for indicating that a Completion should run for all command names
+    // Intended to avoid a meaningless null parameter in the constructors of implementing classes
+    const ALL_COMMANDS = null;
+
+    const TYPE_OPTION = 'option';
+    const TYPE_ARGUMENT = 'argument';
+
+    /**
+     * Return the type of input completion should be run for
+     *
+     * @see \Symfony\Component\Console\Command\Command::addArgument
+     * @see \Symfony\Component\Console\Command\Command::addOption
+     * @return string - one of the CompletionInterface::TYPE_* constants
+     */
+    public function getType();
+
+    /**
+     * Return the name of the command completion should be run for
+     * If the return value is CompletionInterface::ALL_COMMANDS, the completion will be run for any command name
+     *
+     * @see \Symfony\Component\Console\Command\Command::setName
+     * @return string|null
+     */
+    public function getCommandName();
+
+    /**
+     * Return the option/argument name the completion should be run for
+     * CompletionInterface::getType determines whether the target name refers to an option or an argument
+     *
+     * @return string
+     */
+    public function getTargetName();
+
+    /**
+     * Execute the completion
+     *
+     * Returns an array of possible completions or null to indicate that no completions are available.
+     *
+     * @return array|null
+     */
+    public function run();
+}

src/Completion/ShellPathCompletion.php

@@ -0,0 +1,65 @@
+<?php
+
+
+namespace Stecman\Component\Symfony\Console\BashCompletion\Completion;
+
+/**
+ * Shell Path Completion
+ *
+ * Defers completion to the calling shell's built-in path completion functionality.
+ */
+class ShellPathCompletion implements CompletionInterface
+{
+    /**
+     * Exit code set up to trigger path completion in the completion hooks
+     * @see Stecman\Component\Symfony\Console\BashCompletion\HookFactory
+     */
+    const PATH_COMPLETION_EXIT_CODE = 200;
+
+    protected $type;
+
+    protected $commandName;
+
+    protected $targetName;
+
+    public function __construct($commandName, $targetName, $type)
+    {
+        $this->commandName = $commandName;
+        $this->targetName = $targetName;
+        $this->type = $type;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getType()
+    {
+        return $this->type;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getCommandName()
+    {
+        return $this->commandName;
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getTargetName()
+    {
+        return $this->targetName;
+    }
+
+    /**
+     * Exit with the status code configured to defer completion to the shell
+     *
+     * @see \Stecman\Component\Symfony\Console\BashCompletion\HookFactory::$hooks
+     */
+    public function run()
+    {
+        exit(self::PATH_COMPLETION_EXIT_CODE);
+    }
+}

src/CompletionHandler.php

@@ -2,6 +2,7 @@
 
 namespace Stecman\Component\Symfony\Console\BashCompletion;
 
+use Stecman\Component\Symfony\Console\BashCompletion\Completion\CompletionInterface;
 use Symfony\Component\Console\Application as BaseApplication;
 use Symfony\Component\Console\Command\Command as BaseCommand;
 use Symfony\Component\Console\Input\ArrayInput;
@@ -59,7 +60,7 @@ public function addHandlers($array)
         $this->helpers = array_merge($this->helpers, $array);
     }
 
-    public function addHandler(Completion $helper)
+    public function addHandler(CompletionInterface $helper)
     {
         $this->helpers[] = $helper;
     }
@@ -256,7 +257,7 @@ protected function formatArguments(BaseCommand $cmd)
     /**
      * @param $name
      * @param string $type
-     * @return Completion
+     * @return CompletionInterface
      */
     protected function getCompletionHelper($name, $type)
     {
@@ -265,7 +266,7 @@ protected function getCompletionHelper($name, $type)
                 continue;
             }
 
-            if ($helper->isGlobal() || $helper->getCommandName() == $this->command->getName()) {
+            if ($helper->getCommandName() == CompletionInterface::ALL_COMMANDS || $helper->getCommandName() == $this->command->getName()) {
                 if ($helper->getTargetName() == $name) {
                     return $helper;
                 }

src/HookFactory.php

@@ -37,16 +37,22 @@ function %%function_name%% {
     RESULT="$(%%completion_command%%)";
     STATUS=$?;
 
+    local cur;
+    _get_comp_words_by_ref -n : cur;
+
+    # Check if shell provided path completion is requested
+    # @see Completion\ShellPathCompletion
+    if [ $STATUS -eq 200 ]; then
+        _filedir;
+        return 0;
+
     # Bail out if PHP didn't exit cleanly
-    if [ $STATUS -ne 0 ]; then
+    elif [ $STATUS -ne 0 ]; then
         echo -e "$RESULT";
         return $?;
     fi;
 
-    local cur;
-    _get_comp_words_by_ref -n : cur;
-
-    COMPREPLY=(`compgen -W "$RESULT" -- \$cur`);
+    COMPREPLY=(`compgen -W "$RESULT" -- $cur`);
 
     __ltrim_colon_completions "$cur";
 };
@@ -70,8 +76,14 @@ function %%function_name%% {
     RESULT=("${(@f)$( %%completion_command%% )}")
     STATUS=$?;
 
+    # Check if shell provided path completion is requested
+    # @see Completion\ShellPathCompletion
+    if [ $STATUS -eq 200 ]; then
+        _path_files;
+        return 0;
+
     # Bail out if PHP didn't exit cleanly
-    if [ $STATUS -ne 0 ]; then
+    elif [ $STATUS -ne 0 ]; then
         echo -e "$RESULT";
         return $?;
     fi;