[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /*
   4   * This file is part of the Symfony package.
   5   *
   6   * (c) Fabien Potencier <fabien@symfony.com>
   7   *
   8   * For the full copyright and license information, please view the LICENSE
   9   * file that was distributed with this source code.
  10   */
  11  
  12  namespace Symfony\Component\Console\Descriptor;
  13  
  14  use Symfony\Component\Console\Application;
  15  use Symfony\Component\Console\Command\Command;
  16  use Symfony\Component\Console\Helper\Helper;
  17  use Symfony\Component\Console\Input\InputArgument;
  18  use Symfony\Component\Console\Input\InputDefinition;
  19  use Symfony\Component\Console\Input\InputOption;
  20  use Symfony\Component\Console\Output\OutputInterface;
  21  
  22  /**
  23   * Markdown descriptor.
  24   *
  25   * @author Jean-François Simon <contact@jfsimon.fr>
  26   *
  27   * @internal
  28   */
  29  class MarkdownDescriptor extends Descriptor
  30  {
  31      /**
  32       * {@inheritdoc}
  33       */
  34      public function describe(OutputInterface $output, $object, array $options = [])
  35      {
  36          $decorated = $output->isDecorated();
  37          $output->setDecorated(false);
  38  
  39          parent::describe($output, $object, $options);
  40  
  41          $output->setDecorated($decorated);
  42      }
  43  
  44      /**
  45       * {@inheritdoc}
  46       */
  47      protected function write($content, $decorated = true)
  48      {
  49          parent::write($content, $decorated);
  50      }
  51  
  52      /**
  53       * {@inheritdoc}
  54       */
  55      protected function describeInputArgument(InputArgument $argument, array $options = [])
  56      {
  57          $this->write(
  58              '#### `'.($argument->getName() ?: '<none>')."`\n\n"
  59              .($argument->getDescription() ? preg_replace('/\s*[\r\n]\s*/', "\n", $argument->getDescription())."\n\n" : '')
  60              .'* Is required: '.($argument->isRequired() ? 'yes' : 'no')."\n"
  61              .'* Is array: '.($argument->isArray() ? 'yes' : 'no')."\n"
  62              .'* Default: `'.str_replace("\n", '', var_export($argument->getDefault(), true)).'`'
  63          );
  64      }
  65  
  66      /**
  67       * {@inheritdoc}
  68       */
  69      protected function describeInputOption(InputOption $option, array $options = [])
  70      {
  71          $name = '--'.$option->getName();
  72          if ($option->getShortcut()) {
  73              $name .= '|-'.str_replace('|', '|-', $option->getShortcut()).'';
  74          }
  75  
  76          $this->write(
  77              '#### `'.$name.'`'."\n\n"
  78              .($option->getDescription() ? preg_replace('/\s*[\r\n]\s*/', "\n", $option->getDescription())."\n\n" : '')
  79              .'* Accept value: '.($option->acceptValue() ? 'yes' : 'no')."\n"
  80              .'* Is value required: '.($option->isValueRequired() ? 'yes' : 'no')."\n"
  81              .'* Is multiple: '.($option->isArray() ? 'yes' : 'no')."\n"
  82              .'* Default: `'.str_replace("\n", '', var_export($option->getDefault(), true)).'`'
  83          );
  84      }
  85  
  86      /**
  87       * {@inheritdoc}
  88       */
  89      protected function describeInputDefinition(InputDefinition $definition, array $options = [])
  90      {
  91          if ($showArguments = \count($definition->getArguments()) > 0) {
  92              $this->write('### Arguments');
  93              foreach ($definition->getArguments() as $argument) {
  94                  $this->write("\n\n");
  95                  $this->write($this->describeInputArgument($argument));
  96              }
  97          }
  98  
  99          if (\count($definition->getOptions()) > 0) {
 100              if ($showArguments) {
 101                  $this->write("\n\n");
 102              }
 103  
 104              $this->write('### Options');
 105              foreach ($definition->getOptions() as $option) {
 106                  $this->write("\n\n");
 107                  $this->write($this->describeInputOption($option));
 108              }
 109          }
 110      }
 111  
 112      /**
 113       * {@inheritdoc}
 114       */
 115      protected function describeCommand(Command $command, array $options = [])
 116      {
 117          $command->getSynopsis();
 118          $command->mergeApplicationDefinition(false);
 119  
 120          $this->write(
 121              '`'.$command->getName()."`\n"
 122              .str_repeat('-', Helper::strlen($command->getName()) + 2)."\n\n"
 123              .($command->getDescription() ? $command->getDescription()."\n\n" : '')
 124              .'### Usage'."\n\n"
 125              .array_reduce(array_merge([$command->getSynopsis()], $command->getAliases(), $command->getUsages()), function ($carry, $usage) {
 126                  return $carry.'* `'.$usage.'`'."\n";
 127              })
 128          );
 129  
 130          if ($help = $command->getProcessedHelp()) {
 131              $this->write("\n");
 132              $this->write($help);
 133          }
 134  
 135          if ($command->getNativeDefinition()) {
 136              $this->write("\n\n");
 137              $this->describeInputDefinition($command->getNativeDefinition());
 138          }
 139      }
 140  
 141      /**
 142       * {@inheritdoc}
 143       */
 144      protected function describeApplication(Application $application, array $options = [])
 145      {
 146          $describedNamespace = isset($options['namespace']) ? $options['namespace'] : null;
 147          $description = new ApplicationDescription($application, $describedNamespace);
 148          $title = $this->getApplicationTitle($application);
 149  
 150          $this->write($title."\n".str_repeat('=', Helper::strlen($title)));
 151  
 152          foreach ($description->getNamespaces() as $namespace) {
 153              if (ApplicationDescription::GLOBAL_NAMESPACE !== $namespace['id']) {
 154                  $this->write("\n\n");
 155                  $this->write('**'.$namespace['id'].':**');
 156              }
 157  
 158              $this->write("\n\n");
 159              $this->write(implode("\n", array_map(function ($commandName) use ($description) {
 160                  return sprintf('* [`%s`](#%s)', $commandName, str_replace(':', '', $description->getCommand($commandName)->getName()));
 161              }, $namespace['commands'])));
 162          }
 163  
 164          foreach ($description->getCommands() as $command) {
 165              $this->write("\n\n");
 166              $this->write($this->describeCommand($command));
 167          }
 168      }
 169  
 170      private function getApplicationTitle(Application $application)
 171      {
 172          if ('UNKNOWN' !== $application->getName()) {
 173              if ('UNKNOWN' !== $application->getVersion()) {
 174                  return sprintf('%s %s', $application->getName(), $application->getVersion());
 175              }
 176  
 177              return $application->getName();
 178          }
 179  
 180          return 'Console Tool';
 181      }
 182  }