--- /dev/null
+<?php
+namespace Consolidation\AnnotatedCommand\Parser\Internal;
+
+use Consolidation\AnnotatedCommand\Parser\CommandInfo;
+use Consolidation\AnnotatedCommand\Parser\DefaultsWithDescriptions;
+
+/**
+ * Given a class and method name, parse the annotations in the
+ * DocBlock comment, and provide accessor methods for all of
+ * the elements that are needed to create an annotated Command.
+ */
+abstract class AbstractCommandDocBlockParser
+{
+ /**
+ * @var CommandInfo
+ */
+ protected $commandInfo;
+
+ /**
+ * @var \ReflectionMethod
+ */
+ protected $reflection;
+
+ /**
+ * @var string
+ */
+ protected $optionParamName;
+
+ /**
+ * @var array
+ */
+ protected $tagProcessors = [
+ 'command' => 'processCommandTag',
+ 'name' => 'processCommandTag',
+ 'arg' => 'processArgumentTag',
+ 'param' => 'processParamTag',
+ 'return' => 'processReturnTag',
+ 'option' => 'processOptionTag',
+ 'default' => 'processDefaultTag',
+ 'aliases' => 'processAliases',
+ 'usage' => 'processUsageTag',
+ 'description' => 'processAlternateDescriptionTag',
+ 'desc' => 'processAlternateDescriptionTag',
+ ];
+
+ public function __construct(CommandInfo $commandInfo, \ReflectionMethod $reflection)
+ {
+ $this->commandInfo = $commandInfo;
+ $this->reflection = $reflection;
+ }
+
+ protected function processAllTags($phpdoc)
+ {
+ // Iterate over all of the tags, and process them as necessary.
+ foreach ($phpdoc->getTags() as $tag) {
+ $processFn = [$this, 'processGenericTag'];
+ if (array_key_exists($tag->getName(), $this->tagProcessors)) {
+ $processFn = [$this, $this->tagProcessors[$tag->getName()]];
+ }
+ $processFn($tag);
+ }
+ }
+
+ abstract protected function getTagContents($tag);
+
+ /**
+ * Parse the docBlock comment for this command, and set the
+ * fields of this class with the data thereby obtained.
+ */
+ abstract public function parse();
+
+ /**
+ * Save any tag that we do not explicitly recognize in the
+ * 'otherAnnotations' map.
+ */
+ protected function processGenericTag($tag)
+ {
+ $this->commandInfo->addAnnotation($tag->getName(), $this->getTagContents($tag));
+ }
+
+ /**
+ * Set the name of the command from a @command or @name annotation.
+ */
+ protected function processCommandTag($tag)
+ {
+ $commandName = $this->getTagContents($tag);
+ $this->commandInfo->setName($commandName);
+ // We also store the name in the 'other annotations' so that is is
+ // possible to determine if the method had a @command annotation.
+ $this->commandInfo->addAnnotation($tag->getName(), $commandName);
+ }
+
+ /**
+ * The @description and @desc annotations may be used in
+ * place of the synopsis (which we call 'description').
+ * This is discouraged.
+ *
+ * @deprecated
+ */
+ protected function processAlternateDescriptionTag($tag)
+ {
+ $this->commandInfo->setDescription($this->getTagContents($tag));
+ }
+
+ /**
+ * Store the data from a @arg annotation in our argument descriptions.
+ */
+ protected function processArgumentTag($tag)
+ {
+ 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)
+ {
+ if (!$this->pregMatchOptionNameAndDescription((string)$tag->getDescription(), $match)) {
+ return;
+ }
+ $this->addOptionOrArgumentTag($tag, $this->commandInfo->options(), $match);
+ }
+
+ protected function addOptionOrArgumentTag($tag, DefaultsWithDescriptions $set, $nameAndDescription)
+ {
+ $variableName = $this->commandInfo->findMatchingOption($nameAndDescription['name']);
+ $desc = $nameAndDescription['description'];
+ $description = static::removeLineBreaks($desc);
+ $set->add($variableName, $description);
+ }
+
+ /**
+ * Store the data from a @default annotation in our argument or option store,
+ * as appropriate.
+ */
+ protected function processDefaultTag($tag)
+ {
+ if (!$this->pregMatchNameAndDescription((string)$tag->getDescription(), $match)) {
+ return;
+ }
+ $variableName = $match['name'];
+ $defaultValue = $this->interpretDefaultValue($match['description']);
+ if ($this->commandInfo->arguments()->exists($variableName)) {
+ $this->commandInfo->arguments()->setDefaultValue($variableName, $defaultValue);
+ return;
+ }
+ $variableName = $this->commandInfo->findMatchingOption($variableName);
+ if ($this->commandInfo->options()->exists($variableName)) {
+ $this->commandInfo->options()->setDefaultValue($variableName, $defaultValue);
+ }
+ }
+
+ /**
+ * Store the data from a @usage annotation in our example usage list.
+ */
+ protected function processUsageTag($tag)
+ {
+ $lines = explode("\n", $this->getTagContents($tag));
+ $usage = array_shift($lines);
+ $description = static::removeLineBreaks(implode("\n", $lines));
+
+ $this->commandInfo->setExampleUsage($usage, $description);
+ }
+
+ /**
+ * Process the comma-separated list of aliases
+ */
+ protected function processAliases($tag)
+ {
+ $this->commandInfo->setAliases((string)$tag->getDescription());
+ }
+
+ protected function lastParameterName()
+ {
+ $params = $this->commandInfo->getParameters();
+ $param = end($params);
+ if (!$param) {
+ return '';
+ }
+ return $param->name;
+ }
+
+ /**
+ * Return the name of the last parameter if it holds the options.
+ */
+ public function optionParamName()
+ {
+ // Remember the name of the last parameter, if it holds the options.
+ // We will use this information to ignore @param annotations for the options.
+ if (!isset($this->optionParamName)) {
+ $this->optionParamName = '';
+ $options = $this->commandInfo->options();
+ if (!$options->isEmpty()) {
+ $this->optionParamName = $this->lastParameterName();
+ }
+ }
+
+ return $this->optionParamName;
+ }
+
+ /**
+ * Store the data from a @param annotation in our argument descriptions.
+ */
+ protected function processParamTag($tag)
+ {
+ $variableName = $tag->getVariableName();
+ $variableName = str_replace('$', '', $variableName);
+ $description = static::removeLineBreaks((string)$tag->getDescription());
+ if ($variableName == $this->optionParamName()) {
+ return;
+ }
+ $this->commandInfo->arguments()->add($variableName, $description);
+ }
+
+ /**
+ * Store the data from a @return annotation in our argument descriptions.
+ */
+ abstract protected function processReturnTag($tag);
+
+ protected function interpretDefaultValue($defaultValue)
+ {
+ $defaults = [
+ 'null' => null,
+ 'true' => true,
+ 'false' => false,
+ "''" => '',
+ '[]' => [],
+ ];
+ foreach ($defaults as $defaultName => $defaultTypedValue) {
+ if ($defaultValue == $defaultName) {
+ return $defaultTypedValue;
+ }
+ }
+ return $defaultValue;
+ }
+
+ /**
+ * Given a docblock description in the form "$variable description",
+ * return the variable name and description via the 'match' parameter.
+ */
+ protected function pregMatchNameAndDescription($source, &$match)
+ {
+ $nameRegEx = '\\$(?P<name>[^ \t]+)[ \t]+';
+ $descriptionRegEx = '(?P<description>.*)';
+ $optionRegEx = "/{$nameRegEx}{$descriptionRegEx}/s";
+
+ 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.
+ */
+ protected static function convertListToCommaSeparated($text)
+ {
+ return preg_replace('#[ \t\n\r,]+#', ',', $text);
+ }
+
+ /**
+ * Take a multiline description and convert it into a single
+ * long unbroken line.
+ */
+ protected static function removeLineBreaks($text)
+ {
+ return trim(preg_replace('#[ \t\n\r]+#', ' ', $text));
+ }
+}
projects / yaffs-website / blobdiff