finish symfony#3744

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
@@ -30,55 +29,61 @@ regarding to the Console Options or Arguments defined in the application::
                     new InputDefinition(array(
                         new InputOption('foo', 'f'),
                         new InputOption('bar', 'br', InputOption::VALUE_REQUIRED),
-                        new InputOption('baz', 'bz', InputOption::VALUE_OPTIONAL)
-                    )
-                )
-            ;
+                        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.
+    }
+
+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 used
+by the user. The value of the ``bar`` option (and its ``br`` shortcut respectively)
+is required. It can be separated from the option name either by spaces or
+``=`` characters. The same goes for the ``baz`` option (and its ``bz`` shortcut).
+Have a look at the following table to get an overview of the possible ways
+to pass options:
+
+======================== ========= =========== =============
+Input                     ``foo``   ``bar``     ``baz``
+======================== ========= =========== =============
+``--bar=Hello``          ``false`` ``"Hello"`` ``null``
+``--bar Hello``          ``false`` ``"Hello"`` ``null``
+``-br=Hello``            ``false`` ``"Hello"`` ``null``
+``-br Hello``            ``false`` ``"Hello"`` ``null``
+``-brHello``             ``false`` ``"Hello"`` ``null``
+``-fbzWorld -br Hello``  ``true``  ``"Hello"`` ``"World"``
+``-bzfWorld -br Hello``  ``false`` ``"Hello"`` ``"fWorld"``
+``-bzbrWorld``           ``false`` ``null``    ``"brWorld"``
+======================== ========= =========== =============
+
+Things get a little bit more tricky when the command also accepts an optional
+argument::
+
+    // ...
+
+    new InputDefinition(array(
+        // ...
+        new InputArgument('arg', InputArgument::OPTIONAL),
+    ));
+
+You will have to use the special ``--`` separator to separate options from
+arguments. Have a look at the fourth 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 ``baz`` option:
+
+============================== =========== =========== ===========
+Input                          ``bar``     ``baz``     ``arg``
+============================== =========== =========== ===========
+``--bar Hello``                ``"Hello"`` ``null``    ``null``
+``--bar Hello World``          ``"Hello"`` ``null``    ``"World"``
+``--bar Hello --baz World``    ``"Hello"`` ``"World"`` ``null``
+``--bar Hello --baz -- World`` ``"Hello"`` ``null``    ``"World"``
+``-b Hello -bz World``         ``"Hello"`` ``"World"`` ``null``
+============================== =========== =========== ===========
 
 .. _docopt: http://docopt.org/
-

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`