--example with no argument now lists all available examples

src/bin/cargo/commands/bench.rs

@@ -73,6 +73,9 @@ Compilation can be customized with the `bench` profile in the manifest.
 pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
     let ws = args.workspace(config)?;
     let mut compile_opts = args.compile_options(config, CompileMode::Bench)?;
+
+    args.check_optional_opts_all(&ws, &compile_opts)?;
+
     compile_opts.build_config.release = true;
 
     let ops = TestOptions {

src/bin/cargo/commands/build.rs

@@ -49,6 +49,9 @@ the --release flag will use the `release` profile instead.
 pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
     let ws = args.workspace(config)?;
     let mut compile_opts = args.compile_options(config, CompileMode::Build)?;
+
+    args.check_optional_opts_all(&ws, &compile_opts)?;
+
     compile_opts.export_dir = args.value_of_path("out-dir", config);
     if compile_opts.export_dir.is_some() && !config.cli_unstable().unstable_options {
         Err(failure::format_err!(

src/bin/cargo/commands/check.rs

@@ -69,6 +69,9 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
     };
     let mode = CompileMode::Check { test };
     let compile_opts = args.compile_options(config, mode)?;
+
+    args.check_optional_opts_all(&ws, &compile_opts)?;
+
     ops::compile(&ws, &compile_opts)?;
     Ok(())
 }

src/bin/cargo/commands/fix.rs

@@ -123,6 +123,9 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
     // Unlike other commands default `cargo fix` to all targets to fix as much
     // code as we can.
     let mut opts = args.compile_options(config, mode)?;
+
+    args.check_optional_opts_all(&ws, &opts)?;
+
     if let CompileFilter::Default { .. } = opts.filter {
         opts.filter = CompileFilter::Only {
             all_targets: true,

src/bin/cargo/commands/install.rs

@@ -80,6 +80,10 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
     config.reload_rooted_at_cargo_home()?;
     let mut compile_opts = args.compile_options(config, CompileMode::Build)?;
 
+    let ws = args.workspace(config)?;
+
+    args.check_optional_opts_example_and_bin(&ws, &compile_opts)?;
+
     compile_opts.build_config.release = !args.is_present("debug");
 
     let krates = args

src/bin/cargo/commands/run.rs

@@ -40,6 +40,9 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
     let ws = args.workspace(config)?;
 
     let mut compile_opts = args.compile_options(config, CompileMode::Build)?;
+
+    args.check_optional_opts_example_and_bin(&ws, &compile_opts)?;
+
     if !args.is_present("example") && !args.is_present("bin") {
         let default_runs: Vec<_> = compile_opts
             .spec

src/bin/cargo/commands/test.rs

@@ -94,6 +94,8 @@ pub fn exec(config: &mut Config, args: &ArgMatches<'_>) -> CliResult {
 
     let mut compile_opts = args.compile_options(config, CompileMode::Test)?;
 
+    args.check_optional_opts_all(&ws, &compile_opts)?;
+
     let doc = args.is_present("doc");
     if doc {
         if let CompileFilter::Only { .. } = compile_opts.filter {

src/cargo/util/command_prelude.rs

@@ -7,6 +7,10 @@ use crate::ops::{CompileFilter, CompileOptions, NewOptions, Packages, VersionCon
 use crate::sources::CRATES_IO_REGISTRY;
 use crate::util::important_paths::find_root_manifest_for_wd;
 use crate::util::{paths, validate_package_name};
+use crate::util::{
+    print_available_benches, print_available_binaries, print_available_examples,
+    print_available_tests,
+};
 use crate::CargoResult;
 use clap::{self, SubCommand};
 
@@ -60,18 +64,18 @@ pub trait AppExt: Sized {
         all: &'static str,
     ) -> Self {
         self.arg_targets_lib_bin(lib, bin, bins)
-            ._arg(multi_opt("example", "NAME", example))
+            ._arg(optional_multi_opt("example", "NAME", example))
             ._arg(opt("examples", examples))
-            ._arg(multi_opt("test", "NAME", test))
+            ._arg(optional_multi_opt("test", "NAME", test))
             ._arg(opt("tests", tests))
-            ._arg(multi_opt("bench", "NAME", bench))
+            ._arg(optional_multi_opt("bench", "NAME", bench))
             ._arg(opt("benches", benches))
             ._arg(opt("all-targets", all))
     }
 
     fn arg_targets_lib_bin(self, lib: &'static str, bin: &'static str, bins: &'static str) -> Self {
         self._arg(opt("lib", lib))
-            ._arg(multi_opt("bin", "NAME", bin))
+            ._arg(optional_multi_opt("bin", "NAME", bin))
             ._arg(opt("bins", bins))
     }
 
@@ -82,15 +86,15 @@ pub trait AppExt: Sized {
         example: &'static str,
         examples: &'static str,
     ) -> Self {
-        self._arg(multi_opt("bin", "NAME", bin))
+        self._arg(optional_multi_opt("bin", "NAME", bin))
             ._arg(opt("bins", bins))
-            ._arg(multi_opt("example", "NAME", example))
+            ._arg(optional_multi_opt("example", "NAME", example))
             ._arg(opt("examples", examples))
     }
 
     fn arg_targets_bin_example(self, bin: &'static str, example: &'static str) -> Self {
-        self._arg(multi_opt("bin", "NAME", bin))
+        self._arg(optional_multi_opt("bin", "NAME", bin))
-            ._arg(multi_opt("example", "NAME", example))
+            ._arg(optional_multi_opt("example", "NAME", example))
     }
 
     fn arg_features(self) -> Self {
@@ -193,6 +197,18 @@ pub fn opt(name: &'static str, help: &'static str) -> Arg<'static, 'static> {
     Arg::with_name(name).long(name).help(help)
 }
 
+pub fn optional_multi_opt(
+    name: &'static str,
+    value_name: &'static str,
+    help: &'static str,
+) -> Arg<'static, 'static> {
+    opt(name, help)
+        .value_name(value_name)
+        .multiple(true)
+        .min_values(0)
+        .max_values(1)
+}
+
 pub fn multi_opt(
     name: &'static str,
     value_name: &'static str,
@@ -413,6 +429,50 @@ about this warning.";
         Ok(index)
     }
 
+    fn check_optional_opts_example_and_bin(
+        &self,
+        workspace: &Workspace<'_>,
+        compile_opts: &CompileOptions<'_>,
+    ) -> CliResult {
+        if self.is_present_with_zero_values("example") {
+            print_available_examples(&workspace, &compile_opts)?;
+        }
+
+        if self.is_present_with_zero_values("bin") {
+            print_available_binaries(&workspace, &compile_opts)?;
+        }
+
+        Ok(())
+    }
+
+    fn check_optional_opts_all(
+        &self,
+        workspace: &Workspace<'_>,
+        compile_opts: &CompileOptions<'_>,
+    ) -> CliResult {
+        if self.is_present_with_zero_values("example") {
+            print_available_examples(&workspace, &compile_opts)?;
+        }
+
+        if self.is_present_with_zero_values("bin") {
+            print_available_binaries(&workspace, &compile_opts)?;
+        }
+
+        if self.is_present_with_zero_values("bench") {
+            print_available_benches(&workspace, &compile_opts)?;
+        }
+
+        if self.is_present_with_zero_values("test") {
+            print_available_tests(&workspace, &compile_opts)?;
+        }
+
+        Ok(())
+    }
+
+    fn is_present_with_zero_values(&self, name: &str) -> bool {
+        self._is_present(name) && self._value_of(name).is_none()
+    }
+
     fn _value_of(&self, name: &str) -> Option<&str>;
 
     fn _values_of(&self, name: &str) -> Vec<String>;

src/cargo/util/mod.rs

@@ -22,6 +22,10 @@ pub use self::sha256::Sha256;
 pub use self::to_semver::ToSemver;
 pub use self::to_url::ToUrl;
 pub use self::vcs::{existing_vcs_repo, FossilRepo, GitRepo, HgRepo, PijulRepo};
+pub use self::workspace::{
+    print_available_benches, print_available_binaries, print_available_examples,
+    print_available_tests,
+};
 
 mod cfg;
 pub mod command_prelude;
@@ -49,6 +53,7 @@ pub mod to_semver;
 pub mod to_url;
 pub mod toml;
 mod vcs;
+mod workspace;
 
 pub fn elapsed(duration: Duration) -> String {
     let secs = duration.as_secs();

src/cargo/util/workspace.rs

@@ -0,0 +1,72 @@
+use crate::core::{Target, Workspace};
+use crate::ops::CompileOptions;
+use crate::util::CargoResult;
+
+use std::fmt::Write;
+
+fn get_available_targets<'a>(
+    filter_fn: fn(&Target) -> bool,
+    ws: &'a Workspace<'_>,
+    options: &'a CompileOptions<'_>,
+) -> CargoResult<Vec<&'a Target>> {
+    let packages = options.spec.get_packages(ws)?;
+
+    let targets: Vec<_> = packages
+        .into_iter()
+        .flat_map(|pkg| {
+            pkg.manifest()
+                .targets()
+                .into_iter()
+                .filter(|target| filter_fn(target))
+        })
+        .collect();
+    Ok(targets)
+}
+
+fn print_available(
+    filter_fn: fn(&Target) -> bool,
+    ws: &Workspace<'_>,
+    options: &CompileOptions<'_>,
+    option_name: &str,
+    plural_name: &str,
+) -> CargoResult<()> {
+    let targets = get_available_targets(filter_fn, ws, options)?;
+
+    let mut output = String::new();
+    writeln!(output, "\"{}\" takes one argument.", option_name)?;
+
+    if targets.is_empty() {
+        writeln!(output, "No {} available.", plural_name)?;
+    } else {
+        writeln!(output, "Available {}:", plural_name)?;
+        for target in targets {
+            writeln!(output, "    {}", target.name())?;
+        }
+    }
+    Err(failure::err_msg(output))?
+}
+
+pub fn print_available_examples(
+    ws: &Workspace<'_>,
+    options: &CompileOptions<'_>,
+) -> CargoResult<()> {
+    print_available(Target::is_example, ws, options, "--example", "examples")
+}
+
+pub fn print_available_binaries(
+    ws: &Workspace<'_>,
+    options: &CompileOptions<'_>,
+) -> CargoResult<()> {
+    print_available(Target::is_bin, ws, options, "--bin", "binaries")
+}
+
+pub fn print_available_benches(
+    ws: &Workspace<'_>,
+    options: &CompileOptions<'_>,
+) -> CargoResult<()> {
+    print_available(Target::is_bench, ws, options, "--bench", "benches")
+}
+
+pub fn print_available_tests(ws: &Workspace<'_>, options: &CompileOptions<'_>) -> CargoResult<()> {
+    print_available(Target::is_test, ws, options, "--test", "tests")
+}

tests/testsuite/list_targets.rs

@@ -0,0 +1,237 @@
+use crate::support::project;
+
+// cargo {run,install} only support --example and --bin
+// cargo {build,check,fix,test} support --example, --bin, --bench and --test
+
+fn test_list_targets_example_and_bin_only(command: &str) {
+    let p = project()
+        .file("examples/a.rs", "fn main() { }")
+        .file("examples/b.rs", "fn main() { }")
+        .file("src/main.rs", "fn main() { }")
+        .build();
+
+    p.cargo(&format!("{} --example", command))
+        .with_stderr(
+            "\
+error: \"--example\" takes one argument.
+Available examples:
+    a
+    b
+
+",
+        )
+        .with_status(101)
+        .run();
+
+    p.cargo(&format!("{} --bin", command))
+        .with_stderr(
+            "\
+error: \"--bin\" takes one argument.
+Available binaries:
+    foo
+
+",
+        )
+        .with_status(101)
+        .run();
+}
+
+fn test_empty_list_targets_example_and_bin_only(command: &str) {
+    let p = project().file("src/lib.rs", "").build();
+
+    p.cargo(&format!("{} --example", command))
+        .with_stderr(
+            "\
+error: \"--example\" takes one argument.
+No examples available.
+
+",
+        )
+        .with_status(101)
+        .run();
+
+    p.cargo(&format!("{} --bin", command))
+        .with_stderr(
+            "\
+error: \"--bin\" takes one argument.
+No binaries available.
+
+",
+        )
+        .with_status(101)
+        .run();
+}
+
+fn test_list_targets_full(command: &str) {
+    let p = project()
+        .file("examples/a.rs", "fn main() { }")
+        .file("examples/b.rs", "fn main() { }")
+        .file("benches/bench1.rs", "")
+        .file("benches/bench2.rs", "")
+        .file("tests/test1.rs", "")
+        .file("tests/test2.rs", "")
+        .file("src/main.rs", "fn main() { }")
+        .build();
+
+    p.cargo(&format!("{} --example", command))
+        .with_stderr(
+            "\
+error: \"--example\" takes one argument.
+Available examples:
+    a
+    b
+
+",
+        )
+        .with_status(101)
+        .run();
+
+    p.cargo(&format!("{} --bin", command))
+        .with_stderr(
+            "\
+error: \"--bin\" takes one argument.
+Available binaries:
+    foo
+
+",
+        )
+        .with_status(101)
+        .run();
+
+    p.cargo(&format!("{} --bench", command))
+        .with_stderr(
+            "\
+error: \"--bench\" takes one argument.
+Available benches:
+    bench1
+    bench2
+
+",
+        )
+        .with_status(101)
+        .run();
+
+    p.cargo(&format!("{} --test", command))
+        .with_stderr(
+            "\
+error: \"--test\" takes one argument.
+Available tests:
+    test1
+    test2
+
+",
+        )
+        .with_status(101)
+        .run();
+}
+
+fn test_empty_list_targets_full(command: &str) {
+    let p = project().file("src/lib.rs", "").build();
+
+    p.cargo(&format!("{} --example", command))
+        .with_stderr(
+            "\
+error: \"--example\" takes one argument.
+No examples available.
+
+",
+        )
+        .with_status(101)
+        .run();
+
+    p.cargo(&format!("{} --bin", command))
+        .with_stderr(
+            "\
+error: \"--bin\" takes one argument.
+No binaries available.
+
+",
+        )
+        .with_status(101)
+        .run();
+
+    p.cargo(&format!("{} --bench", command))
+        .with_stderr(
+            "\
+error: \"--bench\" takes one argument.
+No benches available.
+
+",
+        )
+        .with_status(101)
+        .run();
+
+    p.cargo(&format!("{} --test", command))
+        .with_stderr(
+            "\
+error: \"--test\" takes one argument.
+No tests available.
+
+",
+        )
+        .with_status(101)
+        .run();
+}
+
+#[test]
+fn build_list_targets() {
+    test_list_targets_full("build");
+}
+#[test]
+fn build_list_targets_empty() {
+    test_empty_list_targets_full("build");
+}
+
+#[test]
+fn check_list_targets() {
+    test_list_targets_full("check");
+}
+#[test]
+fn check_list_targets_empty() {
+    test_empty_list_targets_full("check");
+}
+
+#[test]
+fn fix_list_targets() {
+    test_list_targets_full("fix");
+}
+#[test]
+fn fix_list_targets_empty() {
+    test_empty_list_targets_full("fix");
+}
+
+#[test]
+fn run_list_targets() {
+    test_list_targets_example_and_bin_only("run");
+}
+#[test]
+fn run_list_targets_empty() {
+    test_empty_list_targets_example_and_bin_only("run");
+}
+
+#[test]
+fn test_list_targets() {
+    test_list_targets_full("test");
+}
+#[test]
+fn test_list_targets_empty() {
+    test_empty_list_targets_full("test");
+}
+
+#[test]
+fn bench_list_targets() {
+    test_list_targets_full("bench");
+}
+#[test]
+fn bench_list_targets_empty() {
+    test_empty_list_targets_full("bench");
+}
+
+#[test]
+fn install_list_targets() {
+    test_list_targets_example_and_bin_only("install");
+}
+#[test]
+fn install_list_targets_empty() {
+    test_empty_list_targets_example_and_bin_only("install");
+}

tests/testsuite/main.rs

@@ -43,6 +43,7 @@ mod git;
 mod init;
 mod install;
 mod jobserver;
+mod list_targets;
 mod local_registry;
 mod lockfile_compat;
 mod login;