Re-order optional arguments in usage strings to appear before required arguments

[manfredlotz]

Hi Kevin,
First of all, your videos are really great. Thanks for this.
Question: I played with fake and when invokind fake like this:
./target/debug/fake --help
one of the lines is this:
fake [FLAGS] [OPTIONS]

Shouldn't it be the other way round?
fake [FLAGS] [OPTIONS]

-- Manfred

[manfredlotz]

Sorry I wanted to say that I got this line
fake [FLAGS] [OPTIONS]
instead of that line:
fake [FLAGS] [OPTIONS]

(Didn't know I have to escape < and >)
-- Manfred

[kbknapp]

I'm in the process of updating the videos now actually :) There have been some significant changes/improvements since those were made.

As for your question though, yes and no. "No" because it works either way; as the optional flags and optional options could go before or after the required arguments and work just fine.
"Yes" because traditionally optional arguments come before required ones in usage strings. The reason they appear that way is due to how clap parses required arguments for very complex usage strings (even though fake's arguments aren't complex, it's still a bi-product). The way you can in effect read that usage string is: "fake takes two required positional arguments, first 'input' and second 'output' there are also several other optional flags and options which are position independent." If you were to add additional optional positional arguments you'd see a [POSITIONAL] pre-pended as well meaning, "There are also one or more optional positional arguments."

If you need to change the usage string (to match documentation or anything), you can use App::usage("fake [FLAGS] [OPTIONS] <input> <output>") to override the auto-generated one. There is a drawback to this approach though; you no longer can take advantage of "smart" or "context aware" usage strings for that command, as clap will just spit out the one you provided no matter what. So it's a trade-off, but there are some very valid times you may want to do that.

Hope this answers your question :) If not, feel free to contact me!

Edit: And thanks for watching the videos and taking the time to comment!! 👍

[manfredlotz]

Yes, I know that it works either way. I only think it is more 'natural' to have flags and options coming first. IIRC, then in the samples you presented in the videos it came out more naturally like this:
fake [FLAGS]

[kbknapp]

I think you're correct as well. If I get some time this weekend I'll take a look at some possible ways to re-order them back to the expected way. I've got some ideas on how to do so, I just need to test them :)

[manfredlotz]

Sounds great. Thx a lot.

[kbknapp]

Turned out to be way easier than I imagined, so I've just put in a PR to correct this to the more standard natural order. I've also change [POSITIONALS] to [ARGS] in usage strings because thats the more standard vernacular.

Once Travis passes I'll merge this into master and upload 1.0.2 to crates.io

Thanks again for taking the time to file this!

[kbknapp]

1.0.2 on crates.io or master here is good to go now! Once I finish these updated videos everything should be back in sync ;)

[manfredlotz]

Just tested. Works fine.
Thanks a lot for reacting such quickly.