finish #3744

Author: xabbuh

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/
-

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`