diff --git a/src/Symfony/Component/Console/CHANGELOG.md b/src/Symfony/Component/Console/CHANGELOG.md index 5c37be6d3a21c..c24e4405ef483 100644 --- a/src/Symfony/Component/Console/CHANGELOG.md +++ b/src/Symfony/Component/Console/CHANGELOG.md @@ -6,6 +6,7 @@ CHANGELOG * Improve truecolor terminal detection in some cases * Add support for 256 color terminals (conversion from Ansi24 to Ansi8 if terminal is capable of it) +* Show Application-level console options when showing synopsis or when error occurred 6.1 --- diff --git a/src/Symfony/Component/Console/Command/Command.php b/src/Symfony/Component/Console/Command/Command.php index b41e69153720f..ccf43c4288f82 100644 --- a/src/Symfony/Component/Console/Command/Command.php +++ b/src/Symfony/Component/Console/Command/Command.php @@ -375,15 +375,19 @@ public function setCode(callable $code): static * * @internal */ - public function mergeApplicationDefinition(bool $mergeArgs = true) + public function mergeApplicationDefinition(bool $mergeArgs = true, bool $mergeOptions = true) { if (null === $this->application) { return; } $this->fullDefinition = new InputDefinition(); - $this->fullDefinition->setOptions($this->definition->getOptions()); - $this->fullDefinition->addOptions($this->application->getDefinition()->getOptions()); + if ($mergeOptions) { + $this->fullDefinition->setOptions($this->definition->getOptions()); + $this->fullDefinition->addOptions($this->application->getDefinition()->getOptions()); + } else { + $this->fullDefinition->setOptions($this->definition->getOptions()); + } if ($mergeArgs) { $this->fullDefinition->setArguments($this->application->getDefinition()->getArguments()); diff --git a/src/Symfony/Component/Console/Command/LazyCommand.php b/src/Symfony/Component/Console/Command/LazyCommand.php index ca5a8f4cebfae..d178cc5f32e66 100644 --- a/src/Symfony/Component/Console/Command/LazyCommand.php +++ b/src/Symfony/Component/Console/Command/LazyCommand.php @@ -88,9 +88,9 @@ public function setCode(callable $code): static /** * @internal */ - public function mergeApplicationDefinition(bool $mergeArgs = true): void + public function mergeApplicationDefinition(bool $mergeArgs = true, bool $mergeOptions = false): void { - $this->getCommand()->mergeApplicationDefinition($mergeArgs); + $this->getCommand()->mergeApplicationDefinition($mergeArgs, $mergeOptions); } public function setDefinition(array|InputDefinition $definition): static diff --git a/src/Symfony/Component/Console/Descriptor/Descriptor.php b/src/Symfony/Component/Console/Descriptor/Descriptor.php index bac0adfb50699..2c887ccd8e5dc 100644 --- a/src/Symfony/Component/Console/Descriptor/Descriptor.php +++ b/src/Symfony/Component/Console/Descriptor/Descriptor.php @@ -77,7 +77,7 @@ abstract protected function describeInputOption(InputOption $option, array $opti /** * Describes an InputDefinition instance. */ - abstract protected function describeInputDefinition(InputDefinition $definition, array $options = []); + abstract protected function describeInputDefinition(InputDefinition $definition, array $options = [], string $prefix = ''); /** * Describes a Command instance. diff --git a/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php b/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php index 6f79a17a9d08c..49caa1f50eea0 100644 --- a/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php +++ b/src/Symfony/Component/Console/Descriptor/JsonDescriptor.php @@ -39,9 +39,9 @@ protected function describeInputOption(InputOption $option, array $options = []) } } - protected function describeInputDefinition(InputDefinition $definition, array $options = []) + protected function describeInputDefinition(InputDefinition $definition, array $options = [], string $prefix = '') { - $this->writeData($this->getInputDefinitionData($definition), $options); + $this->writeData($this->getInputDefinitionData($definition, $prefix), $options); } protected function describeCommand(Command $command, array $options = []) @@ -120,22 +120,26 @@ private function getInputOptionData(InputOption $option, bool $negated = false): ]; } - private function getInputDefinitionData(InputDefinition $definition): array + private function getInputDefinitionData(InputDefinition $definition, string $prefix = ''): array { $inputArguments = []; - foreach ($definition->getArguments() as $name => $argument) { - $inputArguments[$name] = $this->getInputArgumentData($argument); + if ($definition->getArguments()) { + foreach ($definition->getArguments() as $name => $argument) { + $inputArguments[$name] = $this->getInputArgumentData($argument); + } } $inputOptions = []; - foreach ($definition->getOptions() as $name => $option) { - $inputOptions[$name] = $this->getInputOptionData($option); - if ($option->isNegatable()) { - $inputOptions['no-'.$name] = $this->getInputOptionData($option, true); + if ($definition->getOptions()) { + foreach ($definition->getOptions() as $name => $option) { + $inputOptions[$name] = $this->getInputOptionData($option); + if ($option->isNegatable()) { + $inputOptions['no-'.$name] = $this->getInputOptionData($option, true); + } } } - return ['arguments' => $inputArguments, 'options' => $inputOptions]; + return ["{$prefix}arguments" => $inputArguments, "{$prefix}options" => $inputOptions]; } private function getCommandData(Command $command, bool $short = false): array @@ -150,13 +154,23 @@ private function getCommandData(Command $command, bool $short = false): array 'usage' => $command->getAliases(), ]; } else { - $command->mergeApplicationDefinition(false); + $command->mergeApplicationDefinition(false, false); $data += [ 'usage' => array_merge([$command->getSynopsis()], $command->getUsages(), $command->getAliases()), 'help' => $command->getProcessedHelp(), - 'definition' => $this->getInputDefinitionData($command->getDefinition()), + 'definition' => [], ]; + + $definition = $command->getApplication()?->getDefinition(); + if ($definition && ($definition->getOptions() || $definition->getArguments())) { + $data['definition'] = $this->getInputDefinitionData($command->getApplication()->getDefinition(), 'application-level '); + } + + $definition = $command->getDefinition(); + if ($definition->getOptions() || $definition->getArguments()) { + $data['definition'] += $this->getInputDefinitionData($command->getDefinition(), 'command-level '); + } } $data['hidden'] = $command->isHidden(); diff --git a/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php b/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php index fbd9c534616e0..2c76d55e74dde 100644 --- a/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php +++ b/src/Symfony/Component/Console/Descriptor/MarkdownDescriptor.php @@ -75,10 +75,10 @@ protected function describeInputOption(InputOption $option, array $options = []) ); } - protected function describeInputDefinition(InputDefinition $definition, array $options = []) + protected function describeInputDefinition(InputDefinition $definition, array $options = [], string $prefix = '') { if ($showArguments = \count($definition->getArguments()) > 0) { - $this->write('### Arguments'); + $this->write("### {$prefix}Arguments"); foreach ($definition->getArguments() as $argument) { $this->write("\n\n"); if (null !== $describeInputArgument = $this->describeInputArgument($argument)) { @@ -92,7 +92,7 @@ protected function describeInputDefinition(InputDefinition $definition, array $o $this->write("\n\n"); } - $this->write('### Options'); + $this->write("### {$prefix}Options"); foreach ($definition->getOptions() as $option) { $this->write("\n\n"); if (null !== $describeInputOption = $this->describeInputOption($option)) { @@ -118,7 +118,7 @@ protected function describeCommand(Command $command, array $options = []) return; } - $command->mergeApplicationDefinition(false); + $command->mergeApplicationDefinition(false, false); $this->write( '`'.$command->getName()."`\n" @@ -135,10 +135,16 @@ protected function describeCommand(Command $command, array $options = []) $this->write($help); } + $definition = $command->getApplication()?->getDefinition(); + if ($definition && ($definition->getOptions() || $definition->getArguments())) { + $this->write("\n\n"); + $this->describeInputDefinition($definition, prefix: 'Application-level '); + } + $definition = $command->getDefinition(); if ($definition->getOptions() || $definition->getArguments()) { $this->write("\n\n"); - $this->describeInputDefinition($definition); + $this->describeInputDefinition($definition, prefix: 'Command-level '); } } diff --git a/src/Symfony/Component/Console/Descriptor/TextDescriptor.php b/src/Symfony/Component/Console/Descriptor/TextDescriptor.php index 48a0b42af9b10..d74a4398dcda8 100644 --- a/src/Symfony/Component/Console/Descriptor/TextDescriptor.php +++ b/src/Symfony/Component/Console/Descriptor/TextDescriptor.php @@ -83,7 +83,7 @@ protected function describeInputOption(InputOption $option, array $options = []) ), $options); } - protected function describeInputDefinition(InputDefinition $definition, array $options = []) + protected function describeInputDefinition(InputDefinition $definition, array $options = [], string $prefix = '') { $totalWidth = $this->calculateTotalWidthForOptions($definition->getOptions()); foreach ($definition->getArguments() as $argument) { @@ -91,7 +91,7 @@ protected function describeInputDefinition(InputDefinition $definition, array $o } if ($definition->getArguments()) { - $this->writeText('Arguments:', $options); + $this->writeText("{$prefix}Arguments:", $options); $this->writeText("\n"); foreach ($definition->getArguments() as $argument) { $this->describeInputArgument($argument, array_merge($options, ['total_width' => $totalWidth])); @@ -106,7 +106,7 @@ protected function describeInputDefinition(InputDefinition $definition, array $o if ($definition->getOptions()) { $laterOptions = []; - $this->writeText('Options:', $options); + $this->writeText("{$prefix}Options:", $options); foreach ($definition->getOptions() as $option) { if (\strlen($option->getShortcut() ?? '') > 1) { $laterOptions[] = $option; @@ -140,10 +140,19 @@ protected function describeCommand(Command $command, array $options = []) } $this->writeText("\n"); + $command->mergeApplicationDefinition(false, false); + + $definition = $command->getApplication()?->getDefinition(); + if ($definition && ($definition->getOptions() || $definition->getArguments())) { + $this->writeText("\n"); + $this->describeInputDefinition($definition, $options, 'Application-level '); + $this->writeText("\n"); + } + $definition = $command->getDefinition(); if ($definition->getOptions() || $definition->getArguments()) { $this->writeText("\n"); - $this->describeInputDefinition($definition, $options); + $this->describeInputDefinition($definition, $options, 'Command-level '); $this->writeText("\n"); } diff --git a/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php b/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php index f4643a9ac77be..8561887a1eccf 100644 --- a/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php +++ b/src/Symfony/Component/Console/Descriptor/XmlDescriptor.php @@ -26,19 +26,29 @@ */ class XmlDescriptor extends Descriptor { - public function getInputDefinitionDocument(InputDefinition $definition): \DOMDocument + public function getInputDefinitionDocument(InputDefinition $definition, string $type = ''): \DOMDocument { $dom = new \DOMDocument('1.0', 'UTF-8'); $dom->appendChild($definitionXML = $dom->createElement('definition')); - $definitionXML->appendChild($argumentsXML = $dom->createElement('arguments')); - foreach ($definition->getArguments() as $argument) { - $this->appendDocument($argumentsXML, $this->getInputArgumentDocument($argument)); + if ($definition->getArguments()) { + $definitionXML->appendChild($argumentsXML = $dom->createElement('arguments')); + if ($type) { + $argumentsXML->setAttribute('type', $type); + } + foreach ($definition->getArguments() as $argument) { + $this->appendDocument($argumentsXML, $this->getInputArgumentDocument($argument)); + } } - $definitionXML->appendChild($optionsXML = $dom->createElement('options')); - foreach ($definition->getOptions() as $option) { - $this->appendDocument($optionsXML, $this->getInputOptionDocument($option)); + if ($definition->getOptions()) { + $definitionXML->appendChild($optionsXML = $dom->createElement('options')); + if ($type) { + $optionsXML->setAttribute('type', $type); + } + foreach ($definition->getOptions() as $option) { + $this->appendDocument($optionsXML, $this->getInputOptionDocument($option)); + } } return $dom; @@ -63,7 +73,7 @@ public function getCommandDocument(Command $command, bool $short = false): \DOMD $usagesXML->appendChild($dom->createElement('usage', $usage)); } } else { - $command->mergeApplicationDefinition(false); + $command->mergeApplicationDefinition(false, false); foreach (array_merge([$command->getSynopsis()], $command->getAliases(), $command->getUsages()) as $usage) { $usagesXML->appendChild($dom->createElement('usage', $usage)); @@ -72,8 +82,17 @@ public function getCommandDocument(Command $command, bool $short = false): \DOMD $commandXML->appendChild($helpXML = $dom->createElement('help')); $helpXML->appendChild($dom->createTextNode(str_replace("\n", "\n ", $command->getProcessedHelp()))); - $definitionXML = $this->getInputDefinitionDocument($command->getDefinition()); - $this->appendDocument($commandXML, $definitionXML->getElementsByTagName('definition')->item(0)); + $definition = $command->getApplication()?->getDefinition(); + if ($definition && ($definition->getOptions() || $definition->getArguments())) { + $definitionXML = $this->getInputDefinitionDocument($definition, 'application-level'); + $this->appendDocument($commandXML, $definitionXML->getElementsByTagName('definition')->item(0)); + } + + $definition = $command->getDefinition(); + if ($definition->getOptions() || $definition->getArguments()) { + $definitionXML = $this->getInputDefinitionDocument($definition, 'command-level'); + $this->appendDocument($commandXML, $definitionXML->getElementsByTagName('definition')->item(0)); + } } return $dom; @@ -130,9 +149,9 @@ protected function describeInputOption(InputOption $option, array $options = []) $this->writeDocument($this->getInputOptionDocument($option)); } - protected function describeInputDefinition(InputDefinition $definition, array $options = []) + protected function describeInputDefinition(InputDefinition $definition, array $options = [], string $prefix = '') { - $this->writeDocument($this->getInputDefinitionDocument($definition)); + $this->writeDocument($this->getInputDefinitionDocument($definition, $prefix)); } protected function describeCommand(Command $command, array $options = []) diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_1.json b/src/Symfony/Component/Console/Tests/Fixtures/application_1.json index bd0bd94c7eed0..d681efe4e9cb9 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/application_1.json +++ b/src/Symfony/Component/Console/Tests/Fixtures/application_1.json @@ -9,17 +9,16 @@ "description": "Internal command to provide shell completion suggestions", "help": "Internal command to provide shell completion suggestions", "definition": { - "arguments": [], - "options": { - "symfony": { - "name": "--symfony", - "shortcut": "-S", - "accept_value": true, - "is_value_required": true, - "is_multiple": false, - "description": "deprecated", - "default": null - }, + "application-level arguments": { + "command": { + "name": "command", + "is_required": true, + "is_array": false, + "description": "The command to execute", + "default": "" + } + }, + "application-level options": { "help": { "name": "--help", "shortcut": "-h", @@ -82,7 +81,10 @@ "is_multiple": false, "description": "Do not ask any interactive question", "default": false - }, + } + }, + "command-level arguments": [], + "command-level options": { "shell": { "name": "--shell", "shortcut": "-s", @@ -118,6 +120,15 @@ "is_multiple": false, "description": "The API version of the completion script", "default": null + }, + "symfony": { + "name": "--symfony", + "shortcut": "-S", + "accept_value": true, + "is_value_required": true, + "is_multiple": false, + "description": "deprecated", + "default": null } } } @@ -131,16 +142,16 @@ "description": "Dump the shell completion script", "help": "Dump the shell completion script", "definition": { - "arguments": { - "shell": { - "name": "shell", - "is_required": false, + "application-level arguments": { + "command": { + "name": "command", + "is_required": true, "is_array": false, - "description": "The shell type (e.g. \"bash\"), the value of the \"$SHELL\" env var will be used if this is not given", - "default": null + "description": "The command to execute", + "default": "" } }, - "options": { + "application-level options": { "help": { "name": "--help", "shortcut": "-h", @@ -203,7 +214,18 @@ "is_multiple": false, "description": "Do not ask any interactive question", "default": false - }, + } + }, + "command-level arguments": { + "shell": { + "name": "shell", + "is_required": false, + "is_array": false, + "description": "The shell type (e.g. \"bash\"), the value of the \"$SHELL\" env var will be used if this is not given", + "default": null + } + }, + "command-level options": { "debug": { "name": "--debug", "shortcut": "", @@ -225,34 +247,16 @@ "description": "Display help for a command", "help": "The help<\/info> command displays help for a given command:\n\n %%PHP_SELF%% help list<\/info>\n\nYou can also output the help in other formats by using the --format<\/comment> option:\n\n %%PHP_SELF%% help --format=xml list<\/info>\n\nTo display the list of available commands, please use the list<\/info> command.", "definition": { - "arguments": { - "command_name": { - "name": "command_name", - "is_required": false, + "application-level arguments": { + "command": { + "name": "command", + "is_required": true, "is_array": false, - "description": "The command name", - "default": "help" + "description": "The command to execute", + "default": "" } }, - "options": { - "format": { - "name": "--format", - "shortcut": "", - "accept_value": true, - "is_value_required": true, - "is_multiple": false, - "description": "The output format (txt, xml, json, or md)", - "default": "txt" - }, - "raw": { - "name": "--raw", - "shortcut": "", - "accept_value": false, - "is_value_required": false, - "is_multiple": false, - "description": "To output raw command help", - "default": false - }, + "application-level options": { "help": { "name": "--help", "shortcut": "-h", @@ -316,6 +320,35 @@ "description": "Do not ask any interactive question", "default": false } + }, + "command-level arguments": { + "command_name": { + "name": "command_name", + "is_required": false, + "is_array": false, + "description": "The command name", + "default": "help" + } + }, + "command-level options": { + "format": { + "name": "--format", + "shortcut": "", + "accept_value": true, + "is_value_required": true, + "is_multiple": false, + "description": "The output format (txt, xml, json, or md)", + "default": "txt" + }, + "raw": { + "name": "--raw", + "shortcut": "", + "accept_value": false, + "is_value_required": false, + "is_multiple": false, + "description": "To output raw command help", + "default": false + } } } }, @@ -328,34 +361,16 @@ "description": "List commands", "help": "The list<\/info> command lists all commands:\n\n %%PHP_SELF%% list<\/info>\n\nYou can also display the commands for a specific namespace:\n\n %%PHP_SELF%% list test<\/info>\n\nYou can also output the information in other formats by using the --format<\/comment> option:\n\n %%PHP_SELF%% list --format=xml<\/info>\n\nIt's also possible to get raw list of commands (useful for embedding command runner):\n\n %%PHP_SELF%% list --raw<\/info>", "definition": { - "arguments": { - "namespace": { - "name": "namespace", - "is_required": false, + "application-level arguments": { + "command": { + "name": "command", + "is_required": true, "is_array": false, - "description": "The namespace name", - "default": null + "description": "The command to execute", + "default": "" } }, - "options": { - "raw": { - "name": "--raw", - "shortcut": "", - "accept_value": false, - "is_value_required": false, - "is_multiple": false, - "description": "To output raw command list", - "default": false - }, - "format": { - "name": "--format", - "shortcut": "", - "accept_value": true, - "is_value_required": true, - "is_multiple": false, - "description": "The output format (txt, xml, json, or md)", - "default": "txt" - }, + "application-level options": { "help": { "name": "--help", "shortcut": "-h", @@ -418,6 +433,35 @@ "is_multiple": false, "description": "Do not ask any interactive question", "default": false + } + }, + "command-level arguments": { + "namespace": { + "name": "namespace", + "is_required": false, + "is_array": false, + "description": "The namespace name", + "default": null + } + }, + "command-level options": { + "raw": { + "name": "--raw", + "shortcut": "", + "accept_value": false, + "is_value_required": false, + "is_multiple": false, + "description": "To output raw command list", + "default": false + }, + "format": { + "name": "--format", + "shortcut": "", + "accept_value": true, + "is_value_required": true, + "is_multiple": false, + "description": "The output format (txt, xml, json, or md)", + "default": "txt" }, "short": { "name": "--short", diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_1.md b/src/Symfony/Component/Console/Tests/Fixtures/application_1.md index bb722c07704b5..f8c81eee383c6 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/application_1.md +++ b/src/Symfony/Component/Console/Tests/Fixtures/application_1.md @@ -16,27 +16,17 @@ Dump the shell completion script Dump the shell completion script -### Arguments +### Application-level Arguments -#### `shell` +#### `command` -The shell type (e.g. "bash"), the value of the "$SHELL" env var will be used if this is not given +The command to execute -* Is required: no +* Is required: yes * Is array: no * Default: `NULL` -### Options - -#### `--debug` - -Tail the completion debug log - -* Accept value: no -* Is value required: no -* Is multiple: no -* Is negatable: no -* Default: `false` +### Application-level Options #### `--help|-h` @@ -98,6 +88,28 @@ Do not ask any interactive question * Is negatable: no * Default: `false` +### Command-level Arguments + +#### `shell` + +The shell type (e.g. "bash"), the value of the "$SHELL" env var will be used if this is not given + +* Is required: no +* Is array: no +* Default: `NULL` + +### Command-level Options + +#### `--debug` + +Tail the completion debug log + +* Accept value: no +* Is value required: no +* Is multiple: no +* Is negatable: no +* Default: `false` + `help` ------ @@ -117,37 +129,17 @@ You can also output the help in other formats by using the --format option: To display the list of available commands, please use the list command. -### Arguments +### Application-level Arguments -#### `command_name` +#### `command` -The command name +The command to execute -* Is required: no +* Is required: yes * Is array: no -* Default: `'help'` - -### Options - -#### `--format` - -The output format (txt, xml, json, or md) - -* Accept value: yes -* Is value required: yes -* Is multiple: no -* Is negatable: no -* Default: `'txt'` - -#### `--raw` - -To output raw command help +* Default: `NULL` -* Accept value: no -* Is value required: no -* Is multiple: no -* Is negatable: no -* Default: `false` +### Application-level Options #### `--help|-h` @@ -209,6 +201,38 @@ Do not ask any interactive question * Is negatable: no * Default: `false` +### Command-level Arguments + +#### `command_name` + +The command name + +* Is required: no +* Is array: no +* Default: `'help'` + +### Command-level Options + +#### `--format` + +The output format (txt, xml, json, or md) + +* Accept value: yes +* Is value required: yes +* Is multiple: no +* Is negatable: no +* Default: `'txt'` + +#### `--raw` + +To output raw command help + +* Accept value: no +* Is value required: no +* Is multiple: no +* Is negatable: no +* Default: `false` + `list` ------ @@ -234,21 +258,21 @@ It's also possible to get raw list of commands (useful for embedding command run %%PHP_SELF%% list --raw -### Arguments +### Application-level Arguments -#### `namespace` +#### `command` -The namespace name +The command to execute -* Is required: no +* Is required: yes * Is array: no * Default: `NULL` -### Options +### Application-level Options -#### `--raw` +#### `--help|-h` -To output raw command list +Display help for the given command. When no command is given display help for the list command * Accept value: no * Is value required: no @@ -256,19 +280,19 @@ To output raw command list * Is negatable: no * Default: `false` -#### `--format` +#### `--quiet|-q` -The output format (txt, xml, json, or md) +Do not output any message -* Accept value: yes -* Is value required: yes +* Accept value: no +* Is value required: no * Is multiple: no * Is negatable: no -* Default: `'txt'` +* Default: `false` -#### `--short` +#### `--verbose|-v|-vv|-vvv` -To skip describing commands' arguments +Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug * Accept value: no * Is value required: no @@ -276,9 +300,9 @@ To skip describing commands' arguments * Is negatable: no * Default: `false` -#### `--help|-h` +#### `--version|-V` -Display help for the given command. When no command is given display help for the list command +Display this application version * Accept value: no * Is value required: no @@ -286,19 +310,19 @@ Display help for the given command. When no command is given display help for th * Is negatable: no * Default: `false` -#### `--quiet|-q` +#### `--ansi|--no-ansi` -Do not output any message +Force (or disable --no-ansi) ANSI output * Accept value: no * Is value required: no * Is multiple: no -* Is negatable: no -* Default: `false` +* Is negatable: yes +* Default: `NULL` -#### `--verbose|-v|-vv|-vvv` +#### `--no-interaction|-n` -Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug +Do not ask any interactive question * Accept value: no * Is value required: no @@ -306,9 +330,21 @@ Increase the verbosity of messages: 1 for normal output, 2 for more verbose outp * Is negatable: no * Default: `false` -#### `--version|-V` +### Command-level Arguments -Display this application version +#### `namespace` + +The namespace name + +* Is required: no +* Is array: no +* Default: `NULL` + +### Command-level Options + +#### `--raw` + +To output raw command list * Accept value: no * Is value required: no @@ -316,19 +352,19 @@ Display this application version * Is negatable: no * Default: `false` -#### `--ansi|--no-ansi` +#### `--format` -Force (or disable --no-ansi) ANSI output +The output format (txt, xml, json, or md) -* Accept value: no -* Is value required: no +* Accept value: yes +* Is value required: yes * Is multiple: no -* Is negatable: yes -* Default: `NULL` +* Is negatable: no +* Default: `'txt'` -#### `--no-interaction|-n` +#### `--short` -Do not ask any interactive question +To skip describing commands' arguments * Accept value: no * Is value required: no diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_1.xml b/src/Symfony/Component/Console/Tests/Fixtures/application_1.xml index d109e055f45cf..e3aaed2b6b4cc 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/application_1.xml +++ b/src/Symfony/Component/Console/Tests/Fixtures/application_1.xml @@ -7,28 +7,13 @@ Internal command to provide shell completion suggestions Internal command to provide shell completion suggestions - - - - - - - + + + @@ -51,6 +36,28 @@ Do not ask any interactive question + + + + + + + diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_2.json b/src/Symfony/Component/Console/Tests/Fixtures/application_2.json index b3eb10bda3d63..aad5be595bb89 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/application_2.json +++ b/src/Symfony/Component/Console/Tests/Fixtures/application_2.json @@ -13,17 +13,16 @@ "description": "Internal command to provide shell completion suggestions", "help": "Internal command to provide shell completion suggestions", "definition": { - "arguments": [], - "options": { - "symfony": { - "name": "--symfony", - "shortcut": "-S", - "accept_value": true, - "is_value_required": true, - "is_multiple": false, - "description": "deprecated", - "default": null - }, + "application-level arguments": { + "command": { + "name": "command", + "is_required": true, + "is_array": false, + "description": "The command to execute", + "default": "" + } + }, + "application-level options": { "help": { "name": "--help", "shortcut": "-h", @@ -86,7 +85,10 @@ "is_multiple": false, "description": "Do not ask any interactive question", "default": false - }, + } + }, + "command-level arguments": [], + "command-level options": { "shell": { "name": "--shell", "shortcut": "-s", @@ -122,6 +124,15 @@ "is_multiple": false, "description": "The API version of the completion script", "default": null + }, + "symfony": { + "name": "--symfony", + "shortcut": "-S", + "accept_value": true, + "is_value_required": true, + "is_multiple": false, + "description": "deprecated", + "default": null } } } @@ -135,16 +146,16 @@ "description": "Dump the shell completion script", "help": "Dump the shell completion script", "definition": { - "arguments": { - "shell": { - "name": "shell", - "is_required": false, + "application-level arguments": { + "command": { + "name": "command", + "is_required": true, "is_array": false, - "description": "The shell type (e.g. \"bash\"), the value of the \"$SHELL\" env var will be used if this is not given", - "default": null + "description": "The command to execute", + "default": "" } }, - "options": { + "application-level options": { "help": { "name": "--help", "shortcut": "-h", @@ -207,7 +218,18 @@ "is_multiple": false, "description": "Do not ask any interactive question", "default": false - }, + } + }, + "command-level arguments": { + "shell": { + "name": "shell", + "is_required": false, + "is_array": false, + "description": "The shell type (e.g. \"bash\"), the value of the \"$SHELL\" env var will be used if this is not given", + "default": null + } + }, + "command-level options": { "debug": { "name": "--debug", "shortcut": "", @@ -229,34 +251,16 @@ "description": "Display help for a command", "help": "The help<\/info> command displays help for a given command:\n\n %%PHP_SELF%% help list<\/info>\n\nYou can also output the help in other formats by using the --format<\/comment> option:\n\n %%PHP_SELF%% help --format=xml list<\/info>\n\nTo display the list of available commands, please use the list<\/info> command.", "definition": { - "arguments": { - "command_name": { - "name": "command_name", - "is_required": false, + "application-level arguments": { + "command": { + "name": "command", + "is_required": true, "is_array": false, - "description": "The command name", - "default": "help" + "description": "The command to execute", + "default": "" } }, - "options": { - "format": { - "name": "--format", - "shortcut": "", - "accept_value": true, - "is_value_required": true, - "is_multiple": false, - "description": "The output format (txt, xml, json, or md)", - "default": "txt" - }, - "raw": { - "name": "--raw", - "shortcut": "", - "accept_value": false, - "is_value_required": false, - "is_multiple": false, - "description": "To output raw command help", - "default": false - }, + "application-level options": { "help": { "name": "--help", "shortcut": "-h", @@ -320,6 +324,35 @@ "description": "Do not ask any interactive question", "default": false } + }, + "command-level arguments": { + "command_name": { + "name": "command_name", + "is_required": false, + "is_array": false, + "description": "The command name", + "default": "help" + } + }, + "command-level options": { + "format": { + "name": "--format", + "shortcut": "", + "accept_value": true, + "is_value_required": true, + "is_multiple": false, + "description": "The output format (txt, xml, json, or md)", + "default": "txt" + }, + "raw": { + "name": "--raw", + "shortcut": "", + "accept_value": false, + "is_value_required": false, + "is_multiple": false, + "description": "To output raw command help", + "default": false + } } } }, @@ -332,34 +365,16 @@ "description": "List commands", "help": "The list<\/info> command lists all commands:\n\n %%PHP_SELF%% list<\/info>\n\nYou can also display the commands for a specific namespace:\n\n %%PHP_SELF%% list test<\/info>\n\nYou can also output the information in other formats by using the --format<\/comment> option:\n\n %%PHP_SELF%% list --format=xml<\/info>\n\nIt's also possible to get raw list of commands (useful for embedding command runner):\n\n %%PHP_SELF%% list --raw<\/info>", "definition": { - "arguments": { - "namespace": { - "name": "namespace", - "is_required": false, + "application-level arguments": { + "command": { + "name": "command", + "is_required": true, "is_array": false, - "description": "The namespace name", - "default": null + "description": "The command to execute", + "default": "" } }, - "options": { - "raw": { - "name": "--raw", - "shortcut": "", - "accept_value": false, - "is_value_required": false, - "is_multiple": false, - "description": "To output raw command list", - "default": false - }, - "format": { - "name": "--format", - "shortcut": "", - "accept_value": true, - "is_value_required": true, - "is_multiple": false, - "description": "The output format (txt, xml, json, or md)", - "default": "txt" - }, + "application-level options": { "help": { "name": "--help", "shortcut": "-h", @@ -422,6 +437,35 @@ "is_multiple": false, "description": "Do not ask any interactive question", "default": false + } + }, + "command-level arguments": { + "namespace": { + "name": "namespace", + "is_required": false, + "is_array": false, + "description": "The namespace name", + "default": null + } + }, + "command-level options": { + "raw": { + "name": "--raw", + "shortcut": "", + "accept_value": false, + "is_value_required": false, + "is_multiple": false, + "description": "To output raw command list", + "default": false + }, + "format": { + "name": "--format", + "shortcut": "", + "accept_value": true, + "is_value_required": true, + "is_multiple": false, + "description": "The output format (txt, xml, json, or md)", + "default": "txt" }, "short": { "name": "--short", @@ -446,8 +490,16 @@ "description": "command 1 description", "help": "command 1 help", "definition": { - "arguments": [], - "options": { + "application-level arguments": { + "command": { + "name": "command", + "is_required": true, + "is_array": false, + "description": "The command to execute", + "default": "" + } + }, + "application-level options": { "help": { "name": "--help", "shortcut": "-h", @@ -525,25 +577,16 @@ "description": "command 2 description", "help": "command 2 help", "definition": { - "arguments": { - "argument_name": { - "name": "argument_name", + "application-level arguments": { + "command": { + "name": "command", "is_required": true, "is_array": false, - "description": "", - "default": null + "description": "The command to execute", + "default": "" } }, - "options": { - "option_name": { - "name": "--option_name", - "shortcut": "-o", - "accept_value": false, - "is_value_required": false, - "is_multiple": false, - "description": "", - "default": false - }, + "application-level options": { "help": { "name": "--help", "shortcut": "-h", @@ -607,6 +650,26 @@ "description": "Do not ask any interactive question", "default": false } + }, + "command-level arguments": { + "argument_name": { + "name": "argument_name", + "is_required": true, + "is_array": false, + "description": "", + "default": null + } + }, + "command-level options": { + "option_name": { + "name": "--option_name", + "shortcut": "-o", + "accept_value": false, + "is_value_required": false, + "is_multiple": false, + "description": "", + "default": false + } } } }, @@ -619,8 +682,16 @@ "description": "command 3 description", "help": "command 3 help", "definition": { - "arguments": {}, - "options": { + "application-level arguments": { + "command": { + "name": "command", + "is_required": true, + "is_array": false, + "description": "The command to execute", + "default": "" + } + }, + "application-level options": { "help": { "name": "--help", "shortcut": "-h", @@ -695,11 +766,19 @@ "descriptor:alias_command4", "command4:descriptor" ], - "description": null, + "description": "", "help": "", "definition": { - "arguments": {}, - "options": { + "application-level arguments": { + "command": { + "name": "command", + "is_required": true, + "is_array": false, + "description": "The command to execute", + "default": "" + } + }, + "application-level options": { "help": { "name": "--help", "shortcut": "-h", diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_2.md b/src/Symfony/Component/Console/Tests/Fixtures/application_2.md index d4802c7470937..962919d65654b 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/application_2.md +++ b/src/Symfony/Component/Console/Tests/Fixtures/application_2.md @@ -29,27 +29,17 @@ Dump the shell completion script Dump the shell completion script -### Arguments +### Application-level Arguments -#### `shell` +#### `command` -The shell type (e.g. "bash"), the value of the "$SHELL" env var will be used if this is not given +The command to execute -* Is required: no +* Is required: yes * Is array: no * Default: `NULL` -### Options - -#### `--debug` - -Tail the completion debug log - -* Accept value: no -* Is value required: no -* Is multiple: no -* Is negatable: no -* Default: `false` +### Application-level Options #### `--help|-h` @@ -111,6 +101,28 @@ Do not ask any interactive question * Is negatable: no * Default: `false` +### Command-level Arguments + +#### `shell` + +The shell type (e.g. "bash"), the value of the "$SHELL" env var will be used if this is not given + +* Is required: no +* Is array: no +* Default: `NULL` + +### Command-level Options + +#### `--debug` + +Tail the completion debug log + +* Accept value: no +* Is value required: no +* Is multiple: no +* Is negatable: no +* Default: `false` + `help` ------ @@ -130,37 +142,17 @@ You can also output the help in other formats by using the --format option: To display the list of available commands, please use the list command. -### Arguments +### Application-level Arguments -#### `command_name` +#### `command` -The command name +The command to execute -* Is required: no +* Is required: yes * Is array: no -* Default: `'help'` - -### Options - -#### `--format` - -The output format (txt, xml, json, or md) - -* Accept value: yes -* Is value required: yes -* Is multiple: no -* Is negatable: no -* Default: `'txt'` - -#### `--raw` +* Default: `NULL` -To output raw command help - -* Accept value: no -* Is value required: no -* Is multiple: no -* Is negatable: no -* Default: `false` +### Application-level Options #### `--help|-h` @@ -222,6 +214,38 @@ Do not ask any interactive question * Is negatable: no * Default: `false` +### Command-level Arguments + +#### `command_name` + +The command name + +* Is required: no +* Is array: no +* Default: `'help'` + +### Command-level Options + +#### `--format` + +The output format (txt, xml, json, or md) + +* Accept value: yes +* Is value required: yes +* Is multiple: no +* Is negatable: no +* Default: `'txt'` + +#### `--raw` + +To output raw command help + +* Accept value: no +* Is value required: no +* Is multiple: no +* Is negatable: no +* Default: `false` + `list` ------ @@ -247,21 +271,21 @@ It's also possible to get raw list of commands (useful for embedding command run %%PHP_SELF%% list --raw -### Arguments +### Application-level Arguments -#### `namespace` +#### `command` -The namespace name +The command to execute -* Is required: no +* Is required: yes * Is array: no * Default: `NULL` -### Options +### Application-level Options -#### `--raw` +#### `--help|-h` -To output raw command list +Display help for the given command. When no command is given display help for the list command * Accept value: no * Is value required: no @@ -269,19 +293,19 @@ To output raw command list * Is negatable: no * Default: `false` -#### `--format` +#### `--quiet|-q` -The output format (txt, xml, json, or md) +Do not output any message -* Accept value: yes -* Is value required: yes +* Accept value: no +* Is value required: no * Is multiple: no * Is negatable: no -* Default: `'txt'` +* Default: `false` -#### `--short` +#### `--verbose|-v|-vv|-vvv` -To skip describing commands' arguments +Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug * Accept value: no * Is value required: no @@ -289,9 +313,9 @@ To skip describing commands' arguments * Is negatable: no * Default: `false` -#### `--help|-h` +#### `--version|-V` -Display help for the given command. When no command is given display help for the list command +Display this application version * Accept value: no * Is value required: no @@ -299,19 +323,19 @@ Display help for the given command. When no command is given display help for th * Is negatable: no * Default: `false` -#### `--quiet|-q` +#### `--ansi|--no-ansi` -Do not output any message +Force (or disable --no-ansi) ANSI output * Accept value: no * Is value required: no * Is multiple: no -* Is negatable: no -* Default: `false` +* Is negatable: yes +* Default: `NULL` -#### `--verbose|-v|-vv|-vvv` +#### `--no-interaction|-n` -Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug +Do not ask any interactive question * Accept value: no * Is value required: no @@ -319,9 +343,21 @@ Increase the verbosity of messages: 1 for normal output, 2 for more verbose outp * Is negatable: no * Default: `false` -#### `--version|-V` +### Command-level Arguments -Display this application version +#### `namespace` + +The namespace name + +* Is required: no +* Is array: no +* Default: `NULL` + +### Command-level Options + +#### `--raw` + +To output raw command list * Accept value: no * Is value required: no @@ -329,19 +365,19 @@ Display this application version * Is negatable: no * Default: `false` -#### `--ansi|--no-ansi` +#### `--format` -Force (or disable --no-ansi) ANSI output +The output format (txt, xml, json, or md) -* Accept value: no -* Is value required: no +* Accept value: yes +* Is value required: yes * Is multiple: no -* Is negatable: yes -* Default: `NULL` +* Is negatable: no +* Default: `'txt'` -#### `--no-interaction|-n` +#### `--short` -Do not ask any interactive question +To skip describing commands' arguments * Accept value: no * Is value required: no @@ -362,7 +398,17 @@ command 1 description command 1 help -### Options +### Application-level Arguments + +#### `command` + +The command to execute + +* Is required: yes +* Is array: no +* Default: `NULL` + +### Application-level Options #### `--help|-h` @@ -437,23 +483,17 @@ command 2 description command 2 help -### Arguments +### Application-level Arguments -#### `argument_name` +#### `command` + +The command to execute * Is required: yes * Is array: no * Default: `NULL` -### Options - -#### `--option_name|-o` - -* Accept value: no -* Is value required: no -* Is multiple: no -* Is negatable: no -* Default: `false` +### Application-level Options #### `--help|-h` @@ -515,6 +555,24 @@ Do not ask any interactive question * Is negatable: no * Default: `false` +### Command-level Arguments + +#### `argument_name` + +* Is required: yes +* Is array: no +* Default: `NULL` + +### Command-level Options + +#### `--option_name|-o` + +* Accept value: no +* Is value required: no +* Is multiple: no +* Is negatable: no +* Default: `false` + `descriptor:command4` --------------------- @@ -525,7 +583,17 @@ Do not ask any interactive question * `command4:descriptor` -### Options +### Application-level Arguments + +#### `command` + +The command to execute + +* Is required: yes +* Is array: no +* Default: `NULL` + +### Application-level Options #### `--help|-h` diff --git a/src/Symfony/Component/Console/Tests/Fixtures/application_2.xml b/src/Symfony/Component/Console/Tests/Fixtures/application_2.xml index 6ee45c1fabf4d..43d261fd3889c 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/application_2.xml +++ b/src/Symfony/Component/Console/Tests/Fixtures/application_2.xml @@ -7,28 +7,13 @@ Internal command to provide shell completion suggestions Internal command to provide shell completion suggestions - - - - - - - + + + @@ -51,6 +36,28 @@ Do not ask any interactive question + + + + + + + diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_2.json b/src/Symfony/Component/Console/Tests/Fixtures/command_2.json index 8a1ec02354257..135795f204448 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/command_2.json +++ b/src/Symfony/Component/Console/Tests/Fixtures/command_2.json @@ -9,7 +9,7 @@ "description": "command 2 description", "help": "command 2 help", "definition": { - "arguments": { + "command-level arguments": { "argument_name": { "name": "argument_name", "is_required": true, @@ -18,7 +18,7 @@ "default": null } }, - "options": { + "command-level options": { "option_name": { "name": "--option_name", "shortcut": "-o", diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_2.md b/src/Symfony/Component/Console/Tests/Fixtures/command_2.md index c0023b7efec56..502af59104875 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/command_2.md +++ b/src/Symfony/Component/Console/Tests/Fixtures/command_2.md @@ -11,7 +11,7 @@ command 2 description command 2 help -### Arguments +### Command-level Arguments #### `argument_name` @@ -19,7 +19,7 @@ command 2 help * Is array: no * Default: `NULL` -### Options +### Command-level Options #### `--option_name|-o` diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_2.txt b/src/Symfony/Component/Console/Tests/Fixtures/command_2.txt index fcab77a29e19a..7ab27893ff244 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/command_2.txt +++ b/src/Symfony/Component/Console/Tests/Fixtures/command_2.txt @@ -6,10 +6,10 @@ descriptor:command2 -o|--option_name \ descriptor:command2 \ -Arguments: +Command-level Arguments: argument_name -Options: +Command-level Options: -o, --option_name Help: diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_2.xml b/src/Symfony/Component/Console/Tests/Fixtures/command_2.xml index ae69e2f49fac8..93974b9ca71ac 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/command_2.xml +++ b/src/Symfony/Component/Console/Tests/Fixtures/command_2.xml @@ -7,13 +7,13 @@ command 2 description command 2 help - + - + diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_mbstring.md b/src/Symfony/Component/Console/Tests/Fixtures/command_mbstring.md index a8d0d10c03b87..cb96669acb633 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/command_mbstring.md +++ b/src/Symfony/Component/Console/Tests/Fixtures/command_mbstring.md @@ -11,7 +11,7 @@ command åèä description command åèä help -### Arguments +### Command-level Arguments #### `argument_åèä` @@ -19,7 +19,7 @@ command åèä help * Is array: no * Default: `NULL` -### Options +### Command-level Options #### `--option_åèä|-o` diff --git a/src/Symfony/Component/Console/Tests/Fixtures/command_mbstring.txt b/src/Symfony/Component/Console/Tests/Fixtures/command_mbstring.txt index 1fa4e3135fa23..d5f111f878d0c 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/command_mbstring.txt +++ b/src/Symfony/Component/Console/Tests/Fixtures/command_mbstring.txt @@ -6,10 +6,10 @@ descriptor:åèä -o|--option_name \ descriptor:åèä \ -Arguments: +Command-level Arguments: argument_åèä -Options: +Command-level Options: -o, --option_åèä Help: diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_definition_1.xml b/src/Symfony/Component/Console/Tests/Fixtures/input_definition_1.xml index b5481ce1276a2..4ba4c8ab00e77 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/input_definition_1.xml +++ b/src/Symfony/Component/Console/Tests/Fixtures/input_definition_1.xml @@ -1,5 +1,2 @@ - - - - + diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_definition_2.xml b/src/Symfony/Component/Console/Tests/Fixtures/input_definition_2.xml index 102efc1486381..aaf79fb71da17 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/input_definition_2.xml +++ b/src/Symfony/Component/Console/Tests/Fixtures/input_definition_2.xml @@ -6,5 +6,4 @@ - diff --git a/src/Symfony/Component/Console/Tests/Fixtures/input_definition_3.xml b/src/Symfony/Component/Console/Tests/Fixtures/input_definition_3.xml index bc95151548ada..26b5ac66abb0e 100644 --- a/src/Symfony/Component/Console/Tests/Fixtures/input_definition_3.xml +++ b/src/Symfony/Component/Console/Tests/Fixtures/input_definition_3.xml @@ -1,6 +1,5 @@ -