Struct Command

pub struct Command { /* private fields */ }

A command-line command.

Implementations

impl Command

pub fn new<S: Into<String>>(name: S) -> Self

Constructs a new Command.

Panics

Panics if the command name is blank or empty.

Example

use clapi::Command;

let command = Command::new("My App");
assert_eq!(command.get_name(), "My App");

pub fn root() -> Self

Constructs a new Command named after the running executable.

pub fn with_options<S: Into<String>>(name: S, options: OptionList) -> Self

Constructs a new Command with the specified Options.

Panics

Panics if the command name is empty or contains whitespaces.

Example

use clapi::{OptionList, CommandOption, Command};

let mut options = OptionList::new();
options.add(CommandOption::new("enable")).unwrap();

let command = Command::with_options("My App", options);
assert!(command.get_options().contains("enable"));

pub fn get_name(&self) -> &str

Returns the name of the command.

pub fn get_description(&self) -> Option<&str>

Returns a short description of the command, or None if is not set.

pub fn get_usage(&self) -> Option<&str>

Returns information about the usage of this command.

pub fn get_help(&self) -> Option<&str>

Returns the help information of the command.

pub fn get_version(&self) -> Option<&str>

Returns the version of this command.

pub fn get_subcommands(&self) -> Iter<'_>

Returns an iterator over the subcommands of this command.

pub fn get_subcommands_mut(&mut self) -> IterMut<'_>

Returns an ExactSizeIterator over the children of this command.

pub fn get_options(&self) -> &OptionList

Returns the Options of this command.

pub fn get_arg(&self) -> Option<&Argument>

Returns the Argument this option takes or None if have more than 1 argument.

pub fn get_args(&self) -> &ArgumentList

Returns the Arguments of this command.

pub fn take_args(&self) -> bool

Returns true if this command take args.

pub fn is_hidden(&self) -> bool

Returns true if this command is no visible for help.

pub fn get_handler( &self, ) -> Option<RefMut<'_, dyn FnMut(&OptionList, &ArgumentList) -> Result<()> + 'static>>

Returns the handler of this command, or None if not set.

pub fn find_subcommand<S: AsRef<str>>(&self, name: S) -> Option<&Command>

Returns the child with the given name, or None if not child if found.

pub fn description<S: Into<String>>(self, description: S) -> Self

Sets a short description of this command.

Example

use clapi::Command;

let command = Command::root().description("My application");
assert_eq!(command.get_description(), Some("My application"));

pub fn usage<S: Into<String>>(self, usage: S) -> Self

Sets information about the usage of this command.

Example

use clapi::Command;
let command = Command::new("app")
    .usage("app [VALUES]\napp [OPTIONS] [VALUES]");

assert_eq!(command.get_usage(), Some("app [VALUES]\napp [OPTIONS] [VALUES]"));

pub fn help<S: Into<String>>(self, help: S) -> Self

Sets help information about this command.

Example

use clapi::Command;
let command = Command::new("MyApp")
    .version("1.0")
    .help(
"MyApp - An app for sum numbers

USAGE:
    MyApp [left] [right]

OPTIONS:
    - times [TIMES]     Number of times to multiply the numbers
    - version           Shows the version of the app
");

assert!(command.get_help().is_some());

pub fn version<S: Into<String>>(self, version: S) -> Self

Sets the version of this command.

Example

use clapi::Command;

let command = Command::new("MyApp").version("1.0.2");
assert_eq!(command.get_version(), Some("1.0.2"));

pub fn option(self, option: CommandOption) -> Self

Adds an CommandOption to this command.

Panics:

Panics it the command contains an CommandOption with the same name or alias.

Example

use clapi::{Command, CommandOption, Argument};
use clapi::validator::validate_type;

let command = Command::new("MyApp")
    .option(CommandOption::new("enable"))
    .option(CommandOption::new("times")
        .arg(Argument::new()
            .validator(validate_type::<i64>())));

assert!(command.get_options().contains("enable"));
assert!(command.get_options().contains("times"));

pub fn options(self, options: OptionList) -> Self

Replaces the options of this command with the specified.

Example

use clapi::{OptionList, CommandOption, Argument, Command};
use clapi::validator::validate_type;

let mut options = OptionList::new();
options.add(CommandOption::new("enable")).unwrap();
options.add(CommandOption::new("times")
    .arg(Argument::new()
        .validator(validate_type::<i64>()))).unwrap();

let command = Command::new("MyApp").options(options);
assert!(command.get_options().contains("enable"));
assert!(command.get_options().contains("times"));

pub fn arg(self, arg: Argument) -> Self

Adds a new Argument to this command.

Panics:

Panic if the command contains an Argument with the same name.

Example

use clapi::{Command, Argument};

let command = Command::new("MyApp").arg(Argument::with_name("values"));
assert_eq!(command.get_arg().unwrap().get_name(), "values");

pub fn args(self, args: ArgumentList) -> Self

Sets the Arguments of this command.

Example

use clapi::{ArgumentList, Argument, Command};

let mut args = ArgumentList::new();
args.add(Argument::with_name("values")).unwrap();

let command = Command::new("MyApp").args(args);
assert_eq!(command.get_arg().unwrap().get_name(), "values");

pub fn hidden(self, is_hidden: bool) -> Self

Specify if this command is hidden for the help, this property may be ignore if is the root command.

What will be hidden or not about the command is up to the implementor of the Help trait.

Example

use clapi::Command;

let command = Command::new("MyApp").hidden(true);
assert!(command.is_hidden());

pub fn handler<F>(self, f: F) -> Self

where F: FnMut(&OptionList, &ArgumentList) -> Result<()> + 'static,

Sets the handler of this command.

Example

use clapi::{Command, CommandLine};

let command = Command::new("test")
    .handler(|_options, _args| {
        println!("This is a test");
        Ok(())
});

let mut cli = CommandLine::new(command);
cli.run();

pub fn subcommand(self, command: Command) -> Self

Adds a new child Command.

Example

use clapi::Command;

let command = Command::new("MyApp")
    .subcommand(Command::new("test"));

assert!(command.find_subcommand("test").is_some());

pub fn parse_args(self) -> Result<ParseResult>

Parse the arguments from std::env::args using this command and returns the ParseResult.

Example:

use clapi::{Command, CommandOption, Argument};
use clapi::validator::validate_type;

let result = Command::root()
    .option(CommandOption::new("negate")
        .arg(Argument::new().validator(validate_type::<bool>())))
    .arg(Argument::one_or_more("values").validator(validate_type::<i64>()))
    .parse_args()
    .unwrap();

pub fn parse_from<I, S>(self, args: I) -> Result<ParseResult>

where I: IntoIterator<Item = S>, S: Borrow<str>,

Parse the arguments using this command and returns the ParseResult.

Example:

use clapi::{Command, CommandOption, Argument};
use clapi::validator::validate_type;

let result = Command::root()
    .option(CommandOption::new("negate")
        .arg(Argument::new().validator(validate_type::<bool>())))
    .arg(Argument::one_or_more("values").validator(validate_type::<i64>()))
    .parse_from(vec!["--negate=true", "1", "2", "3"])
    .unwrap();

assert!(result.options().contains("negate"));
assert_eq!(result.arg().unwrap().convert_all::<i64>().ok(), Some(vec![1, 2, 3]));

Trait Implementations

impl Clone for Command

fn clone(&self) -> Command

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Command

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Command

fn deserialize<D>( deserializer: D, ) -> Result<Self, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Hash for Command

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> IntoIterator for &'a Command

type Item = &'a Command

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Command

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Command

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Command