MarkdownDescriptor.php 6.0 KB

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