From d2b69b6a78153b7376cbcfa972c40c1659e51da9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Tue, 1 Apr 2014 11:30:56 +0200 Subject: [PATCH 1/3] Added a little sample on Option uses with "spaces" --- components/console/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/console/introduction.rst b/components/console/introduction.rst index 7cf2d127f0e..0b0df91aae1 100644 --- a/components/console/introduction.rst +++ b/components/console/introduction.rst @@ -295,7 +295,7 @@ declare a one-letter shortcut that you can call with a single dash like .. tip:: It is also possible to make an option *optionally* accept a value (so that - ``--yell`` or ``--yell=loud`` work). Options can also be configured to + ``--yell`` or ``--yell=loud`` or ``--yell loud`` work). Options can also be configured to accept an array of values. For example, add a new option to the command that can be used to specify From f5035960db94b1db7b722d3678e54e57e6942b12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Wed, 9 Apr 2014 02:03:44 +0200 Subject: [PATCH 2/3] [WIP] - Console add Console arguments page --- components/console/console_arguments.rst | 84 ++++++++++++++++++++++ components/console/index.rst | 1 + components/console/introduction.rst | 1 + components/console/single_command_tool.rst | 2 +- 4 files changed, 87 insertions(+), 1 deletion(-) create mode 100644 components/console/console_arguments.rst diff --git a/components/console/console_arguments.rst b/components/console/console_arguments.rst new file mode 100644 index 00000000000..1212e96d955 --- /dev/null +++ b/components/console/console_arguments.rst @@ -0,0 +1,84 @@ +.. index:: + single: Console; Console arguments + +Understand how Console Arguments are Handled +============================================ + +It can be difficult to understand the way arguments are handled by the console application. +The Symfony Console application, like many other CLI utility tools, follows the behavior +described in the `docopt`_ standards. + +Let's see a complete example on how the arguments are understood by Console application, +regarding to the Console Options or Arguments defined in the application:: + + namespace Acme\Console\Command; + + use Symfony\Component\Console\Command\Command; + use Symfony\Component\Console\Input\InputArgument; + use Symfony\Component\Console\Input\InputInterface; + use Symfony\Component\Console\Input\InputOption; + use Symfony\Component\Console\Output\OutputInterface; + + class DemoArgsCommand extends Command + { + protected function configure() + { + $this + ->setName('demo:args') + ->setDescription('Describe args behaviors') + ->setDefinition( + new InputDefinition(array( + new InputOption('foo', 'f'), + new InputOption('bar', 'br', InputOption::VALUE_REQUIRED), + new InputOption('baz', 'bz', InputOption::VALUE_OPTIONAL) + ) + ) + ; + } + + protected function execute(InputInterface $input, OutputInterface $output) + { + // ... + } + } + +Let's take a look to the values results for differents inputs: + +==================== ========================================= +Input Values +==================== ========================================= +--bar=Hello foo = false, bar = "Hello" +--bar Hello foo = false, bar = "Hello" +-br=Hello foo = false, bar = "Hello" +-br Hello foo = false, bar = "Hello" +-brHello foo = false, bar = "Hello" +-fbzWorld -br Hello foo = true, bar = "Hello", baz = "World" +-bzfWorld -br Hello foo = false, bar = "Hello", baz ="fWorld" +-bzbrWorld foo = false, bz = "brWorld", baz = null +==================== ========================================= + + +Now, assume there is also an optional argument in the input definition:: + + new InputDefinition(array( + // ... + new InputArgument('arg', InputArgument::OPTIONAL), + )); + +========================== ======================================== +Input Values +========================== ======================================== +--bar Hello bar = "Hello", arg = null +--bar Hello World bar = "Hello", arg = "World" +--bar Hello --baz World bar = "Hello", baz = "World", arg = null +--bar Hello --baz -- World bar = "Hello", baz = null, arg = "World" +-b Hello -bz World bar = "Hello", baz = "World", arg = null +========================== ======================================== + +The fourth example shows the special ``--`` seperator which -as you can read +in docopt- seperates the options from the arguments. By that, ``World`` is +no longer interpreted as a value of the ``baz`` option (which has an optional value), +but as the value for the argument. + +.. _docopt: http://docopt.org/ + diff --git a/components/console/index.rst b/components/console/index.rst index c814942d018..b46548de647 100644 --- a/components/console/index.rst +++ b/components/console/index.rst @@ -7,5 +7,6 @@ Console introduction usage single_command_tool + console_arguments events helpers/index diff --git a/components/console/introduction.rst b/components/console/introduction.rst index 0b0df91aae1..5369e93c209 100644 --- a/components/console/introduction.rst +++ b/components/console/introduction.rst @@ -495,6 +495,7 @@ Learn More! * :doc:`/components/console/usage` * :doc:`/components/console/single_command_tool` * :doc:`/components/console/events` +* :doc:`/components/console/console_arguments` .. _Packagist: https://packagist.org/packages/symfony/console .. _ANSICON: https://github.com/adoxa/ansicon/releases diff --git a/components/console/single_command_tool.rst b/components/console/single_command_tool.rst index 5082575def6..609f7a0c2e3 100644 --- a/components/console/single_command_tool.rst +++ b/components/console/single_command_tool.rst @@ -1,5 +1,5 @@ .. index:: - single: Console; Single command application + single: Console; Single command application Building a single Command Application ===================================== From 1ce59eed146a903aa55b8a52784b52660063baaf Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Sat, 1 Nov 2014 12:49:24 +0100 Subject: [PATCH 3/3] finish #3744 --- components/console/console_arguments.rst | 116 ++++++++++++----------- components/map.rst.inc | 1 + 2 files changed, 62 insertions(+), 55 deletions(-) diff --git a/components/console/console_arguments.rst b/components/console/console_arguments.rst index 1212e96d955..0b998961c32 100644 --- a/components/console/console_arguments.rst +++ b/components/console/console_arguments.rst @@ -8,19 +8,18 @@ It can be difficult to understand the way arguments are handled by the console a The Symfony Console application, like many other CLI utility tools, follows the behavior described in the `docopt`_ standards. -Let's see a complete example on how the arguments are understood by Console application, -regarding to the Console Options or Arguments defined in the application:: +Have a look at the following command that has three options:: - namespace Acme\Console\Command; + namespace Acme\Console\Command; - use Symfony\Component\Console\Command\Command; - use Symfony\Component\Console\Input\InputArgument; - use Symfony\Component\Console\Input\InputInterface; - use Symfony\Component\Console\Input\InputOption; - use Symfony\Component\Console\Output\OutputInterface; + use Symfony\Component\Console\Command\Command; + use Symfony\Component\Console\Input\InputArgument; + use Symfony\Component\Console\Input\InputInterface; + use Symfony\Component\Console\Input\InputOption; + use Symfony\Component\Console\Output\OutputInterface; - class DemoArgsCommand extends Command - { + class DemoArgsCommand extends Command + { protected function configure() { $this @@ -29,56 +28,63 @@ regarding to the Console Options or Arguments defined in the application:: ->setDefinition( new InputDefinition(array( new InputOption('foo', 'f'), - new InputOption('bar', 'br', InputOption::VALUE_REQUIRED), - new InputOption('baz', 'bz', InputOption::VALUE_OPTIONAL) - ) - ) - ; + new InputOption('bar', 'b', InputOption::VALUE_REQUIRED), + new InputOption('cat', 'c', InputOption::VALUE_OPTIONAL), + )) + ); } protected function execute(InputInterface $input, OutputInterface $output) { // ... } - } - -Let's take a look to the values results for differents inputs: - -==================== ========================================= -Input Values -==================== ========================================= ---bar=Hello foo = false, bar = "Hello" ---bar Hello foo = false, bar = "Hello" --br=Hello foo = false, bar = "Hello" --br Hello foo = false, bar = "Hello" --brHello foo = false, bar = "Hello" --fbzWorld -br Hello foo = true, bar = "Hello", baz = "World" --bzfWorld -br Hello foo = false, bar = "Hello", baz ="fWorld" --bzbrWorld foo = false, bz = "brWorld", baz = null -==================== ========================================= - - -Now, assume there is also an optional argument in the input definition:: - - new InputDefinition(array( - // ... - new InputArgument('arg', InputArgument::OPTIONAL), - )); - -========================== ======================================== -Input Values -========================== ======================================== ---bar Hello bar = "Hello", arg = null ---bar Hello World bar = "Hello", arg = "World" ---bar Hello --baz World bar = "Hello", baz = "World", arg = null ---bar Hello --baz -- World bar = "Hello", baz = null, arg = "World" --b Hello -bz World bar = "Hello", baz = "World", arg = null -========================== ======================================== - -The fourth example shows the special ``--`` seperator which -as you can read -in docopt- seperates the options from the arguments. By that, ``World`` is -no longer interpreted as a value of the ``baz`` option (which has an optional value), -but as the value for the argument. + } + +Since the ``foo`` option doesn't accept a value, it will be either ``false`` +(when it is not passed to the command) or ``true`` (when ``--foo`` was passed +by the user). The value of the ``bar`` option (and its ``b`` shortcut respectively) +is required. It can be separated from the option name either by spaces or +``=`` characters. The ``cat`` option (and its ``c`` shortcut) behaves similar +except that it doesn't require a value. Have a look at the following table +to get an overview of the possible ways to pass options: + +===================== ========= =========== ============ +Input ``foo`` ``bar`` ``cat`` +===================== ========= =========== ============ +``--bar=Hello`` ``false`` ``"Hello"`` ``null`` +``--bar Hello`` ``false`` ``"Hello"`` ``null`` +``-b=Hello`` ``false`` ``"Hello"`` ``null`` +``-b Hello`` ``false`` ``"Hello"`` ``null`` +``-bHello`` ``false`` ``"Hello"`` ``null`` +``-fcWorld -b Hello`` ``true`` ``"Hello"`` ``"World"`` +``-cfWorld -b Hello`` ``false`` ``"Hello"`` ``"fWorld"`` +``-cbWorld`` ``false`` ``null`` ``"bWorld"`` +===================== ========= =========== ============ + +Things get a little bit more tricky when the command also accepts an optional +argument:: + + // ... + + new InputDefinition(array( + // ... + new InputArgument('arg', InputArgument::OPTIONAL), + )); + +You might have to use the special ``--`` separator to separate options from +arguments. Have a look at the fifth example in the following table where it +is used to tell the command that ``World`` is the value for ``arg`` and not +the value of the optional ``cat`` option: + +============================== ================= =========== =========== +Input ``bar`` ``cat`` ``arg`` +============================== ================= =========== =========== +``--bar Hello`` ``"Hello"`` ``null`` ``null`` +``--bar Hello World`` ``"Hello"`` ``null`` ``"World"`` +``--bar "Hello World"`` ``"Hello World"`` ``null`` ``null`` +``--bar Hello --cat World`` ``"Hello"`` ``"World"`` ``null`` +``--bar Hello --cat -- World`` ``"Hello"`` ``null`` ``"World"`` +``-b Hello -c World`` ``"Hello"`` ``"World"`` ``null`` +============================== ================= =========== =========== .. _docopt: http://docopt.org/ - diff --git a/components/map.rst.inc b/components/map.rst.inc index 572f19352d8..529a132b418 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -21,6 +21,7 @@ * :doc:`/components/console/introduction` * :doc:`/components/console/usage` * :doc:`/components/console/single_command_tool` + * :doc:`/components/console/console_arguments` * :doc:`/components/console/events` * :doc:`/components/console/helpers/index`