From 95a1ff6d96aaed92536964596c802ac642a34313 Mon Sep 17 00:00:00 2001 From: Daniel Mueller Date: Wed, 1 Apr 2020 22:59:22 -0700 Subject: [PATCH] Add support for generating a bash completion script This change adds support for generating a bash completion script. 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 using some user-unfriendly environment variable based approach for making the process conditional. But there is also the fact that 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 https://github.com/clap-rs/clap/issues/1764). In our version we provide a utility program that emits the completion script to standard output, accepting regular command line options itself. In doing so we allow for installation time generation of the completion script or installation of the utility itself, the output of which could be sourced on demand -- depending on the user's preference. --- CHANGELOG.md | 1 + Cargo.toml | 4 +++ README.md | 14 ++++++++++ var/shell-complete.rs | 59 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 78 insertions(+) create mode 100644 var/shell-complete.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index d3750746..00bbdfdf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ Unreleased - Replaced `argparse` with `structopt` - Removed `argparse` dependency - Made the `--verbose` and `--model` options global +- Added bash completion support via `shell-complete` utility program - Removed vendored dependencies and moved source code into repository root - Bumped `nitrokey` dependency to `0.6.0` diff --git a/Cargo.toml b/Cargo.toml index 4ad53eb7..7a181e70 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -36,6 +36,10 @@ exclude = ["ci/*", "rustfmt.toml"] [badges] gitlab = { repository = "d-e-s-o/nitrocli", branch = "master" } +[[bin]] +name = "shell-complete" +path = "var/shell-complete.rs" + [profile.release] opt-level = "z" lto = true diff --git a/README.md b/README.md index 66729142..c76ca7ab 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,20 @@ It is recommended that the resulting executable be installed in a directory accessible via the `PATH` environment variable. +#### Bash Completion +**nitrocli** comes with Bash completion support for options and +arguments to them. A completion script can be generated via the +`shell-complete` utility program and then only needs to be sourced to +make the current shell provide context-sensitive tab completion support. +```bash +$ cargo run --bin=shell-complete > nitrocli.bash +$ source nitrocli.bash +``` + +The generated completion script can be installed system-wide as usual +and sourced through Bash initialization files, such as `~/.bashrc`. + + Known Problems -------------- diff --git a/var/shell-complete.rs b/var/shell-complete.rs new file mode 100644 index 00000000..0a525d85 --- /dev/null +++ b/var/shell-complete.rs @@ -0,0 +1,59 @@ +// shell-complete.rs + +// ************************************************************************* +// * Copyright (C) 2020 Daniel Mueller (deso@posteo.net) * +// * * +// * This program is free software: you can redistribute it and/or modify * +// * it under the terms of the GNU General Public License as published by * +// * the Free Software Foundation, either version 3 of the License, or * +// * (at your option) any later version. * +// * * +// * This program is distributed in the hope that it will be useful, * +// * but WITHOUT ANY WARRANTY; without even the implied warranty of * +// * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * +// * GNU General Public License for more details. * +// * * +// * You should have received a copy of the GNU General Public License * +// * along with this program. If not, see . * +// ************************************************************************* + +use std::io; + +use structopt::clap; +use structopt::StructOpt as _; + +#[allow(unused)] +mod nitrocli { + include!("../src/arg_util.rs"); + + // We only need a stripped down version of the `Command` macro. + macro_rules! Command { + ( $name:ident, [ $( $(#[$doc:meta])* $var:ident$(($inner:ty))? => $exec:expr, ) *] ) => { + #[derive(Debug, PartialEq, structopt::StructOpt)] + pub enum $name { + $( + $(#[$doc])* + $var$(($inner))?, + )* + } + }; + } + + include!("../src/arg_defs.rs"); +} + +/// Generate a bash completion script for nitrocli. +/// +/// The script will be emitted to standard output. +#[derive(Debug, structopt::StructOpt)] +pub struct Args { + /// The command for which to generate the bash completion script. + #[structopt(default_value = "nitrocli")] + pub command: String, +} + +fn main() { + let args = Args::from_args(); + let mut app = nitrocli::Args::clap(); + app.gen_completions_to(&args.command, clap::Shell::Bash, &mut io::stdout()); +}