cargo run --example should print available examples

[tyoc213]

if you clone a repo and has examples and you run _cargo run --example_ you only get help for general usage, what about print the actual examples on the examples directory?

$ cargo run --example
Expected argument for flag '--example' but reached end of arguments.

Usage:
    cargo run [options] [--] [<args>...]

If there where one.rs, two.rs and three.rs inside examples folder it could output something like

$ cargo run --example
Expected argument for flag '--example' but reached end of arguments.

Available examples are: one, two and three.

Usage:
    cargo run [options] [--] [<args>...]

Even more, it can autocomplete the name of the example... well that will be only a NTH.

[alexcrichton]

Sounds like a good suggestion to me!

[AndrewJakubowicz]

Can I work on this @alexcrichton?

[alexcrichton]

Certainly @SpyR1014! If you have any questions just lemme know

[AndrewJakubowicz]

I've poked around the codebase and am unsure where the best place to intercept and update this error is.

Here's a commit with my attempt at handling the error. I haven't implemented the examples path logic as I feel there are other problems.

The error is created by Docopt and I can't find a way to manipulate the error within Docopt. This leaves the error handling to cargo where I've implemented the intercept logic. Currently it's a hideous if statement.

I'm not sure this is a good design, and am not familiar enough to think of another solution.

Pros of the solution:

• Right next to the error source.
• Easy to intercept.

Cons:

• Will require code in the lib.rs to locate the workspace, examples directory and the files.

I would appreciate any pointers before continuing. Thank you in advance for any help! :)

[alexcrichton]

Hm yeah it's true we don't have a lot of experience right now catching docopt errors and printing something as a result.

I'm unfortunately not sure how we'd implement a fix for this in a "clean" fashion, so failing that I think it may be ok to special case this for now. Basically if arguments like --example are passed and have no value, we could catch that docopt error, remove the arg, attempt to parse again, and if successful we should have enough information to start printing diagnostics, right?

[AndrewJakubowicz]

Thank you so much for your response Alex. I've implemented a mostly working solution here

I'm unable to figure out how to get the flag_manifest_path field from the docopts object without access to run's Options struct.

Because of this, the error is only updated if the cwd is the workspace root directory. This is better than nothing.

Example output of running on my test file with an examples directory:

Test 1

├── junk.txt
├── sorting.rs
└── suffix.rs

gives:

error: Expected argument for flag '--example' but reached end of arguments.

Available examples are: sorting and suffix

Usage:
    cargo run [options] [--] [<args>...]

Test 2 - Empty examples directory

Output:

error: Expected argument for flag '--example' but reached end of arguments.

There are no examples in the 'examples' directory

Usage:
    cargo run [options] [--] [<args>...]

Test 3 - Multiple examples

├── one.rs
├── three.rs
└── two.rs

gives:

error: Expected argument for flag '--example' but reached end of arguments.

Available examples are: one, three and two

Usage:
    cargo run [options] [--] [<args>...]

[sanmai-NL]

@AndrewJakubowicz: can you give an update on this?

[derekdreery]

I've played with implementing this by hooking into the error, but you need the arguments to work out what examples are appropriate. Therefore, I think you need something like https://github.com/clap-rs/clap/issues/1354 to implement this.

[AndrewJakubowicz]

@sanmai-NL I have not had a chance to look at this for some time or how this might work after the migration to clap.

@matklad left guidance to move forward here: https://github.com/rust-lang/cargo/pull/5062#issuecomment-373852496