Escape completion results for BASH before writing to stdout

In the previous commit I used `printf '%q'` in the BASH hook to handle escaping
unquoted strings, however this didn't handle escaping quote characters inside
strings where needed. This commit moves the responsibility of escaping completion
results into PHP to make the escaping logic testable and easier to maintain.

BASH supports automatic escaping/quoting in completion results only when the
`-o filenames` option is used to register a completion function. The `filenames`
option has behaviour that is incompatible with a generic completion handler,
such as appending a `/` on results that happen to match directory name in the CWD.
Unfortuntately this means we cannot use this functionality. There is no API to
change this behaviour as far as I've been able to see from the BASH docs and
source code.

ZSH handles escaping of completion functions perfectly fine out of the box.

Author: stecman

src/CompletionCommand.php

@@ -76,7 +76,54 @@ protected function execute(InputInterface $input, OutputInterface $output)
             $output->write($hook, true);
         } else {
             $handler->setContext(new EnvironmentCompletionContext());
-            $output->write($this->runCompletion(), true);
+
+            // Get completion results
+            $results = $this->runCompletion();
+
+            // Escape results for the current shell
+            $shellType = $input->getOption('shell-type') ?: $this->getShellType();
+
+            foreach ($results as &$result) {
+                $result = $this->escapeForShell($result, $shellType);
+            }
+
+            $output->write($results, true);
+        }
+    }
+
+    /**
+     * Escape each completion result for the specified shell
+     *
+     * @param string $result - Completion results that should appear in the shell
+     * @param string $shellType - Valid shell type from HookFactory
+     * @return string
+     */
+    protected function escapeForShell($result, $shellType)
+    {
+        switch ($shellType) {
+            // BASH requires special escaping for multi-word and special character results
+            // This emulates registering completion with`-o filenames`, without side-effects like dir name slashes
+            case 'bash':
+                $context = $this->handler->getContext();
+                $wordStart = substr($context->getRawCurrentWord(), 0, 1);
+
+                if ($wordStart == "'") {
+                    // If the current word is single-quoted, escape any single quotes in the result
+                    $result = str_replace("'", "\\'", $result);
+                } else if ($wordStart == '"') {
+                    // If the current word is double-quoted, escape any double quotes in the result
+                    $result = str_replace('"', '\\"', $result);
+                } else {
+                    // Otherwise assume the string is unquoted and word breaks should be escaped
+                    $result = preg_replace('/([\s\'"\\\\])/', '\\\\$1', $result);
+                }
+
+                // Escape output to prevent special characters being lost when passing results to compgen
+                return escapeshellarg($result);
+
+            // No transformation by default
+            default:
+                return $result;
         }
     }
 

src/CompletionContext.php

@@ -32,17 +32,27 @@ class CompletionContext
     protected $charIndex = 0;
 
     /**
-     * An array containing the individual words in the current command line.
+     * An array of the individual words in the current command line.
      *
      * This is not set until $this->splitCommand() is called, when it is populated by
      * $commandLine exploded by $wordBreaks
      *
      * Bash equivalent: COMP_WORDS
      *
-     * @var array|null
+     * @var string[]|null
      */
     protected $words = null;
 
+    /**
+     * Words from the currently command-line before quotes and escaping is processed
+     *
+     * This is indexed the same as $this->words, but in their raw input terms are in their input form, including
+     * quotes and escaping.
+     *
+     * @var string[]|null
+     */
+    protected $rawWords = null;
+
     /**
      * The index in $this->words containing the word at the current cursor position.
      *
@@ -101,6 +111,22 @@ public function getCurrentWord()
         return '';
     }
 
+    /**
+     * Return the unprocessed string for the word under the cursor
+     *
+     * This preserves any quotes and escaping that are present in the input command line.
+     *
+     * @return string
+     */
+    public function getRawCurrentWord()
+    {
+        if (isset($this->rawWords[$this->wordIndex])) {
+            return $this->rawWords[$this->wordIndex];
+        }
+
+        return '';
+    }
+
     /**
      * Return a word by index from the command line
      *
@@ -132,6 +158,22 @@ public function getWords()
         return $this->words;
     }
 
+    /**
+     * Get the unprocessed/literal words from the command line
+     *
+     * This is indexed the same as getWords(), but preserves any quoting and escaping from the command line
+     *
+     * @return string[]
+     */
+    public function getRawWords()
+    {
+        if ($this->rawWords === null) {
+            $this->splitCommand();
+        }
+
+        return $this->rawWords;
+    }
+
     /**
      * Get the index of the word the cursor is currently in
      *
@@ -202,6 +244,7 @@ protected function splitCommand()
         foreach ($tokens as $token) {
             if ($token['type'] != 'break') {
                 $this->words[] = $this->getTokenValue($token);
+                $this->rawWords[] = $token['value'];
             }
 
             // Determine which word index the cursor is inside once we reach it's offset
@@ -213,16 +256,22 @@ protected function splitCommand()
                     // Push an empty word at the cursor to allow completion of new terms at the cursor, ignoring words ahead
                     $this->wordIndex++;
                     $this->words[] = '';
+                    $this->rawWords[] = '';
                     continue;
                 }
 
                 if ($this->charIndex < $token['offsetEnd']) {
-                    // Cursor is inside the current word - truncate the word at the cursor
-                    // (This emulates normal BASH completion behaviour I've observed, though I'm not entirely sure if it's useful)
+                    // Cursor is inside the current word - truncate the word at the cursor to complete on
+                    // This emulates BASH completion's behaviour with COMP_CWORD
+
+                    // Create a copy of the token with its value truncated
+                    $truncatedToken = $token;
                     $relativeOffset = $this->charIndex - $token['offset'];
-                    $truncated = substr($token['value'], 0, $relativeOffset);
+                    $truncatedToken['value'] = substr($token['value'], 0, $relativeOffset);
 
-                    $this->words[$this->wordIndex] = $truncated;
+                    // Replace the current word with the truncated value
+                    $this->words[$this->wordIndex] = $this->getTokenValue($truncatedToken);
+                    $this->rawWords[$this->wordIndex] = $truncatedToken['value'];
                 }
             }
         }
@@ -231,6 +280,7 @@ protected function splitCommand()
         if ($this->wordIndex === null) {
             $this->wordIndex = count($this->words);
             $this->words[] = '';
+            $this->rawWords[] = '';
         }
     }
 

src/HookFactory.php

@@ -68,11 +68,6 @@ function %%function_name%% {
 
     COMPREPLY=(`compgen -W "$RESULT" -- $cur`);
 
-    # Escape any spaces in results if the current word doesn't begin with a quote
-    if [[ ! -z $COMPREPLY  ]] && [[ ! $cur =~ ^[\'\"] ]]; then
-        COMPREPLY=($(printf '%q\n' "${COMPREPLY[@]}"));
-    fi;
-
     __ltrim_colon_completions "$cur";
 
     MAILCHECK=mail_check_backup;
@@ -156,6 +151,9 @@ public function generateHook($type, $programPath, $programName = null, $multiple
             $completionCommand = $programPath . ' _completion';
         }
 
+        // Pass shell type during completion so output can be encoded if the shell requires it
+        $completionCommand .= " --shell-type $type";
+
         return str_replace(
             array(
                 '%%function_name%%',

tests/Stecman/Component/Symfony/Console/BashCompletion/CompletionContextTest.php

@@ -96,9 +96,9 @@ public function testQuotedStringWordBreaking()
     {
         $context = new CompletionContext();
         $context->setCharIndex(1000);
-        $context->setCommandLine('make horse --legs=3 --name="Jeff the horse" --colour Extreme\ Blanc \'foo " bar\'');
+        $context->setCommandLine('make horse --legs=3 --name="Jeff the horse" --colour Extreme\\ Blanc \'foo " bar\'');
 
-        // Ensure spaces and quotes
+        // Ensure spaces and quotes are processed correctly
         $this->assertEquals(
             array(
                 'make',
@@ -115,6 +115,23 @@ public function testQuotedStringWordBreaking()
             $context->getWords()
         );
 
+        // Confirm the raw versions of the words are indexed correctly
+        $this->assertEquals(
+            array(
+                'make',
+                'horse',
+                '--legs',
+                '3',
+                '--name',
+                '"Jeff the horse"',
+                '--colour',
+                'Extreme\\ Blanc',
+                "'foo \" bar'",
+                '',
+            ),
+            $context->getRawWords()
+        );
+
         $context = new CompletionContext();
         $context->setCommandLine('console --tag=');
 
@@ -130,6 +147,18 @@ public function testQuotedStringWordBreaking()
         );
     }
 
+    public function testGetRawCurrentWord()
+    {
+        $context = new CompletionContext();
+
+        $context->setCommandLine('cmd "double quoted" --option \'value\'');
+        $context->setCharIndex(13);
+        $this->assertEquals(1, $context->getWordIndex());
+
+        $this->assertEquals(array('cmd', '"double q', '--option', "'value'"), $context->getRawWords());
+        $this->assertEquals('"double q', $context->getRawCurrentWord());
+    }
+
     public function testConfigureFromEnvironment()
     {
         putenv("CMDLINE_CONTENTS=beam up li");