annotate vendor/symfony/console/Descriptor/MarkdownDescriptor.php @ 19:fa3358dc1485 tip

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