Crate usage_rs 

The facade for building compiled Rust CLIs with usage.

Depend on usage-rs under the short crate name usage. That is the one package an application needs: derive macros, the argv runtime, help, and clap-shaped errors ship in the defaults. Completions stay behind a feature; low-level adopters that want only the binding runtime keep depending on usage-argv directly.

[dependencies]
usage = { package = "usage-rs", version = "6" }

What happens after a parse can come from the same declaration: a command implements Run, the subcommand enum says #[usage(run)], and the match that routes argv to the code carrying it out is generated rather than written. RunWith under #[usage(run_with)] hands each command shared state, and RunAsync / RunAsyncWith under #[usage(run_async)] / #[usage(run_async_with)] are the async pair. Nothing about any of it reaches the spec.

Enable portable expression validation only when a CLI declares validate rules:

usage = { package = "usage-rs", version = "6", features = ["validation"] }

use usage_rs as usage;
use usage::Cli;

#[derive(Cli)]
#[usage(bin = "ex")]
struct Ex {
    #[usage(long, value_hint = usage::ValueHint::FilePath)]
    file: Option<std::path::PathBuf>,
}

let argv = [std::ffi::OsStr::new("--file"), std::ffi::OsStr::new("input.txt")];
let ex = Ex::parse_from(&argv).expect("valid command line");
assert_eq!(ex.file.as_deref(), Some(std::path::Path::new("input.txt")));

Re-exports

pub use usage_argv as argv;

Modules

diagnostic

What a user reads when a command line does not parse.

embedded

Process control for a CLI embedded in another runtime.

help

The one-line summary of how a command is invoked.

run

Dispatch: handing a parsed command to the code that carries it out.

spec

Cold-path metadata, and writing it out as a spec.

warn

What a parse has to say about declarations that still work but should not be used.

Macros

__usage_needs_complete_feature

See __usage_needs_complete_feature.

Structs

Arg

A positional argument.

BindingType

Resolved identity of a derive-generated binding type.

Clause

A separator-delimited positional group.

Command

A command: its flags, its positional arguments, and its subcommands.

Flag

A flag, addressed by any of its long or short forms.

InvalidValue

Why a value would not convert into the type its field holds.

Parser

A single-pass parse over argv.

ValidationError

A command-wide validation or finalization failure.

Enums

ArgAction

What supplying a declared flag does.

DoubleDash

How an argument relates to the -- separator.

Error

A binding failure.

Event

Something the parser bound.

UnknownFlags

What to do with a flag-like token that names no flag in scope.

ValueHint

A value’s shell-native completion class for #[usage(value_hint = ...)].

Constants

HELP_LONG_KEY

The key --help answers to, and the one -h does.

HELP_SHORT_KEY

See HELP_LONG_KEY.

MAX_DEPTH

How deep a command tree this parser will descend.

SPEC_REQUEST

The word a tool sends to ask a binary for its own spec.

VERSION_LONG_KEY

See HELP_LONG_KEY.

VERSION_SHORT_KEY

See HELP_LONG_KEY.

Statics

HELP_LONG

--help, which every command answers to.

HELP_SHORT

-h, which prints the shorter form.

VERSION_LONG

--version, where the CLI declared one.

VERSION_SHORT

-V, which clap also supplies.

Traits

Run

A command that can be carried out with nothing but what it parsed.

RunAsync

An async command: Run, awaited.

RunAsyncWith

An async command that is handed something shared when it runs: RunWith, awaited.

RunWith

A command that is handed something shared when it runs.

Functions

as_str

Interpret a value as UTF-8.

assert_unique_subcommand_names

Refuse two subcommands that answer to the same name, aliases included.

concat_args

Join groups of argument tables into one, at compile time.

concat_flags

Join groups of flag tables into one, at compile time.

find_subcommand

Resolve a subcommand by name or alias, at compile time.

invalid_choice_value

One Error::InvalidValue for a word that is not one of a value enum’s choices.

invalid_os_value

One Error::InvalidValue for bytes the platform cannot hold in a path.

invalid_parsed_value

One Error::InvalidValue for a value whose type would not build from it.

invalid_utf8_value

One Error::InvalidValue for a word that was not UTF-8.

is_help_flag

Whether a flag is one of the two the parser supplies rather than the CLI declaring it.

is_spec_request

Whether this argv asks for the spec rather than for the CLI to run.

is_version_arg

Whether one exact root argument selects a declared or synthesized version action.

is_version_flag

Whether a flag is one of the two the parser supplies for --version.

key_base

The high half of every key one declaration’s items get.

multicall_applet

The applet name to parse as the first word, when argv[0] is not the dispatcher.

multicall_basename

Basename of argv[0] for a multicall CLI: last path component, with a trailing .exe stripped so Windows and Unix agree.

os_string_from_bytes

Rebuild an OsString from bytes the parser handed back.

os_values

Convert every repeated value of one path-like field, reporting name for the first the platform cannot hold.

parsed_values

Convert every repeated value of one field through FromStr, reporting name for the first that fails.

render_failure

What a caller should print for a parse failure, and what to exit with.

render_failure_plain

A parse failure, never coloured.

render_failure_view

Render a failure through a spec-declared executable view.

render_warnings

What a caller should print for the deprecations a command line used.

table_len

How many entries a group of tables holds in total.

utf8_values

Convert every repeated value of one text field, reporting name for the first that is not UTF-8.

Derive Macros

ArgGroup

Compile an enum into a set of related flags.

Args

Compile a struct into one subcommand’s flags and arguments.

Cli

Compile a struct into a parser and a spec. See the crate docs.

Subcommands

Compile an enum into a set of subcommands.

ValueEnum

Compile an enum into the words one value may be.