Merge 17c95e6 into f3dcc08

CHANGELOG.md

@@ -8,6 +8,7 @@
 - **Breaking** The Symfony Command Event hook has been renamed to COMMAND_EVENT.  There is a new COMMAND hook that behaves like the existing Drush command hook (i.e. the post-command event is called after the primary command method runs).
 - Add an accessor function AnnotatedCommandFactory::setIncludeAllPublicMethods() to control whether all public methods of a command class, or only those with a @command annotation will be treated as commands. Default remains to treat all public methods as commands. The parameters to AnnotatedCommandFactory::createCommandsFromClass() and AnnotatedCommandFactory::createCommandsFromClassInfo() still behave the same way, but are deprecated. If omitted, the value set by the accessor will be used.
 - @option and @usage annotations provided with @hook methods will be added to the help text of the command they hook.  This should be done if a hook needs to add a new option, e.g. to control the behavior of the hook.
+- @option annotations can now be either `@option type $name description`, or just `@option name description`.
 - @hook option can be used to programatically add options to a command.
 - If a --field option is given, it will also force the output format to 'string'.
 - Removed PassThroughArgsInput. This class was unnecessary.

README.md

@@ -47,7 +47,7 @@ class MyCommandClass
      * @command my:cat
      * @param integer $one The first parameter.
      * @param integer $two The other parameter.
-     * @option $flip Whether or not the second parameter should come first in the result.
+     * @option flip Whether or not the second parameter should come first in the result.
      * @aliases c
      * @usage bet alpha --flip
      *   Concatenate "alpha" and "bet".

src/Parser/Internal/AbstractCommandDocBlockParser.php

@@ -102,24 +102,27 @@ protected function processAlternateDescriptionTag($tag)
      */
     protected function processArgumentTag($tag)
     {
-        $this->addOptionOrArgumentTag($tag, $this->commandInfo->arguments());
+        if (!$this->pregMatchNameAndDescription((string)$tag->getDescription(), $match)) {
+            return;
+        }
+        $this->addOptionOrArgumentTag($tag, $this->commandInfo->arguments(), $match);
     }
 
     /**
      * Store the data from an @option annotation in our option descriptions.
      */
     protected function processOptionTag($tag)
     {
-        $this->addOptionOrArgumentTag($tag, $this->commandInfo->options());
+        if (!$this->pregMatchOptionNameAndDescription((string)$tag->getDescription(), $match)) {
+            return;
+        }
+        $this->addOptionOrArgumentTag($tag, $this->commandInfo->options(), $match);
     }
 
-    protected function addOptionOrArgumentTag($tag, DefaultsWithDescriptions $set)
+    protected function addOptionOrArgumentTag($tag, DefaultsWithDescriptions $set, $nameAndDescription)
     {
-        if (!$this->pregMatchNameAndDescription((string)$tag->getDescription(), $match)) {
-            return;
-        }
-        $variableName = $this->commandInfo->findMatchingOption($match['name']);
-        $desc = $match['description'];
+        $variableName = $this->commandInfo->findMatchingOption($nameAndDescription['name']);
+        $desc = $nameAndDescription['description'];
         $description = static::removeLineBreaks($desc);
         $set->add($variableName, $description);
     }
@@ -214,6 +217,21 @@ protected function pregMatchNameAndDescription($source, &$match)
         return preg_match($optionRegEx, $source, $match);
     }
 
+    /**
+     * Given a docblock description in the form "$variable description",
+     * return the variable name and description via the 'match' parameter.
+     */
+    protected function pregMatchOptionNameAndDescription($source, &$match)
+    {
+        // Strip type and $ from the text before the @option name, if present.
+        $source = preg_replace('/^[a-zA-Z]* ?\\$/', '', $source);
+        $nameRegEx = '(?P<name>[^ \t]+)[ \t]+';
+        $descriptionRegEx = '(?P<description>.*)';
+        $optionRegEx = "/{$nameRegEx}{$descriptionRegEx}/s";
+
+        return preg_match($optionRegEx, $source, $match);
+    }
+
     /**
      * Given a list that might be 'a b c' or 'a, b, c' or 'a,b,c',
      * convert the data into the last of these forms.

src/Parser/Internal/CommandDocBlockParser2.php

@@ -40,7 +40,10 @@ protected function getTagContents($tag)
      */
     protected function processArgumentTag($tag)
     {
-        $this->addOptionOrArgumentTag($tag, $this->commandInfo->arguments());
+        if (!$this->pregMatchNameAndDescription((string)$tag->getDescription(), $match)) {
+            return;
+        }
+        $this->addOptionOrArgumentTag($tag, $this->commandInfo->arguments(), $match);
     }
 
     /**

tests/src/ExampleCommandFile.php

@@ -93,7 +93,7 @@ public function commandWithNoOptions($one, $two = 'default')
      *
      * Return a result only if not silent.
      *
-     * @option $silent Supress output.
+     * @option silent Supress output.
      */
     public function commandWithNoArguments($opts = ['silent|s' => false])
     {
@@ -108,7 +108,7 @@ public function commandWithNoArguments($opts = ['silent|s' => false])
      * This command defines the option shortcut on the annotation instead of in the options array.
      *
      * @param $opts The options
-     * @option $silent|s Supress output.
+     * @option silent|s Supress output.
      */
     public function shortcutOnAnnotation($opts = ['silent' => false])
     {
@@ -126,7 +126,7 @@ public function shortcutOnAnnotation($opts = ['silent' => false])
      * @command test:arithmatic
      * @param integer $one The first number to add.
      * @param integer $two The other number to add.
-     * @option $negate Whether or not the result should be negated.
+     * @option negate Whether or not the result should be negated.
      * @aliases arithmatic
      * @usage 2 2 --negate
      *   Add two plus two and then negate.

tests/src/alpha/AlphaCommandFile.php

@@ -109,7 +109,7 @@ public function additionalOptionForExampleTable($command, $annotationData)
      * Demonstrate an alter hook with an option
      *
      * @hook alter example:table
-     * @option $french Add a row with French numbers.
+     * @option french Add a row with French numbers.
      * @usage example:table --french
      */
     public function alterFormatters($result, array $args, AnnotationData $annotationData)
@@ -191,7 +191,7 @@ public function withoutAnnotations()
      *
      * Return a result only if not silent.
      *
-     * @option $silent Supress output.
+     * @option silent Supress output.
      */
     public function commandWithOneOptionalArgument($who = 'world', $opts = ['silent|s' => false])
     {

tests/src/beta/BetaCommandFile.php

@@ -21,7 +21,7 @@ public function unavailableCommand()
      * Demonstrate an alter hook with an option
      *
      * @hook alter example:table
-     * @option $chinese Add a row with Chinese numbers.
+     * @option chinese Add a row with Chinese numbers.
      * @usage example:table --chinese
      */
     public function alterFormattersChinese($result, array $args, AnnotationData $annotationData)
@@ -37,7 +37,7 @@ public function alterFormattersChinese($result, array $args, AnnotationData $ann
      * Demonstrate an alter hook with an option
      *
      * @hook alter *
-     * @option $kanji Add a row with Kanji numbers.
+     * @option kanji Add a row with Kanji numbers.
      * @usage example:table --kanji
      */
     public function alterFormattersKanji($result, array $args, AnnotationData $annotationData)