Struct arkham::App

pub struct App {
    pub root: Command,
    // some fields omitted
}

Fields

root: Command

Implementations

impl App

pub fn application_header(&self) -> String

impl App

pub fn new() -> Self

Contructs a new App instance which can have opts defined and subcommands attached.

pub fn name(self, name: &'static str) -> Self

Sets the name of the application. If not set the cargo package name will be used.

Exmaple:

use arkham::App;
let app = App::new().name("new app");

pub fn version(self, version: &'static str) -> Self

Sets the version for the application. If not set the cargo package version is used.

Example:

use arkham::App;
App::new().version("1.0.0");

pub fn env_prefix(self, prefix: &'static str) -> Self

Sets the environment variable prefix for option resolution. If set to something like APP_NAME a option with the name THING, will look for an environment variable named APP_NAME_THING.

Example:

use arkham::App;
App::new().env_prefix("APP_NAME");

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

Adds a root level command to the application. This command can then be executed with:

myapp command_name

Help flags will also be generated for the command which will display command information for:

myapp –help command_name or myapp help command_name

Example:

use arkham::{App, Command, Context};
App::new().command(Command::new("subcommand").handler(my_handler));

fn my_handler(app: &App, ctx: &Context, args: &[String]) {}

pub fn commands(self, commands: Vec<Command>) -> Self

Similar to App::Command but allows multiple commands to be added at once. Adds a root level commands to the application. This command can then be executed with:

myapp command_name

Help flags will also be generated for the command which will display command information for:

myapp –help command_name or myapp help command_name

Example:

use arkham::{App, Command, Context};
let names = vec!["one", "two", "three"];
let commands = names.into_iter().map(|name| Command::new(name).handler(my_handler)).collect();
App::new().commands(commands);

fn my_handler(app: &App, ctx: &Context, args: &[String]) {}

pub fn opt(self, opt: Opt) -> Self

Adds a root level opt/flag that is available to all commands. Opts are given a name which is used to reference them, as well as a short and long identifier.

Example:

use arkham::{App, Opt};
App::new().opt(Opt::flag("verbose").short("v").long("verbose"));

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

Sets a handler function for the bare root command. If this is not set an error will be generated and a help message will be displayed indicating the available subcommands. The handler function takes an instance of the app, the context which contains the opts and flags, and any additionally passeed arguments.

Example:

use arkham::{App, Command, Context};
App::new().handler(my_handler);

fn my_handler(app: &App, ctx: &Context, args: &[String]) {}

pub fn long_desc(self, desc: &str) -> Self

Sets the longe description for the bare app. This will be displayed in the help content when no additional subcommands are given. Example:

use arkham::{App, Command, Context};
App::new().long_desc("This app does all the things");

pub fn run_with(&mut self, args: Vec<String>) -> Result<(), OptError>

Execute the app and any specified handlers based on the passed arguemnts. This function is mostly used for testing or any situation where you need to pass arbitrary arguments instead of using the ones passed to the application. Example:

use arkham::{App, Command, Context, Opt};
App::new()
    .opt(Opt::scalar("name").short("n").long("name"))
    .handler(my_handler)
    .run_with(vec!["-n".to_string(), "alice".to_string()]);

fn my_handler(app: &App, ctx: &Context, args: &[String]) {
    println!("Hello, {}", ctx.get_string("name").unwrap());
}

pub fn run(&mut self) -> Result<(), OptError>

Execute the app and any specified handlers based on the arguments passsed to the application.

Example: running with myapp –name alice

use arkham::{App, Command, Context, Opt};
App::new()
    .opt(Opt::flag("name").short("n").long("name"))
    .handler(my_handler)
    .run();

fn my_handler(app: &App, ctx: &Context, args: &[String]) {
    println!("Hello, {}", ctx.get_string("name").unwrap_or_else(|| "unnamed".into()));
}

pub fn root_context(&self) -> Result<Context, OptError>

Generates a context for the root command allowing flags to be parsed. This can be useful to predetect certian root level arguments before processing sub commands and other app configurations.

impl App

pub fn config_filename(&mut self, _filename: &'static str) -> Self

Trait Implementations

impl Default for App

fn default() -> Self

Returns the “default value” for a type.