@@ -8,19 +8,18 @@ It can be difficult to understand the way arguments are handled by the console a
88The Symfony Console application, like many other CLI utility tools, follows the behavior
99described in the `docopt `_ standards.
1010
11- Let's see a complete example on how the arguments are understood by Console application,
12- regarding to the Console Options or Arguments defined in the application::
11+ Have a look at the following command that has three options::
1312
14- namespace Acme\Console\Command;
13+ namespace Acme\Console\Command;
1514
16- use Symfony\Component\Console\Command\Command;
17- use Symfony\Component\Console\Input\InputArgument;
18- use Symfony\Component\Console\Input\InputInterface;
19- use Symfony\Component\Console\Input\InputOption;
20- use Symfony\Component\Console\Output\OutputInterface;
15+ use Symfony\Component\Console\Command\Command;
16+ use Symfony\Component\Console\Input\InputArgument;
17+ use Symfony\Component\Console\Input\InputInterface;
18+ use Symfony\Component\Console\Input\InputOption;
19+ use Symfony\Component\Console\Output\OutputInterface;
2120
22- class DemoArgsCommand extends Command
23- {
21+ class DemoArgsCommand extends Command
22+ {
2423 protected function configure()
2524 {
2625 $this
@@ -30,55 +29,61 @@ regarding to the Console Options or Arguments defined in the application::
3029 new InputDefinition(array(
3130 new InputOption('foo', 'f'),
3231 new InputOption('bar', 'br', InputOption::VALUE_REQUIRED),
33- new InputOption('baz', 'bz', InputOption::VALUE_OPTIONAL)
34- )
35- )
36- ;
32+ new InputOption('baz', 'bz', InputOption::VALUE_OPTIONAL),
33+ ))
34+ );
3735 }
3836
3937 protected function execute(InputInterface $input, OutputInterface $output)
4038 {
4139 // ...
4240 }
43- }
44-
45- Let's take a look to the values results for differents inputs:
46-
47- ==================== =========================================
48- Input Values
49- ==================== =========================================
50- --bar=Hello foo = false, bar = "Hello"
51- --bar Hello foo = false, bar = "Hello"
52- -br=Hello foo = false, bar = "Hello"
53- -br Hello foo = false, bar = "Hello"
54- -brHello foo = false, bar = "Hello"
55- -fbzWorld -br Hello foo = true, bar = "Hello", baz = "World"
56- -bzfWorld -br Hello foo = false, bar = "Hello", baz ="fWorld"
57- -bzbrWorld foo = false, bz = "brWorld", baz = null
58- ==================== =========================================
59-
60-
61- Now, assume there is also an optional argument in the input definition::
62-
63- new InputDefinition(array(
64- // ...
65- new InputArgument('arg', InputArgument::OPTIONAL),
66- ));
67-
68- ========================== ========================================
69- Input Values
70- ========================== ========================================
71- --bar Hello bar = "Hello", arg = null
72- --bar Hello World bar = "Hello", arg = "World"
73- --bar Hello --baz World bar = "Hello", baz = "World", arg = null
74- --bar Hello --baz -- World bar = "Hello", baz = null, arg = "World"
75- -b Hello -bz World bar = "Hello", baz = "World", arg = null
76- ========================== ========================================
77-
78- The fourth example shows the special ``-- `` seperator which -as you can read
79- in docopt- seperates the options from the arguments. By that, ``World `` is
80- no longer interpreted as a value of the ``baz `` option (which has an optional value),
81- but as the value for the argument.
41+ }
42+
43+ Since the ``foo `` option doesn't accept a value, it will be either ``false ``
44+ (when it is not passed to the command) or ``true `` (when ``--foo `` was used
45+ by the user. The value of the ``bar `` option (and its ``br `` shortcut respectively)
46+ is required. It can be separated from the option name either by spaces or
47+ ``= `` characters. The same goes for the ``baz `` option (and its ``bz `` shortcut).
48+ Have a look at the following table to get an overview of the possible ways
49+ to pass options:
50+
51+ ======================== ========= =========== =============
52+ Input ``foo `` ``bar `` ``baz ``
53+ ======================== ========= =========== =============
54+ ``--bar=Hello `` ``false `` ``"Hello" `` ``null ``
55+ ``--bar Hello `` ``false `` ``"Hello" `` ``null ``
56+ ``-br=Hello `` ``false `` ``"Hello" `` ``null ``
57+ ``-br Hello `` ``false `` ``"Hello" `` ``null ``
58+ ``-brHello `` ``false `` ``"Hello" `` ``null ``
59+ ``-fbzWorld -br Hello `` ``true `` ``"Hello" `` ``"World" ``
60+ ``-bzfWorld -br Hello `` ``false `` ``"Hello" `` ``"fWorld" ``
61+ ``-bzbrWorld `` ``false `` ``null `` ``"brWorld" ``
62+ ======================== ========= =========== =============
63+
64+ Things get a little bit more tricky when the command also accepts an optional
65+ argument::
66+
67+ // ...
68+
69+ new InputDefinition(array(
70+ // ...
71+ new InputArgument('arg', InputArgument::OPTIONAL),
72+ ));
73+
74+ You will have to use the special ``-- `` separator to separate options from
75+ arguments. Have a look at the fourth example in the following table where
76+ it is used to tell the command that ``World `` is the value for ``arg `` and
77+ not the value of the optional ``baz `` option:
78+
79+ ============================== =========== =========== ===========
80+ Input ``bar `` ``baz `` ``arg ``
81+ ============================== =========== =========== ===========
82+ ``--bar Hello `` ``"Hello" `` ``null `` ``null ``
83+ ``--bar Hello World `` ``"Hello" `` ``null `` ``"World" ``
84+ ``--bar Hello --baz World `` ``"Hello" `` ``"World" `` ``null ``
85+ ``--bar Hello --baz -- World `` ``"Hello" `` ``null `` ``"World" ``
86+ ``-b Hello -bz World `` ``"Hello" `` ``"World" `` ``null ``
87+ ============================== =========== =========== ===========
8288
8389.. _docopt : http://docopt.org/
84-
0 commit comments