HewDocumentation 0.9.3

Module std.cli

Command-line parsing over supplied argument strings.

A Command owns its options, child commands and help. Pass arguments without the executable name. Parent options precede a child command; subsequent options belong to that child. -- starts a literal positional tail. Long option names are exact, never abbreviated.

Parsing performs no I/O and never exits the process. Help is a successful Outcome.Help; the application decides how to display it.

import std.cli;

fn main() {
    var app = cli.command("greet", "Greet some neighbours");
    app.argument(cli.flag("enthusiastic", .Some("e"), "Add an exclamation mark"));
    app.positionals("NAME");
    match app.parse(["-e", "Zoë"]) {
        .Ok(.Help(text)) => println(text),
        .Ok(.Parsed(matches)) => {
            let selected = matches.selected();
            for name in selected.positionals {
                if selected.flag("enthusiastic") {
                    println(f"Hello, {name}!");
                } else {
                    println(f"Hello, {name}.");
                }
            }
        }
        .Err(error) => println(f"{error}"),
    }
}

Contents

Functions

Function flag

pub fn flag(name: string, short: Option<string>, help: string) -> Argument

Declare a boolean flag such as --verbose or -v.

Function option

pub fn option(name: string, short: Option<string>, placeholder: string, help: string) -> Argument

Declare a string option. An attached empty value (--label=) is valid.

Function integer

pub fn integer(name: string, short: Option<string>, placeholder: string, help: string) -> Argument

Declare a checked signed i64 option, including negative values.

Function choice

pub fn choice(name: string, short: Option<string>, placeholder: string, help: string, choices: Vec<string>) -> Argument

Declare an option accepting exactly one of the supplied strings.

Function command

pub fn command(name: string, about: string) -> Command

Create a command with no options, positional tail or child commands.

Types

Enum ValueKind

The value accepted by an argument. Strings name its help placeholder.

Variants

Flag
Text(string)
Integer(string)
Choice(string, Vec<string>)

Struct Argument

One long option, with an optional single ASCII short alias.

Fields

name: string
short: Option<string>
help: string
kind: ValueKind
multiple: bool

Struct Command

A command schema. Child commands form groups requiring a command name.

Fields

name: string
about: string
arguments: Vec<Argument>
commands: Vec<Command>
tail: Option<string>

Enum Outcome

Parsing help is successful; application arguments carry checked values.

Variants

Help(string)
Parsed(Matches)

Struct Matches

Parsed command levels, ordered from the root to the selected command.

Fields

commands: Vec<CommandMatch>

Enum Value

A checked value. Choice options produce text.

Variants

Text(string)
Integer(i64)

Struct MatchedValue

A named option value, retained in input order.

Fields

name: string
value: Value

Struct CommandMatch

Arguments belonging to one command, independent of its parents.

Fields

name: string
flags: Vec<string>
entries: Vec<MatchedValue>
positionals: Vec<string>

Enum ParseError

A malformed schema or invalid supplied argument.

Variants

InvalidDefinition(string)
UnknownOption(string)
MissingValue(string)
UnexpectedValue(string)
RepeatedOption(string)
InvalidValue(string, string, string)
UnexpectedArgument(string)
UnknownCommand(string, string)
MissingCommand(string)

Inherent methods

impl Argument

pub fn repeated(self) -> Argument

Allow repeated values, retaining their order. Flags are idempotent.

impl Matches

pub fn root(self) -> CommandMatch

The application's root options, before any child command.

pub fn selected(self) -> CommandMatch

The deepest selected command and its arguments.

impl CommandMatch

pub fn flag(self, name: string) -> bool

Whether a flag was supplied, through either spelling.

pub fn value(self, name: string) -> Option<string>

The first string or choice value, or absence when omitted.

pub fn values(self, name: string) -> Vec<string>

All string or choice values in their input order.

pub fn integer(self, name: string) -> Option<i64>

The first checked integer, or absence when omitted.

pub fn integers(self, name: string) -> Vec<i64>

All checked integers in their input order.

impl Command

pub fn argument(var self, argument: Argument)

Add an option declaration. Conflicting names or aliases fail at parse.

pub fn subcommand(var self, command: Command)

Add a child command. Parent options must precede its name in the input.

pub fn positionals(var self, placeholder: string)

Allow zero or more positional arguments; placeholder labels help.

pub fn help(self) -> string

Render help from this command's declarations.

pub fn parse(self, args: Vec<string>) -> Outcome fails ParseError

Parse supplied arguments, excluding the executable name.

Accepts --name=value, --name value, -abc flag clusters and attached short values such as -j4. Scalar options reject duplication across aliases. A dash-prefixed text value must be attached (--name=-text).