@@ -179,6 +179,15 @@ values after a white space or an ``=`` sign (e.g. ``--iterations 5`` or
179179``--iterations=5 ``), but short options can only use white spaces or no
180180separation at all (e.g. ``-i 5 `` or ``-i5 ``).
181181
182+ ..caution ::
183+
184+ While it is possible to separate an option from its value with a white space,
185+ using this form leads to an ambiguity should the option appear before the
186+ command name. For example, ``php app/console --iterations 5 app:greet Fabien ``
187+ is ambiguous; Symfony would interpret ``5 `` as the command name. To avoid
188+ this situation, always place options after the command name, or avoid using
189+ a space to separate the option name from its value.
190+
182191There are four option variants you can use:
183192
184193``InputOption::VALUE_IS_ARRAY ``
@@ -209,21 +218,53 @@ You can combine ``VALUE_IS_ARRAY`` with ``VALUE_REQUIRED`` or
209218 array('blue', 'red')
210219 );
211220
212- ..tip ::
221+ Options with optional arguments
222+ -------------------------------
223+
224+ There is nothing forbidding you to create a command with an option that
225+ optionally accepts a value, but it's a bit tricky. Consider this example::
226+
227+ // ...
228+ use Symfony\Component\Console\Input\InputOption;
229+
230+ $this
231+ // ...
232+ ->addOption(
233+ 'yell',
234+ null,
235+ InputOption::VALUE_OPTIONAL,
236+ 'Should I yell while greeting?'
237+ );
238+
239+ This option can be used in 3 ways: ``--yell ``, ``yell=louder ``, and not passing
240+ the option at all. However, it's hard to distinguish between passing the option
241+ without a value (``greet --yell ``) and not passing the option (``greet ``).
242+
243+ To solve this issue, you have to set the option's default value to ``false ``::
244+
245+ // ...
246+ use Symfony\Component\Console\Input\InputOption;
247+
248+ $this
249+ // ...
250+ ->addOption(
251+ 'yell',
252+ null,
253+ InputOption::VALUE_OPTIONAL,
254+ 'Should I yell while greeting?',
255+ false // this is the new default value, instead of null
256+ );
213257
214- There is nothing forbidding you to create a command with an option that
215- optionally accepts a value. However, there is no way you can distinguish
216- when the option was used without a value (`` command --language ``) or when
217- it wasn't used at all (`` command ``). In both cases, the value retrieved for
218- the option will be `` null ``.
258+ Now check the value of the option and keep in mind that `` false !== null ``::
259+
260+ $optionValue = $input->getOptions('yell');
261+ $yell = ($optionValue !== false);
262+ $yellLouder = ($optionValue === 'louder');
219263
220264..caution ::
221265
222- While it is possible to separate an option from its value with a white space,
223- using this form leads to an ambiguity should the option appear before the
224- command name. For example, ``php bin/console --iterations 5 app:greet Fabien ``
225- is ambiguous; Symfony would interpret ``5 `` as the command name. To avoid
226- this situation, always place options after the command name, or avoid using
227- a space to separate the option name from its value.
266+ Due to a PHP limitation, passing an empty string is indistinguishable from
267+ not passing any value at all. In ``command --prefix `` and ``command --prefix='' ``
268+ cases, the value of the ``prefix `` option will be ``null ``.
228269
229270.. _`docopt standard` :http://docopt.org/