[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /*
   4   * This file is part of the Symfony package.
   5   *
   6   * (c) Fabien Potencier <[email protected]>
   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 <[email protected]>
  26   *
  27   * @internal
  28   */
  29  class MarkdownDescriptor extends Descriptor
  30  {
  31      /**
  32       * {@inheritdoc}
  33       */
  34      public function describe(OutputInterface $output, object $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(string $content, bool $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->isNegatable()) {
  73              $name .= '|--no-'.$option->getName();
  74          }
  75          if ($option->getShortcut()) {
  76              $name .= '|-'.str_replace('|', '|-', $option->getShortcut()).'';
  77          }
  78  
  79          $this->write(
  80              '#### `'.$name.'`'."\n\n"
  81              .($option->getDescription() ? preg_replace('/\s*[\r\n]\s*/', "\n", $option->getDescription())."\n\n" : '')
  82              .'* Accept value: '.($option->acceptValue() ? 'yes' : 'no')."\n"
  83              .'* Is value required: '.($option->isValueRequired() ? 'yes' : 'no')."\n"
  84              .'* Is multiple: '.($option->isArray() ? 'yes' : 'no')."\n"
  85              .'* Is negatable: '.($option->isNegatable() ? 'yes' : 'no')."\n"
  86              .'* Default: `'.str_replace("\n", '', var_export($option->getDefault(), true)).'`'
  87          );
  88      }
  89  
  90      /**
  91       * {@inheritdoc}
  92       */
  93      protected function describeInputDefinition(InputDefinition $definition, array $options = [])
  94      {
  95          if ($showArguments = \count($definition->getArguments()) > 0) {
  96              $this->write('### Arguments');
  97              foreach ($definition->getArguments() as $argument) {
  98                  $this->write("\n\n");
  99                  if (null !== $describeInputArgument = $this->describeInputArgument($argument)) {
 100                      $this->write($describeInputArgument);
 101                  }
 102              }
 103          }
 104  
 105          if (\count($definition->getOptions()) > 0) {
 106              if ($showArguments) {
 107                  $this->write("\n\n");
 108              }
 109  
 110              $this->write('### Options');
 111              foreach ($definition->getOptions() as $option) {
 112                  $this->write("\n\n");
 113                  if (null !== $describeInputOption = $this->describeInputOption($option)) {
 114                      $this->write($describeInputOption);
 115                  }
 116              }
 117          }
 118      }
 119  
 120      /**
 121       * {@inheritdoc}
 122       */
 123      protected function describeCommand(Command $command, array $options = [])
 124      {
 125          if ($options['short'] ?? false) {
 126              $this->write(
 127                  '`'.$command->getName()."`\n"
 128                  .str_repeat('-', Helper::width($command->getName()) + 2)."\n\n"
 129                  .($command->getDescription() ? $command->getDescription()."\n\n" : '')
 130                  .'### Usage'."\n\n"
 131                  .array_reduce($command->getAliases(), function ($carry, $usage) {
 132                      return $carry.'* `'.$usage.'`'."\n";
 133                  })
 134              );
 135  
 136              return;
 137          }
 138  
 139          $command->mergeApplicationDefinition(false);
 140  
 141          $this->write(
 142              '`'.$command->getName()."`\n"
 143              .str_repeat('-', Helper::width($command->getName()) + 2)."\n\n"
 144              .($command->getDescription() ? $command->getDescription()."\n\n" : '')
 145              .'### Usage'."\n\n"
 146              .array_reduce(array_merge([$command->getSynopsis()], $command->getAliases(), $command->getUsages()), function ($carry, $usage) {
 147                  return $carry.'* `'.$usage.'`'."\n";
 148              })
 149          );
 150  
 151          if ($help = $command->getProcessedHelp()) {
 152              $this->write("\n");
 153              $this->write($help);
 154          }
 155  
 156          $definition = $command->getDefinition();
 157          if ($definition->getOptions() || $definition->getArguments()) {
 158              $this->write("\n\n");
 159              $this->describeInputDefinition($definition);
 160          }
 161      }
 162  
 163      /**
 164       * {@inheritdoc}
 165       */
 166      protected function describeApplication(Application $application, array $options = [])
 167      {
 168          $describedNamespace = $options['namespace'] ?? null;
 169          $description = new ApplicationDescription($application, $describedNamespace);
 170          $title = $this->getApplicationTitle($application);
 171  
 172          $this->write($title."\n".str_repeat('=', Helper::width($title)));
 173  
 174          foreach ($description->getNamespaces() as $namespace) {
 175              if (ApplicationDescription::GLOBAL_NAMESPACE !== $namespace['id']) {
 176                  $this->write("\n\n");
 177                  $this->write('**'.$namespace['id'].':**');
 178              }
 179  
 180              $this->write("\n\n");
 181              $this->write(implode("\n", array_map(function ($commandName) use ($description) {
 182                  return sprintf('* [`%s`](#%s)', $commandName, str_replace(':', '', $description->getCommand($commandName)->getName()));
 183              }, $namespace['commands'])));
 184          }
 185  
 186          foreach ($description->getCommands() as $command) {
 187              $this->write("\n\n");
 188              if (null !== $describeCommand = $this->describeCommand($command, $options)) {
 189                  $this->write($describeCommand);
 190              }
 191          }
 192      }
 193  
 194      private function getApplicationTitle(Application $application): string
 195      {
 196          if ('UNKNOWN' !== $application->getName()) {
 197              if ('UNKNOWN' !== $application->getVersion()) {
 198                  return sprintf('%s %s', $application->getName(), $application->getVersion());
 199              }
 200  
 201              return $application->getName();
 202          }
 203  
 204          return 'Console Tool';
 205      }
 206  }