diff --git a/CHANGELOG.md b/CHANGELOG.md index b99d801..7169ea2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,11 @@ candidates before a series ships (`27.1-rc.1`). The tag is the version with a ## [Unreleased] +### Added +- `completions ` prints a shell completion script (bash, zsh, fish, + elvish or powershell) to standard output, and `man` prints a man page in + roff. Both are generated from the command itself and reach no server. + ## [27.1-rc.12] The twelfth release candidate of the 27.1 series: upstream v1.0.15, keywords diff --git a/Cargo.lock b/Cargo.lock index 8eee739..d939277 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -462,6 +462,15 @@ dependencies = [ "strsim", ] +[[package]] +name = "clap_complete" +version = "4.6.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "037e2a1a92236d0aff7e845093f64661d6df4c02c9fcc61a60e9e1d736fa392f" +dependencies = [ + "clap", +] + [[package]] name = "clap_derive" version = "4.6.7" @@ -480,6 +489,16 @@ version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1c133bc6a41be0d194c306b5506d15e6feeea7b1d6604bd3f8310dfb2ca96486" +[[package]] +name = "clap_mangen" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "211d617eaa4b735c96c9e0228fcbdb5120ef623f2b8cb67ffb84c3e02dbc28a4" +dependencies = [ + "clap", + "roff", +] + [[package]] name = "cmake" version = "0.1.58" @@ -1333,6 +1352,8 @@ dependencies = [ "chrono", "chrono-tz", "clap", + "clap_complete", + "clap_mangen", "crossbeam-channel", "encodify", "flate2", @@ -2119,6 +2140,12 @@ dependencies = [ "windows-sys 0.52.0", ] +[[package]] +name = "roff" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "323c417e1d9665a65b263ec744ba09030cfb277e9daa0b018a4ab62e57bc8189" + [[package]] name = "rsqlite-vfs" version = "0.1.1" diff --git a/Cargo.toml b/Cargo.toml index b314870..6d49c4c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -28,6 +28,8 @@ url= "2.5.8" thiserror = "2.0.18" ureq = { version = "3.5.0", default-features = false, features = ["json", "gzip", "rustls-no-provider", "platform-verifier"] } clap = { version = "4.6.1", features = ["derive"] } +clap_complete = "4.6.11" +clap_mangen = "0.3.3" crossbeam-channel = "0.5.15" num_cpus = "1.17.0" encodify = "1.0" diff --git a/README.md b/README.md index 4ee1e3b..b2d9741 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,20 @@ so you can confirm it came from us before trusting the checksums. The same public key signs every inbuxa release (installer, migrate and cli). +## Shell completions and a man page + +`inbuxa-migrate completions ` prints a completion script to standard +output, for `bash`, `zsh`, `fish`, `elvish` or `powershell`. Install it where +the shell looks: + + inbuxa-migrate completions bash > /etc/bash_completion.d/inbuxa-migrate + inbuxa-migrate completions zsh > "${fpath[1]}/_inbuxa-migrate" + inbuxa-migrate completions fish > ~/.config/fish/completions/inbuxa-migrate.fish + +`inbuxa-migrate man` prints a man page, in roff, to standard output: + + inbuxa-migrate man > /usr/share/man/man1/inbuxa-migrate.1 + ## Building and testing cargo build --release the binary is target/release/inbuxa-migrate diff --git a/src/cli.rs b/src/cli.rs index bf57650..c4236b1 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -107,6 +107,21 @@ enum Command { Plan(Box), #[command(about = "Show the contents of a local archive (read-only)")] Inspect(Box), + /// Print a shell completion script to standard output + /// + /// Source it, or install it where the shell looks: + /// bash: inbuxa-migrate completions bash > /etc/bash_completion.d/inbuxa-migrate + /// zsh: inbuxa-migrate completions zsh > "${fpath[1]}/_inbuxa-migrate" + /// fish: inbuxa-migrate completions fish > ~/.config/fish/completions/inbuxa-migrate.fish + Completions { + /// The shell to generate for + #[arg(value_enum)] + shell: clap_complete::Shell, + }, + /// Print a man page, in roff, to standard output + /// + /// inbuxa-migrate man > /usr/share/man/man1/inbuxa-migrate.1 + Man, } #[derive(Subcommand)] @@ -921,6 +936,8 @@ pub enum Action { ExportManageSieve(CommonConfig, ExportManageSieveConfig), ExportDav(CommonConfig, ExportDavConfig), Inspect(InspectConfig), + Completions(clap_complete::Shell), + Man, } impl Action { @@ -1117,6 +1134,8 @@ impl Cli { Command::ExportCaldav(args) => resolve_export_dav(*args, DavKindArg::Caldav), Command::ExportCarddav(args) => resolve_export_dav(*args, DavKindArg::Carddav), Command::Inspect(args) => resolve_inspect(*args), + Command::Completions { shell } => Ok(Action::Completions(shell)), + Command::Man => Ok(Action::Man), } } } @@ -2234,6 +2253,36 @@ mod tests { use super::*; use std::env; + #[test] + fn completions_resolve_to_the_named_shell() { + let cli = Cli::try_parse_from(["inbuxa-migrate", "completions", "bash"]) + .unwrap_or_else(|e| panic!("clap rejected args: {e}")); + assert!(matches!( + cli.resolve().unwrap(), + Action::Completions(clap_complete::Shell::Bash) + )); + let cli = Cli::try_parse_from(["inbuxa-migrate", "completions", "zsh"]) + .unwrap_or_else(|e| panic!("clap rejected args: {e}")); + assert!(matches!( + cli.resolve().unwrap(), + Action::Completions(clap_complete::Shell::Zsh) + )); + } + + #[test] + fn completions_reject_an_unknown_shell() { + assert!(Cli::try_parse_from(["inbuxa-migrate", "completions", "powershellx"]).is_err()); + // The shell is required. + assert!(Cli::try_parse_from(["inbuxa-migrate", "completions"]).is_err()); + } + + #[test] + fn man_resolves() { + let cli = Cli::try_parse_from(["inbuxa-migrate", "man"]) + .unwrap_or_else(|e| panic!("clap rejected args: {e}")); + assert!(matches!(cli.resolve().unwrap(), Action::Man)); + } + #[test] fn parse_duration_reads_units_and_rejects_nonsense() { use std::time::Duration; diff --git a/src/main.rs b/src/main.rs index 5b94cbc..38ca12a 100644 --- a/src/main.rs +++ b/src/main.rs @@ -5,7 +5,7 @@ * SPDX-License-Identifier: Apache-2.0 OR MIT */ -use clap::Parser; +use clap::{CommandFactory, Parser}; use inbuxa_migrate::cli::{Action, Cli}; use inbuxa_migrate::error::Error; @@ -31,6 +31,24 @@ fn run() -> i32 { Err(err) => return fail(&err), }; + // Completions and the man page are generated from the command itself and + // touch no network, archive or logger, so they come before everything else. + match &action { + Action::Completions(shell) => { + let mut cmd = Cli::command(); + let name = cmd.get_name().to_string(); + clap_complete::generate(*shell, &mut cmd, name, &mut std::io::stdout()); + return 0; + } + Action::Man => { + return match clap_mangen::Man::new(Cli::command()).render(&mut std::io::stdout()) { + Ok(()) => 0, + Err(err) => fail(&Error::from(err)), + }; + } + _ => {} + } + let do_estimate = action.estimate_available(); if action.estimate_requested() && !do_estimate { eprintln!( @@ -184,6 +202,8 @@ fn run() -> i32 { Err(err) => fail(&err), }; } + // Handled before the match, above. + Action::Completions(_) | Action::Man => unreachable!(), }; if do_estimate {