Generate Shell completions (#388)

* feat: ✨ Add shell completions for espflash

* docs: 📝 Update usage

* feat: ✨ Use crate_name! macro from clap instead of hardcoded name

* feat: ✨ Remove log level

* build: ⚡️ Remove cargo feature from clap

* feat: ✨ Add shell completions

* docs: 📝 Add docstring for completions

* docs: 📝 Document cargo-espflash completions

* feat: ⚡️ Avoid duplicating code

Author: SergioGasquez

Cargo.lock

@@ -54,6 +54,7 @@ Usage: cargo espflash <COMMAND>
 
 Commands:
   board-info       Display information about the connected board and exit without flashing
+  completions      Generate completions for the given shell. Resulting completions have to be appended to cargo's completions
   flash            Flash an application to a target device
   monitor          Open the serial monitor without flashing
   partition-table  Operations for partitions tables

cargo-espflash/README.md

@@ -5,13 +5,13 @@ use std::{
 };
 
 use cargo_metadata::Message;
-use clap::{Args, Parser, Subcommand};
+use clap::{Args, CommandFactory, Parser, Subcommand};
 use espflash::{
     cli::{
-        self, board_info, config::Config, connect, erase_partitions, flash_elf_image,
+        self, board_info, completions, config::Config, connect, erase_partitions, flash_elf_image,
         monitor::monitor, parse_partition_table, partition_table, print_board_info,
-        save_elf_as_image, serial_monitor, ConnectArgs, EspflashProgress, FlashConfigArgs,
-        MonitorArgs, PartitionTableArgs,
+        save_elf_as_image, serial_monitor, CompletionsArgs, ConnectArgs, EspflashProgress,
+        FlashConfigArgs, MonitorArgs, PartitionTableArgs,
     },
     image_format::ImageFormatKind,
     logging::initialize_logger,
@@ -32,7 +32,7 @@ mod error;
 mod package_metadata;
 
 #[derive(Debug, Parser)]
-#[clap(version, bin_name = "cargo", propagate_version = true)]
+#[clap(version, propagate_version = true)]
 struct Cli {
     #[clap(subcommand)]
     subcommand: CargoSubcommand,
@@ -50,6 +50,7 @@ enum CargoSubcommand {
 #[derive(Debug, Subcommand)]
 enum Commands {
     BoardInfo(ConnectArgs),
+    Completions(CompletionsArgs),
     Flash(FlashArgs),
     Monitor(MonitorArgs),
     PartitionTable(PartitionTableArgs),
@@ -137,6 +138,7 @@ fn main() -> Result<()> {
     // associated arguments.
     match args {
         Commands::BoardInfo(args) => board_info(&args, &config),
+        Commands::Completions(args) => completions(&args, &mut Cli::command(), "cargo"),
         Commands::Flash(args) => flash(args, &config),
         Commands::Monitor(args) => serial_monitor(args, &config),
         Commands::PartitionTable(args) => partition_table(args),

cargo-espflash/src/main.rs

@@ -29,6 +29,7 @@ base64 = "0.21.0"
 binread = "2.2.0"
 bytemuck = { version = "1.12.3", features = ["derive"] }
 clap = { version = "4.0.32", features = ["derive", "env"], optional = true }
+clap_complete = { version = "4.1.5", optional = true }
 comfy-table = { version = "6.1.4", optional = true }
 crossterm = { version = "0.26.1", optional = true }
 ctrlc = { version = "3.2.5", optional = true }
@@ -60,6 +61,7 @@ default = ["cli"]
 cli = [
     "dep:addr2line",
     "dep:clap",
+    "dep:clap_complete",
     "dep:comfy-table",
     "dep:crossterm",
     "dep:ctrlc",

espflash/Cargo.toml

@@ -54,7 +54,8 @@ A command-line tool for flashing Espressif devices over serial
 Usage: espflash <COMMAND>
 
 Commands:
-  board-info       Display information about the connected board and exit without flashing
+  board-info       Establish a connection with a target device
+  completions      Generate completions for the given shell
   flash            Flash an application to a target device
   monitor          Open the serial monitor without flashing
   partition-table  Operations for partitions tables
@@ -63,8 +64,8 @@ Commands:
   help             Print this message or the help of the given subcommand(s)
 
 Options:
-  -h, --help     Print help information
-  -V, --version  Print version information
+  -h, --help     Print help
+  -V, --version  Print version
 ```
 
 ### Cargo Runner

espflash/README.md

@@ -5,13 +5,13 @@ use std::{
     path::PathBuf,
 };
 
-use clap::{Args, Parser, Subcommand};
+use clap::{Args, CommandFactory, Parser, Subcommand};
 use espflash::{
     cli::{
-        self, board_info, config::Config, connect, erase_partitions, flash_elf_image,
+        self, board_info, completions, config::Config, connect, erase_partitions, flash_elf_image,
         monitor::monitor, parse_partition_table, partition_table, print_board_info,
-        save_elf_as_image, serial_monitor, ConnectArgs, EspflashProgress, FlashConfigArgs,
-        MonitorArgs, PartitionTableArgs,
+        save_elf_as_image, serial_monitor, CompletionsArgs, ConnectArgs, EspflashProgress,
+        FlashConfigArgs, MonitorArgs, PartitionTableArgs,
     },
     image_format::ImageFormatKind,
     logging::initialize_logger,
@@ -22,15 +22,16 @@ use log::{debug, LevelFilter};
 use miette::{IntoDiagnostic, Result, WrapErr};
 
 #[derive(Debug, Parser)]
-#[clap(about, version, propagate_version = true)]
-struct Cli {
-    #[clap(subcommand)]
+#[command(about, version, propagate_version = true)]
+pub struct Cli {
+    #[command(subcommand)]
     subcommand: Commands,
 }
 
 #[derive(Debug, Subcommand)]
 enum Commands {
     BoardInfo(ConnectArgs),
+    Completions(CompletionsArgs),
     Flash(FlashArgs),
     Monitor(MonitorArgs),
     PartitionTable(PartitionTableArgs),
@@ -107,6 +108,7 @@ fn main() -> Result<()> {
     // associated arguments.
     match args {
         Commands::BoardInfo(args) => board_info(&args, &config),
+        Commands::Completions(args) => completions(&args, &mut Cli::command(), "espflash"),
         Commands::Flash(args) => flash(args, &config),
         Commands::Monitor(args) => serial_monitor(args, &config),
         Commands::PartitionTable(args) => partition_table(args),

espflash/src/bin/espflash.rs

@@ -15,6 +15,7 @@ use std::{
 };
 
 use clap::Args;
+use clap_complete::Shell;
 use comfy_table::{modifiers, presets::UTF8_FULL, Attribute, Cell, Color, Table};
 use esp_idf_part::{DataType, Partition, PartitionTable};
 use indicatif::{style::ProgressStyle, HumanCount, ProgressBar};
@@ -59,6 +60,13 @@ pub struct ConnectArgs {
     pub no_stub: bool,
 }
 
+/// Generate completions for the given shell
+#[derive(Debug, Args)]
+pub struct CompletionsArgs {
+    /// Shell to generate completions for.
+    pub shell: Shell,
+}
+
 /// Configure communication with the target device's flash
 #[derive(Debug, Args)]
 pub struct FlashConfigArgs {
@@ -217,6 +225,13 @@ pub fn board_info(args: &ConnectArgs, config: &Config) -> Result<()> {
     Ok(())
 }
 
+/// Generate shell completions for the given shell
+pub fn completions(args: &CompletionsArgs, app: &mut clap::Command, bin_name: &str) -> Result<()> {
+    clap_complete::generate(args.shell, app, bin_name, &mut std::io::stdout());
+
+    Ok(())
+}
+
 /// Print information about a chip
 pub fn print_board_info(flasher: &mut Flasher) -> Result<()> {
     let info = flasher.device_info()?;