Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-13 14:22:34 +00:00
Code Issues Projects Releases Packages Wiki Activity

fix(complete): Better organize the API

Browse source
This commit is contained in:
Ed Page 2021-12-31 13:20:55 -06:00
parent 8d73a0e80f
commit 19b59a2df8
18 changed files with 287 additions and 294 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
clap_complete/examples/bash_completion.rs
View file

@ -1,5 +1,5 @@
use clap::App;
use clap_complete::{generate, generators::Bash};
use clap_complete::{generate, shells::Bash};
use std::io;
fn main() {

234
clap_complete/src/generator/mod.rs Normal file
View file

@ -0,0 +1,234 @@
//! Shell completion machinery
pub mod utils;
use std::ffi::OsString;
use std::fs::File;
use std::io::Error;
use std::io::Write;
use std::path::PathBuf;
use clap::App;
/// Generator trait which can be used to write generators
pub trait Generator {
/// Returns the file name that is created when this generator is called during compile time.
///
/// # Examples
///
/// ```
/// # use std::io::Write;
/// # use clap::App;
/// use clap_complete::Generator;
///
/// pub struct Fish;
///
/// impl Generator for Fish {
/// # fn generate(&self, app: &App, buf: &mut dyn Write) {}
/// fn file_name(&self, name: &str) -> String {
/// format!("{}.fish", name)
/// }
/// }
/// ```
fn file_name(&self, name: &str) -> String;
/// Generates output out of [`clap::App`](App).
///
/// # Examples
///
/// The following example generator displays the [`clap::App`](App)
/// as if it is printed using [`std::println`].
///
/// ```
/// use std::{io::Write, fmt::write};
/// use clap::App;
/// use clap_complete::Generator;
///
/// pub struct ClapDebug;
///
/// impl Generator for ClapDebug {
/// fn generate(&self, app: &App, buf: &mut dyn Write) {
/// write!(buf, "{}", app).unwrap();
/// }
/// # fn file_name(&self, name: &str) -> String {
/// # name.into()
/// # }
/// }
/// ```
fn generate(&self, app: &App, buf: &mut dyn Write);
}
/// Generate a completions file for a specified shell at compile-time.
///
/// **NOTE:** to generate the file at compile time you must use a `build.rs` "Build Script" or a
/// [`cargo-xtask`](https://github.com/matklad/cargo-xtask)
///
/// # Examples
///
/// The following example generates a bash completion script via a `build.rs` script. In this
/// simple example, we'll demo a very small application with only a single subcommand and two
/// args. Real applications could be many multiple levels deep in subcommands, and have tens or
/// potentially hundreds of arguments.
///
/// First, it helps if we separate out our `App` definition into a separate file. Whether you
/// do this as a function, or bare App definition is a matter of personal preference.
///
/// ```
/// // src/cli.rs
///
/// use clap::{App, Arg};
///
/// pub fn build_cli() -> App<'static> {
/// App::new("compl")
/// .about("Tests completions")
/// .arg(Arg::new("file")
/// .help("some input file"))
/// .subcommand(App::new("test")
/// .about("tests things")
/// .arg(Arg::new("case")
/// .long("case")
/// .takes_value(true)
/// .help("the case to test")))
/// }
/// ```
///
/// In our regular code, we can simply call this `build_cli()` function, then call
/// `get_matches()`, or any of the other normal methods directly after. For example:
///
/// ```ignore
/// // src/main.rs
///
/// mod cli;
///
/// fn main() {
/// let _m = cli::build_cli().get_matches();
///
/// // normal logic continues...
/// }
/// ```
///
/// Next, we set up our `Cargo.toml` to use a `build.rs` build script.
///
/// ```toml
/// # Cargo.toml
/// build = "build.rs"
///
/// [dependencies]
/// clap = "*"
///
/// [build-dependencies]
/// clap = "*"
/// clap_complete = "*"
/// ```
///
/// Next, we place a `build.rs` in our project root.
///
/// ```ignore
/// use clap_complete::{generate_to, generators::Bash};
/// use std::env;
/// use std::io::Error;
///
/// include!("src/cli.rs");
///
/// fn main() -> Result<(), Error> {
/// let outdir = match env::var_os("OUT_DIR") {
/// None => return Ok(()),
/// Some(outdir) => outdir,
/// };
///
/// let mut app = build_cli();
/// let path = generate_to(
/// Bash,
/// &mut app, // We need to specify what generator to use
/// "myapp", // We need to specify the bin name manually
/// outdir, // We need to specify where to write to
/// )?;
///
/// println!("cargo:warning=completion file is generated: {:?}", path);
///
/// Ok(())
/// }
/// ```
///
/// Now, once we compile there will be a `{bin_name}.bash` file in the directory.
/// Assuming we compiled with debug mode, it would be somewhere similar to
/// `<project>/target/debug/build/myapp-<hash>/out/myapp.bash`.
///
/// **NOTE:** Please look at the individual [shells][crate::shells]
/// to see the name of the files generated.
pub fn generate_to<G, S, T>(
gen: G,
app: &mut clap::App,
bin_name: S,
out_dir: T,
) -> Result<PathBuf, Error>
where
G: Generator,
S: Into<String>,
T: Into<OsString>,
{
app.set_bin_name(bin_name);
let out_dir = PathBuf::from(out_dir.into());
let file_name = gen.file_name(app.get_bin_name().unwrap());
let path = out_dir.join(file_name);
let mut file = File::create(&path)?;
_generate::<G, S>(gen, app, &mut file);
Ok(path)
}
/// Generate a completions file for a specified shell at runtime.
///
/// Until `cargo install` can install extra files like a completion script, this may be
/// used e.g. in a command that outputs the contents of the completion script, to be
/// redirected into a file by the user.
///
/// # Examples
///
/// Assuming a separate `cli.rs` like the [example above](generate_to()),
/// we can let users generate a completion script using a command:
///
/// ```ignore
/// // src/main.rs
///
/// mod cli;
/// use std::io;
/// use clap_complete::{generate, generators::Bash};
///
/// fn main() {
/// let matches = cli::build_cli().get_matches();
///
/// if matches.is_present("generate-bash-completions") {
/// generate(Bash, &mut cli::build_cli(), "myapp", &mut io::stdout());
/// }
///
/// // normal logic continues...
/// }
///
/// ```
///
/// Usage:
///
/// ```shell
/// $ myapp generate-bash-completions > /usr/share/bash-completion/completions/myapp.bash
/// ```
pub fn generate<G, S>(gen: G, app: &mut clap::App, bin_name: S, buf: &mut dyn Write)
where
G: Generator,
S: Into<String>,
{
app.set_bin_name(bin_name);
_generate::<G, S>(gen, app, buf)
}
fn _generate<G, S>(gen: G, app: &mut clap::App, buf: &mut dyn Write)
where
G: Generator,
S: Into<String>,
{
app._build_all();
gen.generate(app, buf)
}

2
clap_complete/src/utils.rs → clap_complete/src/generator/utils.rs
View file

@ -1,3 +1,5 @@
//! Helpers for writing generators
use clap::{App, Arg, ArgSettings};
/// Gets all subcommands including child subcommands in the form of `("name", "bin_name")`.

56
clap_complete/src/generators/mod.rs
View file

@ -1,56 +0,0 @@
mod shells;
// Std
use std::io::Write;
// Internal
use clap::App;
pub use shells::*;
/// Generator trait which can be used to write generators
pub trait Generator {
/// Returns the file name that is created when this generator is called during compile time.
///
/// # Examples
///
/// ```
/// # use std::io::Write;
/// # use clap::App;
/// use clap_complete::Generator;
///
/// pub struct Fish;
///
/// impl Generator for Fish {
/// # fn generate(&self, app: &App, buf: &mut dyn Write) {}
/// fn file_name(&self, name: &str) -> String {
/// format!("{}.fish", name)
/// }
/// }
/// ```
fn file_name(&self, name: &str) -> String;
/// Generates output out of [`clap::App`](App).
///
/// # Examples
///
/// The following example generator displays the [`clap::App`](App)
/// as if it is printed using [`std::println`].
///
/// ```
/// use std::{io::Write, fmt::write};
/// use clap::App;
/// use clap_complete::Generator;
///
/// pub struct ClapDebug;
///
/// impl Generator for ClapDebug {
/// fn generate(&self, app: &App, buf: &mut dyn Write) {
/// write!(buf, "{}", app).unwrap();
/// }
/// # fn file_name(&self, name: &str) -> String {
/// # name.into()
/// # }
/// }
/// ```
fn generate(&self, app: &App, buf: &mut dyn Write);
}

197
clap_complete/src/lib.rs
View file

@ -61,195 +61,10 @@ const INTERNAL_ERROR_MSG: &str = "Fatal internal error. Please consider filing a
#[allow(missing_docs)]
mod macros;
/// Contains some popular generators
pub mod generators;
/// Contains supported shells for auto-completion scripts
mod shell;
/// Helpers for writing generators
pub mod utils;
pub mod generator;
pub mod shells;
use std::ffi::OsString;
use std::fs::File;
use std::io::Error;
use std::io::Write;
use std::path::PathBuf;
#[doc(inline)]
pub use generators::Generator;
#[doc(inline)]
pub use shell::Shell;
/// Generate a completions file for a specified shell at compile-time.
///
/// **NOTE:** to generate the file at compile time you must use a `build.rs` "Build Script" or a
/// [`cargo-xtask`](https://github.com/matklad/cargo-xtask)
///
/// # Examples
///
/// The following example generates a bash completion script via a `build.rs` script. In this
/// simple example, we'll demo a very small application with only a single subcommand and two
/// args. Real applications could be many multiple levels deep in subcommands, and have tens or
/// potentially hundreds of arguments.
///
/// First, it helps if we separate out our `App` definition into a separate file. Whether you
/// do this as a function, or bare App definition is a matter of personal preference.
///
/// ```
/// // src/cli.rs
///
/// use clap::{App, Arg};
///
/// pub fn build_cli() -> App<'static> {
/// App::new("compl")
/// .about("Tests completions")
/// .arg(Arg::new("file")
/// .help("some input file"))
/// .subcommand(App::new("test")
/// .about("tests things")
/// .arg(Arg::new("case")
/// .long("case")
/// .takes_value(true)
/// .help("the case to test")))
/// }
/// ```
///
/// In our regular code, we can simply call this `build_cli()` function, then call
/// `get_matches()`, or any of the other normal methods directly after. For example:
///
/// ```ignore
/// // src/main.rs
///
/// mod cli;
///
/// fn main() {
/// let _m = cli::build_cli().get_matches();
///
/// // normal logic continues...
/// }
/// ```
///
/// Next, we set up our `Cargo.toml` to use a `build.rs` build script.
///
/// ```toml
/// # Cargo.toml
/// build = "build.rs"
///
/// [dependencies]
/// clap = "*"
///
/// [build-dependencies]
/// clap = "*"
/// clap_complete = "*"
/// ```
///
/// Next, we place a `build.rs` in our project root.
///
/// ```ignore
/// use clap_complete::{generate_to, generators::Bash};
/// use std::env;
/// use std::io::Error;
///
/// include!("src/cli.rs");
///
/// fn main() -> Result<(), Error> {
/// let outdir = match env::var_os("OUT_DIR") {
/// None => return Ok(()),
/// Some(outdir) => outdir,
/// };
///
/// let mut app = build_cli();
/// let path = generate_to(
/// Bash,
/// &mut app, // We need to specify what generator to use
/// "myapp", // We need to specify the bin name manually
/// outdir, // We need to specify where to write to
/// )?;
///
/// println!("cargo:warning=completion file is generated: {:?}", path);
///
/// Ok(())
/// }
/// ```
///
/// Now, once we compile there will be a `{bin_name}.bash` file in the directory.
/// Assuming we compiled with debug mode, it would be somewhere similar to
/// `<project>/target/debug/build/myapp-<hash>/out/myapp.bash`.
///
/// **NOTE:** Please look at the individual [generators]
/// to see the name of the files generated.
pub fn generate_to<G, S, T>(
gen: G,
app: &mut clap::App,
bin_name: S,
out_dir: T,
) -> Result<PathBuf, Error>
where
G: Generator,
S: Into<String>,
T: Into<OsString>,
{
app.set_bin_name(bin_name);
let out_dir = PathBuf::from(out_dir.into());
let file_name = gen.file_name(app.get_bin_name().unwrap());
let path = out_dir.join(file_name);
let mut file = File::create(&path)?;
_generate::<G, S>(gen, app, &mut file);
Ok(path)
}
/// Generate a completions file for a specified shell at runtime.
///
/// Until `cargo install` can install extra files like a completion script, this may be
/// used e.g. in a command that outputs the contents of the completion script, to be
/// redirected into a file by the user.
///
/// # Examples
///
/// Assuming a separate `cli.rs` like the [example above](generate_to()),
/// we can let users generate a completion script using a command:
///
/// ```ignore
/// // src/main.rs
///
/// mod cli;
/// use std::io;
/// use clap_complete::{generate, generators::Bash};
///
/// fn main() {
/// let matches = cli::build_cli().get_matches();
///
/// if matches.is_present("generate-bash-completions") {
/// generate(Bash, &mut cli::build_cli(), "myapp", &mut io::stdout());
/// }
///
/// // normal logic continues...
/// }
///
/// ```
///
/// Usage:
///
/// ```shell
/// $ myapp generate-bash-completions > /usr/share/bash-completion/completions/myapp.bash
/// ```
pub fn generate<G, S>(gen: G, app: &mut clap::App, bin_name: S, buf: &mut dyn Write)
where
G: Generator,
S: Into<String>,
{
app.set_bin_name(bin_name);
_generate::<G, S>(gen, app, buf)
}
fn _generate<G, S>(gen: G, app: &mut clap::App, buf: &mut dyn Write)
where
G: Generator,
S: Into<String>,
{
app._build_all();
gen.generate(app, buf)
}
pub use generator::generate;
pub use generator::generate_to;
pub use generator::Generator;
pub use shells::Shell;

7
clap_complete/src/generators/shells/bash.rs → clap_complete/src/shells/bash.rs
View file

@ -1,12 +1,9 @@
// Std
use std::{fmt::Write as _, io::Write};
// Internal
use crate::utils;
use crate::Generator;
use clap::*;
use crate::generator::{utils, Generator};
/// Generate bash completion file
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub struct Bash;

8
clap_complete/src/generators/shells/elvish.rs → clap_complete/src/shells/elvish.rs
View file

@ -1,12 +1,10 @@
// Std
use std::io::Write;
// Internal
use crate::utils;
use crate::Generator;
use crate::INTERNAL_ERROR_MSG;
use clap::*;
use crate::generator::{utils, Generator};
use crate::INTERNAL_ERROR_MSG;
/// Generate elvish completion file
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub struct Elvish;

6
clap_complete/src/generators/shells/fish.rs → clap_complete/src/shells/fish.rs
View file

@ -1,11 +1,9 @@
// Std
use std::io::Write;
// Internal
use crate::utils;
use crate::Generator;
use clap::*;
use crate::generator::{utils, Generator};
/// Generate fish completion file
///
/// Note: The fish generator currently only supports named options (-o/--option), not positional arguments.

4
clap_complete/src/generators/shells/mod.rs → clap_complete/src/shells/mod.rs
View file

@ -1,11 +1,15 @@
//! Shell-specific generators
mod bash;
mod elvish;
mod fish;
mod powershell;
mod shell;
mod zsh;
pub use bash::Bash;
pub use elvish::Elvish;
pub use fish::Fish;
pub use powershell::PowerShell;
pub use shell::Shell;
pub use zsh::Zsh;

8
clap_complete/src/generators/shells/powershell.rs → clap_complete/src/shells/powershell.rs
View file

@ -1,12 +1,10 @@
// Std
use std::io::Write;
// Internal
use crate::utils;
use crate::Generator;
use crate::INTERNAL_ERROR_MSG;
use clap::*;
use crate::generator::{utils, Generator};
use crate::INTERNAL_ERROR_MSG;
/// Generate powershell completion file
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub struct PowerShell;

23
clap_complete/src/shell.rs → clap_complete/src/shells/shell.rs
View file

@ -3,7 +3,8 @@ use std::str::FromStr;
use clap::{ArgEnum, PossibleValue};
use crate::{generators, Generator};
use crate::shells;
use crate::Generator;
/// Shell with auto-generated completion script available.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
@ -78,21 +79,21 @@ impl ArgEnum for Shell {
impl Generator for Shell {
fn file_name(&self, name: &str) -> String {
match self {
Shell::Bash => generators::Bash.file_name(name),
Shell::Elvish => generators::Elvish.file_name(name),
Shell::Fish => generators::Fish.file_name(name),
Shell::PowerShell => generators::PowerShell.file_name(name),
Shell::Zsh => generators::Zsh.file_name(name),
Shell::Bash => shells::Bash.file_name(name),
Shell::Elvish => shells::Elvish.file_name(name),
Shell::Fish => shells::Fish.file_name(name),
Shell::PowerShell => shells::PowerShell.file_name(name),
Shell::Zsh => shells::Zsh.file_name(name),
}
}
fn generate(&self, app: &clap::App, buf: &mut dyn std::io::Write) {
match self {
Shell::Bash => generators::Bash.generate(app, buf),
Shell::Elvish => generators::Elvish.generate(app, buf),
Shell::Fish => generators::Fish.generate(app, buf),
Shell::PowerShell => generators::PowerShell.generate(app, buf),
Shell::Zsh => generators::Zsh.generate(app, buf),
Shell::Bash => shells::Bash.generate(app, buf),
Shell::Elvish => shells::Elvish.generate(app, buf),
Shell::Fish => shells::Fish.generate(app, buf),
Shell::PowerShell => shells::PowerShell.generate(app, buf),
Shell::Zsh => shells::Zsh.generate(app, buf),
}
}
}

8
clap_complete/src/generators/shells/zsh.rs → clap_complete/src/shells/zsh.rs
View file

@ -1,12 +1,10 @@
// Std
use std::io::Write;
// Internal
use crate::utils;
use crate::Generator;
use crate::INTERNAL_ERROR_MSG;
use clap::*;
use crate::generator::{utils, Generator};
use crate::INTERNAL_ERROR_MSG;
/// Generate zsh completion file
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub struct Zsh;

2
clap_complete/tests/completions/mod.rs
View file

@ -1,5 +1,5 @@
use clap::{App, AppSettings, Arg, ValueHint};
use clap_complete::{generate, generators::*};
use clap_complete::{generate, shells::*, Generator};
use std::fmt;
mod bash;

6
clap_complete/tests/generate_completions.rs
View file

@ -1,7 +1,9 @@
use clap::{App, Arg};
use clap_complete::{generate, generators::*};
use std::io;
use clap::{App, Arg};
use clap_complete::{generate, shells::*};
#[test]
fn generate_completions() {
let mut app = App::new("test_app")

9
clap_complete/tests/value_hints.rs
View file

@ -1,9 +1,10 @@
use clap::{App, AppSettings, Arg, ValueHint};
use clap_complete::generators::*;
use completions::common;
mod completions;
use clap::{App, AppSettings, Arg, ValueHint};
use clap_complete::shells::*;
use completions::common;
pub fn build_app_with_value_hints() -> App<'static> {
App::new("my_app")
.setting(AppSettings::TrailingVarArg)

2
clap_complete_fig/src/fig.rs
View file

@ -160,7 +160,7 @@ fn gen_options(app: &App, indent: usize) -> String {
buffer.push_str(&format!("{:indent$}}},\n", "", indent = indent + 2));
}
for flag in utils::flags(app) {
for flag in generator::utils::flags(app) {
buffer.push_str(&format!("{:indent$}{{\n", "", indent = indent + 2));
let mut flags = vec![];

2
clap_complete_fig/tests/completions/mod.rs
View file

@ -1,5 +1,5 @@
use clap::{App, AppSettings, Arg, ValueHint};
use clap_complete::{generate, generators::*};
use clap_complete::{generate, Generator};
use std::fmt;
mod fig;

5
clap_generate/src/lib.rs
View file

@ -10,12 +10,13 @@ pub use clap_complete::Shell;
#[deprecated(since = "3.0.0", note = "Renamed to `clap_complete::generators`")]
pub mod generators {
pub use clap_complete::generators::*;
pub use clap_complete::generator::*;
pub use clap_complete::shells::*;
}
#[deprecated(since = "3.0.0", note = "Renamed to `clap_complete::utils`")]
pub mod utils {
pub use clap_complete::utils::*;
pub use clap_complete::generator::utils::*;
}
#[deprecated(since = "3.0.0", note = "Renamed to `clap_complete::generate_to`")]