Crate clapi

Expand description

§Clapi

Clapi (Command-Line API) is a framework for create command line applications.

Currently clapi provides several methods for create command line applications:

Parsing the arguments
Function handlers
Macros
Macros attributes

See the examples below creating the same app using the 4 methods.

§Parsing the arguments

use clapi::{Command, CommandOption, Argument, CommandLine};
use clapi::validator::validate_type;
use std::num::NonZeroUsize;

fn main() -> clapi::Result<()> {
    let command = Command::new("echo")
        .version("1.0")
        .description("outputs the given values on the console")
        .arg(Argument::one_or_more("values"))
        .option(
            CommandOption::new("times")
                .alias("t")
                .description("number of times to repeat")
                .arg(
                    Argument::new()
                        .validator(validate_type::<NonZeroUsize>())
                        .validation_error("expected number greater than 0")
                        .default(NonZeroUsize::new(1).unwrap()),
                ),
        ).handler(|opts, args| {
        let times = opts.convert::<usize>("times").unwrap();
        let values = args.get_raw_args()
            .map(|s| s.to_string())
            .collect::<Vec<String>>()
            .join(" ") as String;

        for _ in 0..times {
            println!("{}", values);
        }

        Ok(())
    });

    CommandLine::new(command)
        .use_default_help()
        .use_default_suggestions()
        .run()
        .map_err(|e| e.exit())
}

§Function handlers

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

fn main() -> clapi::Result<()> {
    let command = Command::new("MyApp")
        .subcommand(
            Command::new("repeat")
                .arg(Argument::one_or_more("values"))
                .option(
                    CommandOption::new("times").alias("t").arg(
                        Argument::with_name("times")
                            .validator(validate_type::<u64>())
                            .default(1),
                    ),
                )
                .handler(|opts, args| {
                    let times = opts.get_arg("times").unwrap().convert::<u64>()?;
                    let values = args
                        .get("values")
                        .unwrap()
                        .convert_all::<String>()?
                        .join(" ");
                    for _ in 0..times {
                        println!("{}", values);
                    }
                    Ok(())
                }),
        );

    CommandLine::new(command)
        .use_default_suggestions()
        .use_default_help()
        .run()
}

§Macro

 use std::num::NonZeroUsize;

 fn main() -> clapi::Result<()> {
     let cli = clapi::app!{ echo =>
         (version => "1.0")
         (description => "outputs the given values on the console")
         (@option times =>
             (alias => "t")
             (description => "number of times to repeat")
             (@arg =>
                 (type => NonZeroUsize)
                 (default => NonZeroUsize::new(1).unwrap())
                 (error => "expected number greater than 0")
             )
         )
         (@arg values => (count => 1..))
         (handler (times: usize, ...args: Vec<String>) => {
             let values = args.join(" ");
             for _ in 0..times {
                 println!("{}", values);
             }
         })
     };

     cli.use_default_suggestions()
         .use_default_help()
         .run()
         .map_err(|e| e.exit())
 }

§Macro attributes

Requires macros feature enable.

use clapi::macros::*;
use std::num::NonZeroUsize;

#[command(name="echo", description="outputs the given values on the console", version="1.0")]
#[arg(values, min=1)]
#[option(times,
    alias="t",
    description="number of times to repeat",
    default=1,
    error="expected number greater than 0"
)]
fn main(times: NonZeroUsize, values: Vec<String>) {
    let values = values.join(" ");

    for _ in 0..times.get() {
        println!("{}", values);
    }
}

Modules§

help: Utilities for provide commands help information.
macros: Macro attributes for create command-line apps. Require macros feature enable.
suggestion: Utilities for provide suggestions.
token: Representation of the command-line command, option and args.
tokenizer: Converts the command-line arguments into tokens.
typing: Exposes the struct Type for arguments type checking.
utils: Utilities and extensions intended for internal use.
validator: Provides the Validator trait used for validate the values of an Argument.

Macros§

app: Constructs a CommandLine app.
crate_app: Constructs a CommandLine app using this crate Cargo.toml info.
crate_description: Returns this crate description.
crate_name: Returns this crate name.
crate_version: Returns this crate version.
run_app: Constructs and run a CommandLine app.
run_crate_app: Constructs and run a CommandLine app using this crate Cargo.toml info.

Structs§

Aliases: An iterator over the aliases of CommandOption.
ArgCount: Represents the number of values an argument takes.
Argument: Represents the arguments of an option or command.
ArgumentList: List of arguments of an option or command.
Command: A command-line command.
CommandLine: Represents a command-line app.
CommandOption: Represents a command-line option.
Context: Provides configuration info for parsing a command.
ContextBuilder: A builder for Context.
Error: An error in a command-line operation.
IterMut: A mutable iterator over the subcommands of a Command.
OptionList: Represents a collection of CommandOptions.
ParseResult: Represents the result of a parse operation and provides a set of methods to query over the values.
Parser: A command-line argument parser.
Prefixes: An iterator over option prefixes.
RawArgs: An iterator over the &str values of the arguments of an ArgumentList.
Values: An iterator over the values of an argument or option.

Enums§

ErrorKind: Types of errors.

Type Aliases§

Result: A convenient Result type.

Crate clapiCopy item path