Added and documented completion subcommand

README.md

@@ -171,10 +171,11 @@ CLI app for Topiary, the universal code formatter.
 Usage: topiary [OPTIONS] <COMMAND>
 
 Commands:
-  format     Format inputs
-  visualise  Visualise the input's Tree-sitter parse tree
-  config     Print the current configuration
-  help       Print this message or the help of the given subcommand(s)
+  format      Format inputs
+  visualise   Visualise the input's Tree-sitter parse tree
+  config      Print the current configuration
+  completion  Generate shell completion script
+  help        Print this message or the help of the given subcommand(s)
 
 Options:
   -C, --configuration <CONFIGURATION>
@@ -383,6 +384,59 @@ understand the different sources of configuration and collation modes.
 
 Note: `cfg` is a recognised alias of the `config` subcommand.
 
+#### Shell Completion
+
+Shell completion scripts for Topiary can be generated with the
+`completion` subcommand. The output of which can be sourced into your
+shell session or profile, as required.
+
+<!-- DO NOT REMOVE THE "usage" COMMENTS -->
+<!-- usage:start:completion -->
+```
+Generate shell completion script
+
+Usage: topiary completion [OPTIONS] [SHELL]
+
+Arguments:
+  [SHELL]
+          Shell (omit to detect from the environment)
+
+          [possible values: bash, elvish, fish, powershell, zsh]
+
+Options:
+  -C, --configuration <CONFIGURATION>
+          Configuration file
+
+          [env: TOPIARY_CONFIG_FILE]
+
+      --configuration-collation <CONFIGURATION_COLLATION>
+          Configuration collation mode
+
+          [env: TOPIARY_CONFIG_COLLATION]
+          [default: merge]
+
+          Possible values:
+          - merge:    When multiple sources of configuration are available, matching items are
+            updated from the higher priority source, with collections merged as the union of sets
+          - revise:   When multiple sources of configuration are available, matching items
+            (including collections) are superseded from the higher priority source
+          - override: When multiple sources of configuration are available, the highest priority
+            source is taken. All values from lower priority sources are discarded
+
+  -v, --verbose...
+          Logging verbosity (increased per occurrence)
+
+  -h, --help
+          Print help (see a summary with '-h')
+```
+<!-- usage:end:completion -->
+
+For example, in Bash:
+
+```bash
+source <(topiary completion)
+```
+
 #### Logging
 
 By default, the Topiary CLI will only output error messages. You can

topiary-cli/src/cli.rs

@@ -1,7 +1,8 @@
 //! Command line interface argument parsing.
 
-use clap::{ArgAction, ArgGroup, Args, Parser, Subcommand};
-use std::path::PathBuf;
+use clap::{ArgAction, ArgGroup, Args, CommandFactory, Parser, Subcommand};
+use clap_complete::{generate, shells::Shell};
+use std::{io::stdout, path::PathBuf};
 
 use log::LevelFilter;
 use topiary::SupportedLanguage;
@@ -151,6 +152,13 @@ pub enum Commands {
     /// Print the current configuration
     #[command(alias = "cfg", display_order = 3)]
     Config,
+
+    /// Generate shell completion script
+    #[command(display_order = 100)]
+    Completion {
+        /// Shell (omit to detect from the environment)
+        shell: Option<Shell>,
+    },
 }
 
 /// Given a vector of paths, recursively expand those that identify as directories, in place
@@ -222,8 +230,25 @@ pub fn get_args() -> CLIResult<Cli> {
             }
         }
 
+        // Attempt to detect shell from environment, when omitted
+        Commands::Completion { shell: None } => {
+            let detected_shell = Shell::from_env().ok_or(TopiaryError::Bin(
+                "Cannot detect shell from environment".into(),
+                None,
+            ))?;
+
+            args.command = Commands::Completion {
+                shell: Some(detected_shell),
+            };
+        }
+
         _ => {}
     }
 
     Ok(args)
 }
+
+/// Generate shell completion script, for the given shell, and output to stdout
+pub fn completion(shell: Shell) {
+    generate(shell, &mut Cli::command(), "topiary", &mut stdout());
+}

topiary-cli/src/main.rs

@@ -148,9 +148,14 @@ async fn run() -> CLIResult<()> {
         }
 
         Commands::Config => {
-            // Output collated configuration as TOML, with annotations about how we got there
+            // Output collated configuration gtas TOML, with annotations about how we got there
             print!("{annotations}\n{config}");
         }
+
+        Commands::Completion { shell } => {
+            // The CLI parser fails if no shell is provided/detected, so it's safe to unwrap here
+            cli::completion(shell.unwrap());
+        }
     }
 
     Ok(())

verify-documented-usage.sh

@@ -40,7 +40,7 @@ diff-usage() {
 }
 
 main() {
-  local -a subcommands=(ROOT format visualise config)
+  local -a subcommands=(ROOT format visualise config completion)
 
   local _diff
   local _subcommand