Add support for generating a bash completion script

This change adds support for generating shell completion scripts for the
program. If sourced, the shell will provide tab completions for the
program's arguments.
There are two possible approaches provided by clap for going about
generating shell completion functionality: either at build time by
separately generating the clap parsers out-of-band or at run time, as an
option to the main program itself. We are generally not too much in
favor of a run time approach, as it means less inspectability at
installation time and more overhead in the form of code crammed into the
main binary.
Hence, with this change we take the "build time" approach. Clap
recommends hooking the generation up in build.rs, but this seems like an
inflexible choice. For one, that is because it would mean
unconditionally generating this file or some user unfriendly environment
variable based approach to making the process conditional, but also
because specifying the command for which to generate the script should
likely be configurable. That is a limitation of the completion script
that clap generates (see clap-rs/clap#1764).
Instead, we provide a utility program that emits the completion script
to standard output, accepting regular command line options itself.

Cargo.toml

@@ -7,9 +7,15 @@ license = "GPL-3.0-or-later"
 description = """
 A program for backup & restoration of btrfs subvolumes.
 """
+default-run = "btrfs-backup"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
+[[bin]]
+name = "shell-complete"
+path = "var/shell-complete.rs"
+required-features = ["clap_complete"]
+
 [profile.release]
 opt-level = "z"
 lto = true
@@ -24,6 +30,7 @@ grev = "0.1.3"
 [dependencies]
 anyhow = "1.0.68"
 clap = {version = "4.1.4", features = ["derive"]}
+clap_complete = {version = "4.1.1", optional = true}
 once_cell = "1.17.0"
 regex = {version = "1.7.1", default-features = false, features = ["std"]}
 time = {version = "0.3.18", features = ["local-offset", "macros", "parsing"]}

var/shell-complete.rs

@@ -0,0 +1,36 @@
+// Copyright (C) 2023 Daniel Mueller <[email protected]>
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+#![allow(clippy::large_enum_variant, clippy::let_and_return)]
+
+use std::io::stdout;
+
+use clap::CommandFactory as _;
+use clap::Parser;
+
+use clap_complete::generate;
+use clap_complete::Shell;
+
+
+#[allow(unused)]
+mod prog {
+  include!("../src/args.rs");
+}
+
+
+/// Generate a shell completion script for the program.
+#[derive(Debug, Parser)]
+struct Args {
+  /// The shell for which to generate a completion script for.
+  shell: Shell,
+  /// The command for which to generate the shell completion script.
+  #[clap(default_value = env!("CARGO_PKG_NAME"))]
+  command: String,
+}
+
+
+fn main() {
+  let args = Args::parse();
+  let mut app = prog::Args::command();
+  generate(args.shell, &mut app, &args.command, &mut stdout());
+}