#2548: cargo run --example should print available examples

[AndrewJakubowicz]

Partial fix for this issue.

Handles the more common case. Everything else falls through.
It would be interesting to consider a way of catching docopt errors to improve future error messages in cargo's arguments and flags.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @matklad (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[matklad]

r? @alexcrichton

[alexcrichton]

Thanks for this!

I wonder if we could perhaps refactor this slightly to be a bit more extensible? For example this doesn't cover flags like --bin, --test, --bench, etc. Would it be possible to restructure and allow fixing those as well?

[AndrewJakubowicz]

Thank you for the review @alexcrichton !

Currently I've been focusing on cargo run flags. You've made me aware that cargo test --example should also fail in the same way as cargo run --example does.

Am I correct in assuming the --test and --bench flags would be related to cargo test?

Finally, I'm struggling to find cargo documentation on the --bench flag. Would this list .rs files containing the #[bench] attribute?

I'll have a go at implementing your suggestion.

[alexcrichton]

Ah they're all pretty similar and accepted by a number of subcommands, but they're related to the targets (like entries in tests/*.rs) but benches are in benches/*.rs.

[AndrewJakubowicz]

Hi Alex,

I'm not feeling confident in how to implement a general fix yet. So I'm putting this off until I understand how to use those tools better. I'm also going to explore docopt more, because the fix may be better off there? Otherwise we're intercepting strings. I feel like I'd need to add tests to make sure the string intercepting doesn't fail.

I'm sorry about my slow turnarounds.

[alexcrichton]

Ah no worries! In the meantime though this may actually want to hold off on more investigation until we sort out #5152 as we may be switching to clap anyway! I do agree though that exploring a better option here may necessitate changes in the command line parser itself, although I suspect that may be a bit easier in clap!

[bors]

☔ The latest upstream changes (presumably #5152) made this pull request unmergeable. Please resolve the merge conflicts.

[matklad]

@SpyR1014 so we've successfully migrated to clap, so I think it should be easier right now to give an error when --example is missing an argument.

Currently, the --example argument is defined over here:

cargo/src/bin/command_prelude.rs

Line 59 in 8cc8f3b

._arg(multi_opt("example", "NAME", examle))

And it is processed over here:

cargo/src/bin/command_prelude.rs

Line 261 in 8cc8f3b

self._values_of("example"),

To fix this issue, I think first of all we should tell clap that it's okay to actually supply zero arguments to it. I think it could be done with .min_values(0).max_values(1). Then, when preparing compiler options, we should determine if we are in the --example case, and print available examples!

The same could probably work for bin, test and bench as well?

[AndrewJakubowicz]

@matklad Thank you for the help, and congratulations on the migration!
I'll have a go at the fix and ask questions as they arise.

[AndrewJakubowicz]

Closing as I am unable to make progress.