Skip to content

[Console] Made output docopt compatible #13220

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 6 commits into from
Closed

[Console] Made output docopt compatible #13220

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4daf2c0
Added addUsage() to specify usage patterns
wouterj Jan 3, 2015
43c1c85
Made output docopt compatible
wouterj Jan 3, 2015
d462aba
Customize usage section
wouterj Jan 29, 2015
d9a42c9
Fixed some more tests
wouterj Feb 17, 2015
749d9cf
Added test for multiline descriptions
wouterj Feb 18, 2015
7489720
Made fabbot happy
wouterj Feb 18, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 38 additions & 6 deletions src/Symfony/Component/Console/Command/Command.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,8 @@ class Command
private $applicationDefinitionMerged = false;
private $applicationDefinitionMergedWithArgs = false;
private $code;
private $synopsis;
private $synopsis = array();
private $usages = array();
private $helperSet;

/**
Expand Down Expand Up @@ -215,7 +216,8 @@ protected function initialize(InputInterface $input, OutputInterface $output)
public function run(InputInterface $input, OutputInterface $output)
{
// force the creation of the synopsis before the merge with the app definition
$this->getSynopsis();
$this->getSynopsis(true);
$this->getSynopsis(false);

// add the application arguments and options
$this->mergeApplicationDefinition();
Expand Down Expand Up @@ -573,15 +575,45 @@ public function getAliases()
/**
* Returns the synopsis for the command.
*
* @param bool $short Whether to show the short version of the synopsis (with options folded) or not
*
* @return string The synopsis
*/
public function getSynopsis()
public function getSynopsis($short = false)
{
$key = $short ? 'short' : 'long';

if (!isset($this->synopsis[$key])) {
$this->synopsis[$key] = trim(sprintf('%s %s', $this->name, $this->definition->getSynopsis($short)));
}

return $this->synopsis[$key];
}

/**
* Add a command usage example.
*
* @param string $usage The usage, it'll be prefixed with the command name
*/
public function addUsage($usage)
{
if (null === $this->synopsis) {
$this->synopsis = trim(sprintf('%s %s', $this->name, $this->definition->getSynopsis()));
if (0 !== strpos($usage, $this->name)) {
$usage = sprintf('%s %s', $this->name, $usage);
}

return $this->synopsis;
$this->usages[] = $usage;

return $this;
}

/**
* Returns alternative usages of the command.
*
* @return array
*/
public function getUsages()
{
return $this->usages;
}

/**
Expand Down
7 changes: 3 additions & 4 deletions src/Symfony/Component/Console/Descriptor/JsonDescriptor.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ private function getInputArgumentData(InputArgument $argument)
'name' => $argument->getName(),
'is_required' => $argument->isRequired(),
'is_array' => $argument->isArray(),
'description' => $argument->getDescription(),
'description' => preg_replace('/\s*\R\s*/', ' ', $argument->getDescription()),
'default' => $argument->getDefault(),
);
}
Expand All @@ -120,7 +120,7 @@ private function getInputOptionData(InputOption $option)
'accept_value' => $option->acceptValue(),
'is_value_required' => $option->isValueRequired(),
'is_multiple' => $option->isArray(),
'description' => $option->getDescription(),
'description' => preg_replace('/\s*\R\s*/', ' ', $option->getDescription()),
'default' => $option->getDefault(),
);
}
Expand Down Expand Up @@ -157,10 +157,9 @@ private function getCommandData(Command $command)

return array(
'name' => $command->getName(),
'usage' => $command->getSynopsis(),
'usage' => array_merge(array($command->getSynopsis()), $command->getUsages(), $command->getAliases()),
'description' => $command->getDescription(),
'help' => $command->getProcessedHelp(),
'aliases' => $command->getAliases(),
'definition' => $this->getInputDefinitionData($command->getNativeDefinition()),
);
}
Expand Down
12 changes: 7 additions & 5 deletions src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ protected function describeInputArgument(InputArgument $argument, array $options
.'* Name: '.($argument->getName() ?: '<none>')."\n"
.'* Is required: '.($argument->isRequired() ? 'yes' : 'no')."\n"
.'* Is array: '.($argument->isArray() ? 'yes' : 'no')."\n"
.'* Description: '.($argument->getDescription() ?: '<none>')."\n"
.'* Description: '.preg_replace('/\s*\R\s*/', PHP_EOL.' ', $argument->getDescription() ?: '<none>')."\n"
.'* Default: `'.str_replace("\n", '', var_export($argument->getDefault(), true)).'`'
);
}
Expand All @@ -53,7 +53,7 @@ protected function describeInputOption(InputOption $option, array $options = arr
.'* Accept value: '.($option->acceptValue() ? 'yes' : 'no')."\n"
.'* Is value required: '.($option->isValueRequired() ? 'yes' : 'no')."\n"
.'* Is multiple: '.($option->isArray() ? 'yes' : 'no')."\n"
.'* Description: '.($option->getDescription() ?: '<none>')."\n"
.'* Description: '.preg_replace('/\s*\R\s*/', PHP_EOL.' ', $option->getDescription() ?: '<none>')."\n"
.'* Default: `'.str_replace("\n", '', var_export($option->getDefault(), true)).'`'
);
}
Expand Down Expand Up @@ -96,12 +96,14 @@ protected function describeCommand(Command $command, array $options = array())
$command->getName()."\n"
.str_repeat('-', strlen($command->getName()))."\n\n"
.'* Description: '.($command->getDescription() ?: '<none>')."\n"
.'* Usage: `'.$command->getSynopsis().'`'."\n"
.'* Aliases: '.(count($command->getAliases()) ? '`'.implode('`, `', $command->getAliases()).'`' : '<none>')
.'* Usage:'."\n\n"
.array_reduce(array_merge(array($command->getSynopsis()), $command->getAliases(), $command->getUsages()), function ($carry, $usage) {
return $carry .= ' * `'.$usage.'`'."\n";
})
);

if ($help = $command->getProcessedHelp()) {
$this->write("\n\n");
$this->write("\n");
$this->write($help);
}

Expand Down
137 changes: 82 additions & 55 deletions src/Symfony/Component/Console/Descriptor/TextDescriptor.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,16 +32,19 @@ class TextDescriptor extends Descriptor
protected function describeInputArgument(InputArgument $argument, array $options = array())
{
if (null !== $argument->getDefault() && (!is_array($argument->getDefault()) || count($argument->getDefault()))) {
$default = sprintf('<comment> (default: %s)</comment>', $this->formatDefaultValue($argument->getDefault()));
$default = sprintf('<comment> [default: %s]</comment>', $this->formatDefaultValue($argument->getDefault()));
} else {
$default = '';
}

$nameWidth = isset($options['name_width']) ? $options['name_width'] : strlen($argument->getName());
$totalWidth = isset($options['total_width']) ? $options['total_width'] : strlen($argument->getName());
$spacingWidth = $totalWidth - strlen($argument->getName()) + 2;

$this->writeText(sprintf(" <info>%-${nameWidth}s</info> %s%s",
$this->writeText(sprintf(" <info>%s</info>%s%s%s",
$argument->getName(),
str_replace("\n", "\n".str_repeat(' ', $nameWidth + 2), $argument->getDescription()),
str_repeat(' ', $spacingWidth),
// + 17 = 2 spaces + <info> + </info> + 2 spaces
preg_replace('/\s*\R\s*/', PHP_EOL.str_repeat(' ', $totalWidth + 17), $argument->getDescription()),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The additional lines only need to have +4 spaces as the <info></info> elements only apply to the first line and that's catered for in the sprintf.

$default
), $options);
}
Expand All @@ -52,18 +55,33 @@ protected function describeInputArgument(InputArgument $argument, array $options
protected function describeInputOption(InputOption $option, array $options = array())
{
if ($option->acceptValue() && null !== $option->getDefault() && (!is_array($option->getDefault()) || count($option->getDefault()))) {
$default = sprintf('<comment> (default: %s)</comment>', $this->formatDefaultValue($option->getDefault()));
$default = sprintf('<comment> [default: %s]</comment>', $this->formatDefaultValue($option->getDefault()));
} else {
$default = '';
}

$nameWidth = isset($options['name_width']) ? $options['name_width'] : strlen($option->getName());
$nameWithShortcutWidth = $nameWidth - strlen($option->getName()) - 2;
$value = '';
if ($option->acceptValue()) {
$value = '='.strtoupper($option->getName());

$this->writeText(sprintf(" <info>%s</info> %-${nameWithShortcutWidth}s%s%s%s",
'--'.$option->getName(),
$option->getShortcut() ? sprintf('(-%s) ', $option->getShortcut()) : '',
str_replace("\n", "\n".str_repeat(' ', $nameWidth + 2), $option->getDescription()),
if ($option->isValueOptional()) {
$value = '['.$value.']';
}
}

$totalWidth = isset($options['total_width']) ? $options['total_width'] : $this->calculateTotalWidthForOptions(array($option));
$synopsis = sprintf('%s%s',
$option->getShortcut() ? sprintf('-%s, ', $option->getShortcut()) : ' ',
sprintf('--%s%s', $option->getName(), $value)
);

$spacingWidth = $totalWidth - strlen($synopsis) + 2;

$this->writeText(sprintf(" <info>%s</info>%s%s%s%s",
$synopsis,
str_repeat(' ', $spacingWidth),
// + 17 = 2 spaces + <info> + </info> + 2 spaces
preg_replace('/\s*\R\s*/', "\n".str_repeat(' ', $totalWidth + 17), $option->getDescription()),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The additional lines only need to have +4 spaces as the <info></info> elements only apply to the first line and that's catered for in the sprintf.

$default,
$option->isArray() ? '<comment> (multiple values allowed)</comment>' : ''
), $options);
Expand All @@ -74,24 +92,16 @@ protected function describeInputOption(InputOption $option, array $options = arr
*/
protected function describeInputDefinition(InputDefinition $definition, array $options = array())
{
$nameWidth = 0;
foreach ($definition->getOptions() as $option) {
$nameLength = strlen($option->getName()) + 2;
if ($option->getShortcut()) {
$nameLength += strlen($option->getShortcut()) + 3;
}
$nameWidth = max($nameWidth, $nameLength);
}
$totalWidth = $this->calculateTotalWidthForOptions($definition->getOptions());
foreach ($definition->getArguments() as $argument) {
$nameWidth = max($nameWidth, strlen($argument->getName()));
$totalWidth = max($totalWidth, strlen($argument->getName()));
}
++$nameWidth;

if ($definition->getArguments()) {
$this->writeText('<comment>Arguments:</comment>', $options);
$this->writeText("\n");
foreach ($definition->getArguments() as $argument) {
$this->describeInputArgument($argument, array_merge($options, array('name_width' => $nameWidth)));
$this->describeInputArgument($argument, array_merge($options, array('total_width' => $totalWidth)));
$this->writeText("\n");
}
}
Expand All @@ -101,11 +111,20 @@ protected function describeInputDefinition(InputDefinition $definition, array $o
}

if ($definition->getOptions()) {
$laterOptions = array();

$this->writeText('<comment>Options:</comment>', $options);
$this->writeText("\n");
foreach ($definition->getOptions() as $option) {
$this->describeInputOption($option, array_merge($options, array('name_width' => $nameWidth)));
if (strlen($option->getShortcut()) > 1) {
$laterOptions[] = $option;
continue;
}
$this->writeText("\n");
$this->describeInputOption($option, array_merge($options, array('total_width' => $totalWidth)));
}
foreach ($laterOptions as $option) {
$this->writeText("\n");
$this->describeInputOption($option, array_merge($options, array('total_width' => $totalWidth)));
}
}
}
Expand All @@ -115,27 +134,26 @@ protected function describeInputDefinition(InputDefinition $definition, array $o
*/
protected function describeCommand(Command $command, array $options = array())
{
$command->getSynopsis();
$command->getSynopsis(true);
$command->getSynopsis(false);
$command->mergeApplicationDefinition(false);

$this->writeText('<comment>Usage:</comment>', $options);
$this->writeText("\n");
$this->writeText(' '.$command->getSynopsis(), $options);
$this->writeText("\n");

if (count($command->getAliases()) > 0) {
foreach (array_merge(array($command->getSynopsis(true)), $command->getAliases(), $command->getUsages()) as $usage) {
$this->writeText("\n");
$this->writeText('<comment>Aliases:</comment> <info>'.implode(', ', $command->getAliases()).'</info>', $options);
$this->writeText(' '.$usage, $options);
}
$this->writeText("\n");

if ($definition = $command->getNativeDefinition()) {
$definition = $command->getNativeDefinition();
if ($definition->getOptions() || $definition->getArguments()) {
$this->writeText("\n");
$this->describeInputDefinition($definition, $options);
$this->writeText("\n");
}

$this->writeText("\n");

if ($help = $command->getProcessedHelp()) {
$this->writeText("\n");
$this->writeText('<comment>Help:</comment>', $options);
$this->writeText("\n");
$this->writeText(' '.str_replace("\n", "\n ", $help), $options);
Expand Down Expand Up @@ -164,27 +182,12 @@ protected function describeApplication(Application $application, array $options
}

$this->writeText("<comment>Usage:</comment>\n", $options);
$this->writeText(" command [options] [arguments]\n\n", $options);
$this->writeText('<comment>Options:</comment>', $options);

$inputOptions = $application->getDefinition()->getOptions();

$width = 0;
foreach ($inputOptions as $option) {
$nameLength = strlen($option->getName()) + 2;
if ($option->getShortcut()) {
$nameLength += strlen($option->getShortcut()) + 3;
}
$width = max($width, $nameLength);
}
++$width;
$this->writeText(" command [options] [arguments]\n\n", $options);

foreach ($inputOptions as $option) {
$this->writeText("\n", $options);
$this->describeInputOption($option, array_merge($options, array('name_width' => $width)));
}
$this->describeInputDefinition(new InputDefinition($application->getDefinition()->getOptions()), $options);

$this->writeText("\n\n", $options);
$this->writeText("\n");
$this->writeText("\n");

$width = $this->getColumnWidth($description->getCommands());

Expand All @@ -198,12 +201,13 @@ protected function describeApplication(Application $application, array $options
foreach ($description->getNamespaces() as $namespace) {
if (!$describedNamespace && ApplicationDescription::GLOBAL_NAMESPACE !== $namespace['id']) {
$this->writeText("\n");
$this->writeText('<comment>'.$namespace['id'].'</comment>', $options);
$this->writeText(' <comment>'.$namespace['id'].'</comment>', $options);
}

foreach ($namespace['commands'] as $name) {
$this->writeText("\n");
$this->writeText(sprintf(" <info>%-${width}s</info> %s", $name, $description->getCommand($name)->getDescription()), $options);
$spacingWidth = $width - strlen($name);
$this->writeText(sprintf(" <info>%s</info>%s%s", $name, str_repeat(' ', $spacingWidth), $description->getCommand($name)->getDescription()), $options);
}
}

Expand Down Expand Up @@ -252,4 +256,27 @@ private function getColumnWidth(array $commands)

return $width + 2;
}

/**
* @param InputOption[] $options
*
* @return int
*/
private function calculateTotalWidthForOptions($options)
{
$totalWidth = 0;
foreach ($options as $option) {
$nameLength = 4 + strlen($option->getName()) + 2; // - + shortcut + , + whitespace + name + --

if ($option->acceptValue()) {
$valueLength = 1 + strlen($option->getName()); // = + value
$valueLength += $option->isValueOptional() ? 2 : 0; // [ + ]

$nameLength += $valueLength;
}
$totalWidth = max($totalWidth, $nameLength);
}

return $totalWidth;
}
}
13 changes: 5 additions & 8 deletions src/Symfony/Component/Console/Descriptor/XmlDescriptor.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,21 +65,18 @@ public function getCommandDocument(Command $command)
$commandXML->setAttribute('id', $command->getName());
$commandXML->setAttribute('name', $command->getName());

$commandXML->appendChild($usageXML = $dom->createElement('usage'));
$usageXML->appendChild($dom->createTextNode(sprintf($command->getSynopsis(), '')));
$commandXML->appendChild($usagesXML = $dom->createElement('usages'));

foreach (array_merge(array($command->getSynopsis()), $command->getAliases(), $command->getUsages()) as $usage) {
$usagesXML->appendChild($dom->createElement('usage', $usage));
}

$commandXML->appendChild($descriptionXML = $dom->createElement('description'));
$descriptionXML->appendChild($dom->createTextNode(str_replace("\n", "\n ", $command->getDescription())));

$commandXML->appendChild($helpXML = $dom->createElement('help'));
$helpXML->appendChild($dom->createTextNode(str_replace("\n", "\n ", $command->getProcessedHelp())));

$commandXML->appendChild($aliasesXML = $dom->createElement('aliases'));
foreach ($command->getAliases() as $alias) {
$aliasesXML->appendChild($aliasXML = $dom->createElement('alias'));
$aliasXML->appendChild($dom->createTextNode($alias));
}

$definitionXML = $this->getInputDefinitionDocument($command->getNativeDefinition());
$this->appendDocument($commandXML, $definitionXML->getElementsByTagName('definition')->item(0));

Expand Down
Loading