From f513fc1dcb45a084b680123a57f96945ca4fcddb Mon Sep 17 00:00:00 2001 From: Greg Anderson Date: Fri, 2 Mar 2018 12:05:42 -0800 Subject: [PATCH 1/4] Clarify how to use short options with values. Adds a brief description of the correct syntax for short options that take values. --- console/input.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/console/input.rst b/console/input.rst index 0753ae85bd6..03ad6874de7 100644 --- a/console/input.rst +++ b/console/input.rst @@ -174,6 +174,8 @@ flag: 1 ); +Note that while long options are separated from their value with an ``=`` character, e.g. ``--iterations=5``, short options do not use any separator. The short option variant of the previous example would therefore be ``-i5``. + There are four option variants you can use: ``InputOption::VALUE_IS_ARRAY`` @@ -184,7 +186,7 @@ There are four option variants you can use: behavior of options; ``InputOption::VALUE_REQUIRED`` - This value is required (e.g. ``--iterations=5``), the option itself is + This value is required (e.g. ``--iterations=5`` or ``-i5``), the option itself is still optional; ``InputOption::VALUE_OPTIONAL`` From a705f80d9d07ad2e7adcf523d1b9f7b8c872f877 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 5 Mar 2018 14:40:19 +0100 Subject: [PATCH 2/4] Wrap long lines --- console/input.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/console/input.rst b/console/input.rst index 03ad6874de7..41dd4de9f40 100644 --- a/console/input.rst +++ b/console/input.rst @@ -174,7 +174,9 @@ flag: 1 ); -Note that while long options are separated from their value with an ``=`` character, e.g. ``--iterations=5``, short options do not use any separator. The short option variant of the previous example would therefore be ``-i5``. +Note that while long options are separated from their value with an ``=`` +character, e.g. ``--iterations=5``, short options do not use any separator. The +short option variant of the previous example would therefore be ``-i5``. There are four option variants you can use: From c436cead2a6a5bc649c0fc4e6dfa674f1f507b23 Mon Sep 17 00:00:00 2001 From: Greg Anderson Date: Mon, 5 Mar 2018 08:09:39 -0800 Subject: [PATCH 3/4] Clarify Symfony Console option conventions Add link to docopt standard and describe Symfony limitation in using spaces in option name/value pairs. --- console/input.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/console/input.rst b/console/input.rst index 41dd4de9f40..3e36b39afe9 100644 --- a/console/input.rst +++ b/console/input.rst @@ -215,3 +215,20 @@ You can combine ``VALUE_IS_ARRAY`` with ``VALUE_REQUIRED`` or when the option was used without a value (``command --language``) or when it wasn't used at all (``command``). In both cases, the value retrieved for the option will be ``null``. + +Note that to comply with the `docopt standard`_, long options can specify their +values after a white space or an ``=`` sign (e.g. ``--iterations 5`` or +``--iterations=5``), but short options can only use white spaces or no +separation at all (e.g. ``-i 5`` or ``-i5``). + +.. _`docopt standard`: http://docopt.org/ + +.. tip:: + + While it is possible to use whitespace to separate an option from its value, + using this form leads to an ambiguity should the option appear before the + command name. In other words, ``php bin/console --iterations 5 app:greet Fabien`` + is ambiguous; Symfony would interpret ``5`` as the command name. To avoid + this situation, always place options after the command name, or avoid using + a space to separate the option name from its value. + From 27f8ab3999cc08f1ca9f47582341c1d51bc2a880 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 7 Mar 2018 10:23:07 +0100 Subject: [PATCH 4/4] Minor tweaks --- console/input.rst | 27 +++++++++++---------------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/console/input.rst b/console/input.rst index 3e36b39afe9..f74ce28425b 100644 --- a/console/input.rst +++ b/console/input.rst @@ -174,9 +174,10 @@ flag: 1 ); -Note that while long options are separated from their value with an ``=`` -character, e.g. ``--iterations=5``, short options do not use any separator. The -short option variant of the previous example would therefore be ``-i5``. +Note that to comply with the `docopt standard`_, long options can specify their +values after a white space or an ``=`` sign (e.g. ``--iterations 5`` or +``--iterations=5``), but short options can only use white spaces or no +separation at all (e.g. ``-i 5`` or ``-i5``). There are four option variants you can use: @@ -188,8 +189,8 @@ There are four option variants you can use: behavior of options; ``InputOption::VALUE_REQUIRED`` - This value is required (e.g. ``--iterations=5`` or ``-i5``), the option itself is - still optional; + This value is required (e.g. ``--iterations=5`` or ``-i5``), the option + itself is still optional; ``InputOption::VALUE_OPTIONAL`` This option may or may not have a value (e.g. ``--yell`` or @@ -216,19 +217,13 @@ You can combine ``VALUE_IS_ARRAY`` with ``VALUE_REQUIRED`` or it wasn't used at all (``command``). In both cases, the value retrieved for the option will be ``null``. -Note that to comply with the `docopt standard`_, long options can specify their -values after a white space or an ``=`` sign (e.g. ``--iterations 5`` or -``--iterations=5``), but short options can only use white spaces or no -separation at all (e.g. ``-i 5`` or ``-i5``). - -.. _`docopt standard`: http://docopt.org/ +.. caution:: -.. tip:: - - While it is possible to use whitespace to separate an option from its value, + While it is possible to separate an option from its value with a white space, using this form leads to an ambiguity should the option appear before the - command name. In other words, ``php bin/console --iterations 5 app:greet Fabien`` + command name. For example, ``php bin/console --iterations 5 app:greet Fabien`` is ambiguous; Symfony would interpret ``5`` as the command name. To avoid this situation, always place options after the command name, or avoid using a space to separate the option name from its value. - + +.. _`docopt standard`: http://docopt.org/