[WIP] [Console] Added Console arguments documentation #3744

mickaelandrieu · 2014-04-01T09:32:41Z

Q	A
Doc fix?	yes
New docs?	no
Applies to?	2.3, 2.4, 2.5
Fixed tickets?	no

xabbuh · 2014-04-01T10:24:02Z

components/console/introduction.rst

@@ -292,7 +292,7 @@ declare a one-letter shortcut that you can call with a single dash like
 .. tip::

    It is also possible to make an option *optionally* accept a value (so that
-    ``--yell`` or ``--yell=loud`` work). Options can also be configured to
+    ``--yell`` or ``--yell=loud`` or ``--yell loud`` work). Options can also be configured to


I don't think that this does always work. If the value for the --yell option is optional loud would be treated as an argument, won't it?

no, it will be treated as the value being provided

It does : symfony/symfony#10603 (comment)

It's a little bit weird indeed.

Weird. But if it is intended.

The behaviour is following the docopt standards.

Assume the following InputDefinition:

new InputDefinition(array( new InputOption('foo', 'f'), new InputOption('bar', 'b', InputOption::VALUE_REQUIRED), new InputOption('cat', 'c', InputOption::VALUE_OPTIONAL), ));

The behaviour is:

Input Values

--bar=Hello foo = false, bar = "Hello"

--bar Hello foo = false, bar = "Hello"

-b Hello foo = false, bar = "Hello"

-b=Hello foo = false, bar = "=Hello"

-bHello foo = false, bar = "Hello"

-fbHello foo = true, bar = "Hello"

-fcHello -b World foo = true, bar = "World", cat = "Hello"

-cfHello -b World foo = false, bar = "World", cat = "fHello"

-cbHello cat = "bHello", bar = null

Now, assume there is also an optional argument in the input definition:

new InputDefinition(array( // ... new InputArgument('qux', InputArgument::OPTIONAL), ));

The behaviour now:

Input Values

--bar Hello bar = "Hello", qux = null

--bar Hello World bar = "Hello", qux = "World"

--bar Hello --cat World bar = "Hello", cat = "World", qux = null

--bar Hello --cat -- World bar = "Hello", cat = null, qux = "World"

-b Hello -c World bar = "Hello", cat = "World", qux = 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 cat option (which has an optional value), but as the value for the argument.

mickaelandrieu · 2014-04-01T11:58:59Z

@wouterj thanks a lot for this ! Maybe should we notice this on the documentation:
What do you think ?

wouterj · 2014-04-01T12:18:39Z

@mickaelandrieu we shoul definitely document this behaviour if it is not done yet. Btw, please note that I updated it with more examples, also using arguments.

mickaelandrieu · 2014-04-01T12:42:05Z

@wouterj as far as I know it's not documented yet.
I will improve my PR to document this behavior too ;)

PS: can I use your examples or did you prefer to do your own PR ?

wouterj · 2014-04-01T12:52:20Z

PS: can I use your examples or did you prefer to do your own PR ?

You can always use my examples in OSS :) (and especially in the Symfony docs). However you need to make it somewhat nice to read, not this reference like table thing.

mickaelandrieu · 2014-04-09T00:25:51Z

Thanks to your useful samples, I've improved my work with yours :)

Let me know if it's good enough to be added to docs.

xabbuh · 2014-04-09T07:24:12Z

components/console/console_arguments.rst

+.. index::
+   single: Console; Console arguments
+
+Understand how are handled Console arguments


How Console Arguments are Handled

Done, modified by How Console Arguments are handled

wouterj · 2014-04-09T15:49:35Z

Thank you @mickaelandrieu.

However, I would rather want text instead of a table full of examples. Then after the text, we can say "For examples, see this table:".

mickaelandrieu · 2014-04-10T14:21:35Z

@wouterj I'm working on it, "stay tuned" 💃

wouterj · 2014-05-21T09:36:34Z

@mickaelandrieu what is the status of this?

mickaelandrieu · 2014-05-21T09:55:53Z

@wouterj I'm very busy for now :/ but I will finish this.

xabbuh · 2014-08-08T12:46:20Z

ping @mickaelandrieu

mickaelandrieu · 2014-08-08T15:08:10Z

aww I'll try to finish this one tommorow, only need text documentation illustrated by examples provided by @wouterj right ?

xabbuh · 2014-08-08T15:17:35Z

@mickaelandrieu I think so.

wouterj · 2014-08-09T17:05:32Z

@mickaelandrieu correct

xabbuh · 2014-10-07T11:18:18Z

@mickaelandrieu Do you have time to finish this? If you don't have the time, someone could take this over and finish the nice work you did so far.

mickaelandrieu · 2014-10-07T12:43:35Z

For now, I don't have time :/

I agree to let someone finish this.

Sorry for the inconvenience

wouterj · 2014-10-07T13:30:06Z

I'll finish it, no problem. Thanks for starting this!
Op 7 okt. 2014 14:43 schreef "Mickaël Andrieu" [email protected]:

For now, I don't have time :/

I agree to let someone finish this.

Sorry for the inconvenience

—
Reply to this email directly or view it on GitHub
#3744 (comment).

xabbuh · 2014-11-01T11:53:04Z

@mickaelandrieu Thank you very much for starting this great work! I took this over in #4405.

@mickaelandrieu

This PR was merged into the 2.3 branch. Discussion ---------- Finish 3744 This finishes the great pull request started by @mickaelandrieu in #3744. Commits ------- 1ce59ee finish #3744 f503596 [WIP] - Console add Console arguments page d2b69b6 Added a little sample on Option uses with "spaces"

* 2.3: Fixed typos Update web_server_configuration.rst Update web_server_configuration.rst remove service class parameters Some fixes backport service factory improvements Minor standard fix for best practices guide Minor tweak Don't use form() helper Apply best practices to forms Use AppBundle instead of AcmeStoreBundle Other minor fixes Use AppBundle instead of AcmeDemoBundle link to a bundle's current (not master) docs finish #3744 [WIP] - Console add Console arguments page Added a little sample on Option uses with "spaces" Conflicts: components/map.rst.inc

* 2.5: Fixed typos Update web_server_configuration.rst Update web_server_configuration.rst remove service class parameters Some fixes backport service factory improvements Minor standard fix for best practices guide Minor tweak Don't use form() helper Apply best practices to forms Use AppBundle instead of AcmeStoreBundle Other minor fixes Use AppBundle instead of AcmeDemoBundle link to a bundle's current (not master) docs finish #3744 [WIP] - Console add Console arguments page Added a little sample on Option uses with "spaces" Conflicts: book/forms.rst components/dependency_injection/factories.rst cookbook/profiler/matchers.rst cookbook/security/securing_services.rst

Added a little sample on Option uses with "spaces"

efd2502

xabbuh reviewed Apr 1, 2014
View reviewed changes

mickaelandrieu changed the title ~~Added a little sample on Option uses with "spaces"~~ [Console] Added Console arguments documentation Apr 8, 2014

xabbuh reviewed Apr 9, 2014
View reviewed changes

[WIP] - Console add Console arguments page

8dff92c

wouterj changed the title ~~[Console] Added Console arguments documentation~~ [WIP] [Console] Added Console arguments documentation May 21, 2014

wouterj added the In progress label Aug 15, 2014

xabbuh added a commit to xabbuh/symfony-docs that referenced this pull request Nov 1, 2014

finish symfony#3744

74d2f77

xabbuh mentioned this pull request Nov 1, 2014

Finish 3744 #4405

Merged

xabbuh closed this Nov 1, 2014

mickaelandrieu deleted the patch-1 branch November 1, 2014 12:28

xabbuh added a commit to xabbuh/symfony-docs that referenced this pull request Nov 1, 2014

finish symfony#3744

0bfd2d9

xabbuh added a commit to xabbuh/symfony-docs that referenced this pull request Nov 7, 2014

finish symfony#3744

1ce59ee

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] [Console] Added Console arguments documentation #3744

[WIP] [Console] Added Console arguments documentation #3744

mickaelandrieu commented Apr 1, 2014

xabbuh Apr 1, 2014

stof Apr 1, 2014

mickaelandrieu Apr 1, 2014

xabbuh Apr 1, 2014

wouterj Apr 1, 2014

mickaelandrieu commented Apr 1, 2014

wouterj commented Apr 1, 2014

mickaelandrieu commented Apr 1, 2014

wouterj commented Apr 1, 2014

mickaelandrieu commented Apr 9, 2014

xabbuh Apr 9, 2014

mickaelandrieu Apr 9, 2014

wouterj commented Apr 9, 2014

mickaelandrieu commented Apr 10, 2014

wouterj commented May 21, 2014

mickaelandrieu commented May 21, 2014

xabbuh commented Aug 8, 2014

mickaelandrieu commented Aug 8, 2014

xabbuh commented Aug 8, 2014

wouterj commented Aug 9, 2014

xabbuh commented Oct 7, 2014

mickaelandrieu commented Oct 7, 2014

wouterj commented Oct 7, 2014

xabbuh commented Nov 1, 2014

Input	Values
`--bar=Hello`	foo = false, bar = "Hello"
`--bar Hello`	foo = false, bar = "Hello"
`-b Hello`	foo = false, bar = "Hello"
`-b=Hello`	foo = false, bar = "=Hello"
`-bHello`	foo = false, bar = "Hello"
`-fbHello`	foo = true, bar = "Hello"
`-fcHello -b World`	foo = true, bar = "World", cat = "Hello"
`-cfHello -b World`	foo = false, bar = "World", cat = "fHello"
`-cbHello`	cat = "bHello", bar = null

Input	Values
`--bar Hello`	bar = "Hello", qux = null
`--bar Hello World`	bar = "Hello", qux = "World"
`--bar Hello --cat World`	bar = "Hello", cat = "World", qux = null
`--bar Hello --cat -- World`	bar = "Hello", cat = null, qux = "World"
`-b Hello -c World`	bar = "Hello", cat = "World", qux = null

[WIP] [Console] Added Console arguments documentation #3744

[WIP] [Console] Added Console arguments documentation #3744

Conversation

mickaelandrieu commented Apr 1, 2014

xabbuh Apr 1, 2014

Choose a reason for hiding this comment

stof Apr 1, 2014

Choose a reason for hiding this comment

mickaelandrieu Apr 1, 2014

Choose a reason for hiding this comment

xabbuh Apr 1, 2014

Choose a reason for hiding this comment

wouterj Apr 1, 2014

Choose a reason for hiding this comment

mickaelandrieu commented Apr 1, 2014

wouterj commented Apr 1, 2014

mickaelandrieu commented Apr 1, 2014

wouterj commented Apr 1, 2014

mickaelandrieu commented Apr 9, 2014

xabbuh Apr 9, 2014

Choose a reason for hiding this comment

mickaelandrieu Apr 9, 2014

Choose a reason for hiding this comment

wouterj commented Apr 9, 2014

mickaelandrieu commented Apr 10, 2014

wouterj commented May 21, 2014

mickaelandrieu commented May 21, 2014

xabbuh commented Aug 8, 2014

mickaelandrieu commented Aug 8, 2014

xabbuh commented Aug 8, 2014

wouterj commented Aug 9, 2014

xabbuh commented Oct 7, 2014

mickaelandrieu commented Oct 7, 2014

wouterj commented Oct 7, 2014

xabbuh commented Nov 1, 2014