Struct App 

pub struct App<C> { /* private fields */ }

Available on crate feature app only.

One ctl process: short-circuits, help, parsing, execution, and presentation.

C is the CLI’s Clap parser. Build an App with Self::new, configure it with the builder methods, and finish with Self::run. Every builder takes self, so a setting set later replaces an earlier one. The one exception: Self::theme wins over the theme in Self::styles, whichever is called first.

Implementations

impl<C> App<C>

pub fn new(bin: impl Into<String>) -> Self

Build a CLI named bin with pretty output and automatic colour.

bin prefixes error lines (bin: message) and names the binary in JSON error envelopes. Self::view replaces the default view.

pub fn view(self, select: impl Fn(&C) -> View + 'static) -> Self

Pick the View for a run from the parsed CLI, usually from OutputArgs.

The select closure runs after a successful parse. Help and parse errors come before it, so they read the format and colour from the raw arguments instead. The width, style, and layout settings of this App are applied on top of the view select returns.

pub fn automatic_width_buffer(self, cells: u16) -> Self

Override the number of cells subtracted from an automatically detected width, for help, errors, and command output. Zero disables the subtraction. An explicit view width stays exact.

pub fn automatic_width_buffer_envs(self, names: &'static [&'static str]) -> Self

Replace the ordered environment names that set the buffer, for every automatic-width render. An empty slice disables environment lookup.

pub fn minimum_automatic_width(self, cells: u16) -> Self

Set the floor, in cells, for an automatically detected width.

pub fn fallback_width(self, width: Option<u16>) -> Self

Lay out to width cells when no width is detected. None turns the fallback off, so tables render at their natural width.

pub fn input_limits(self, limits: Limits) -> Self

Available on crate features input-toml or input-yaml only.

Set the process-wide default input limits as soon as it is called, not when the App runs. The limits of a single call win over them, and so does a repository’s .ctl/input.yaml with input-yaml.

pub fn styles(self, styles: RenderOptions) -> Self

Take the theme, record style, table frame, row separation, and the variables they read from styles, for help, errors, and command output. Its colour and width settings are ignored.

pub fn json_layout(self, layout: JsonLayout) -> Self

Lay out JSON output as layout. This beats the environment.

pub fn json_layout_envs(self, names: &'static [&'static str]) -> Self

Replace the ordered environment names read for the JSON layout. An empty slice disables lookup.

pub fn theme(self, theme: Theme) -> Self

Draw help, errors, and command output in theme, in place of Theme::default. It also replaces the theme a Self::styles value carries. Colour is still the colour mode’s choice: --color never writes no style.

pub fn broken_pipe(self, policy: BrokenPipe) -> Self

Exit as policy says when the reader closes stdout or stderr before the output is written. The default, BrokenPipe::Ignore, exits with the command’s own code and writes nothing to stderr.

pub fn before_parse( self, hook: impl Fn(&[OsString]) -> Option<ExitCode> + 'static, ) -> Self

Add a hook that runs before parsing and may end the run.

A hook gets the raw argv, program name first. Returning Some(code) stops the run with that code. Hooks run in the order added, after a --usage-spec request and before help and parsing.

pub fn completion(self) -> Self

where C: CommandFactory + 'static,

Available on crate feature completion only.

Answer COMPLETE=<shell> before parsing, so the script the completion verb prints can ask this binary for candidates.

A run without the variable, or with it empty or 0, parses as usual. See the completion module.

pub fn mounted_as(self, task: impl Into<String>) -> Self

Available on crate feature usage only.

Answer a --usage-spec request from mise for the task named task.

When argv matches, the run prints the Usage spec to stdout and exits 0 without parsing. See the usage module for the argv shape.

pub fn usage_spec( self, render: impl Fn(Command, &str) -> String + 'static, ) -> Self

Available on crate feature usage only.

Replace how the Usage document is rendered, keeping the short-circuit and the stdout write. The render callback receives the declared Clap command and the requested task name, and returns the document text.

impl<C> App<C>

where C: Parser + CommandFactory,

pub fn run<T>(self, execute: impl FnOnce(C) -> Result<T>) -> ExitCode

where T: Present,

Run against the process argv and return the exit code for main.

The handler execute gets the parsed CLI. An Err from it is written as an error (bin: message, or a JSON envelope) with exit code 1. Its message includes the whole anyhow chain.

Panics

Panics when the command disables -h/--help or -V/--version.

pub fn run_from<T>( self, args: impl IntoIterator<Item = impl Into<OsString>>, execute: impl FnOnce(C) -> Result<T>, ) -> ExitCode

where T: Present,

Run against explicit argv. The first item is the binary name.

The result is the same as Self::run. Use it in tests with a fixed argv.

Panics

Panics when the command disables -h/--help or -V/--version.

Trait Implementations

impl<C> Debug for App<C>

Names the binary only: the hooks are closures, which have no Debug.

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

Formats the value using the given formatter.