std/cli
On this page
Index
- type
Command - type
Flag - type
Arg - type
Parsed- method
Parsed.command - method
Parsed.bool - method
Parsed.str - method
Parsed.str_opt - method
Parsed.int - method
Parsed.int_opt - method
Parsed.duration - method
Parsed.duration_opt - method
Parsed.float - method
Parsed.float_opt - method
Parsed.strs - method
Parsed.is_set - method
Parsed.arg - method
Parsed.arg_opt - method
Parsed.rest
- method
- type
CliErr- method
CliErr.display - method
CliErr.exit_code
- method
- fn
command - fn
bool_flag - fn
str_flag - fn
int_flag - fn
duration_flag - fn
float_flag - fn
choice_flag - fn
strs_flag - fn
arg - fn
rest - fn
parse - fn
parse_or_exit - fn
help - fn
completion
Types
Command
struct Command {}A command: a name, a help line, flags, positional arguments, and subcommands (std.md 14.1).
Flag
struct Flag {}A flag (--name value, -n value, --verbose).
Arg
struct Arg {}A positional argument.
Parsed
struct Parsed {}The result of parse: the selected command and every value.
Parsed.command
fn (p: Parsed) command() -> StrThe selected subcommand path, words joined by one space ("" for the root command).
Parsed.bool
fn (p: Parsed) bool(name: Str) -> BoolParsed.str
fn (p: Parsed) str(name: Str) -> StrThe value given, else the default ("" without one).
Parsed.str_opt
fn (p: Parsed) str_opt(name: Str) -> Str?The value given; None when the flag was not given (on the command line or in its variable).
Parsed.int
fn (p: Parsed) int(name: Str) -> IntParsed.int_opt
fn (p: Parsed) int_opt(name: Str) -> Int?Parsed.duration
fn (p: Parsed) duration(name: Str) -> DurationParsed.duration_opt
fn (p: Parsed) duration_opt(name: Str) -> Duration?Parsed.float
fn (p: Parsed) float(name: Str) -> FloatParsed.float_opt
fn (p: Parsed) float_opt(name: Str) -> Float?Parsed.strs
fn (p: Parsed) strs(name: Str) -> List[Str]Every value of a strs_flag, in order.
Parsed.is_set
fn (p: Parsed) is_set(name: Str) -> BoolWhether the flag was given on the command line or in its variable.
Parsed.arg
fn (p: Parsed) arg(name: Str) -> StrA required positional argument.
Parsed.arg_opt
fn (p: Parsed) arg_opt(name: Str) -> Str?An optional positional argument; None when absent.
Parsed.rest
fn (p: Parsed) rest(name: Str) -> List[Str]The arguments collected by rest.
CliErr
enum CliErr {
Help(text: Str)
Version(text: Str)
Usage(msg: Str, usage: Str)
}Why parse did not return a Parsed. Help and Version are not
failures: the user asked for the text (exit status 0). Usage is a
mistake in the arguments (exit status 2). Displays as the text of
Help and Version and as the message of Usage.
CliErr.display
fn (e: CliErr) display() -> StrCliErr.exit_code
fn (e: CliErr) exit_code() -> Int0 for Help and Version, 2 for Usage.
Functions
command
fn command(name: Str, help: Str, flags: List[Flag] = [], args: List[Arg] = [], commands: List[Command] = [], version: Str = "", single_dash_long: Bool = false, stop_at_positional: Bool = false) -> CommandA command. name is the program’s name for the root command and the
word that selects a subcommand. A command with subcommands takes no
positional arguments of its own.
bool_flag
fn bool_flag(name: Str, help: Str, short: Str = "", env: Str = "", default: Bool = false) -> FlagA flag that is true when given (--verbose, -v, --verbose=false),
else default.
str_flag
fn str_flag(name: Str, help: Str, short: Str = "", default: Str = "", env: Str = "", required: Bool = false, value: Str = "str") -> FlagA text flag. value names the value in the help (--out <path>).
int_flag
fn int_flag(name: Str, help: Str, short: Str = "", default: Int = 0, env: Str = "", required: Bool = false) -> FlagAn integer flag.
duration_flag
fn duration_flag(name: Str, help: Str, short: Str = "", default: Duration = 0s, env: Str = "", required: Bool = false) -> FlagA duration flag, in Duration.parse syntax (30s, 1m30s).
float_flag
fn float_flag(name: Str, help: Str, short: Str = "", default: Float = 0.0, env: Str = "", required: Bool = false) -> FlagA floating point flag, in Float.parse syntax (1.5, 2e-3, inf;
Go’s flag.Float64).
choice_flag
fn choice_flag(name: Str, help: Str, choices: List[Str], short: Str = "", default: Str = "", env: Str = "", required: Bool = false) -> FlagA text flag whose value must be one of choices.
strs_flag
fn strs_flag(name: Str, help: Str, short: Str = "", env: Str = "", value: Str = "str") -> FlagA text flag that may be repeated (-t a -t b); its variable, if any, is
split on commas.
arg
fn arg(name: Str, help: Str, optional: Bool = false) -> ArgOne positional argument, required unless optional.
rest
fn rest(name: Str, help: Str, min: Int = 0) -> ArgEvery remaining positional argument (at least min); must be last.
parse
fn parse(cmd: Command, args: List[Str], env: Env) -> Parsed ! CliErr uses envParses args (without the program name, as Env.args gives them)
against cmd. Flags not given on the command line are read from their
env variable through env.
parse_or_exit
fn parse_or_exit(cmd: Command, env: Env, stdio: Stdio, proc: Proc) -> Parsed uses (env, stdio, proc)parse(cmd, env.args(), env) for main: prints the help or version to
standard output and exits with status 0, or prints a usage error to
standard error and exits with status 2.
help
fn help(cmd: Command, path: Str = "") -> StrThe help text of cmd, or of the subcommand at path (“remote add”).
completion
fn completion(cmd: Command, shell: Str) -> Str ! CliErrA completion script for “bash”, “zsh”, or “fish” (std.md 14.5, decision 0165): subcommands, flags, and choice values; another shell is a Usage error.
↑ index