std/cli

Types

ParseError

pub type ParseError =
    | UnknownFlag(token: String)
    | MissingValue(flag: String)
    | InvalidValue(flag: String, value: String, reason: String)
    | MissingFlag(flag: String)
    | MissingArgument(name: String)
    | UnexpectedArgument(token: String)
    | UnknownSubcommand(token: String)
    | MissingSubcommand(names: String)
    | BadDefinition(reason: String)

Why a command line did not parse. Texts that came from an argument are its lossy form, with U+FFFD for bytes that are not UTF-8.

ParseError.message

pub fn ParseError.message(self) -> String

The one-line text for the user, without the program name or a trailing newline.

Parser

pub type Parser = {
    // private fields omitted
}

One command line being read. Each declaration finds its occurrences, converts them and writes its destination before it returns, so no borrow outlives a call. Declare the flags of a level before its arguments and subcommands, and call finish last.

Parser.usage

pub fn Parser.usage(self) -> String

The Usage: line for the command selected so far.

Parser.help

pub fn Parser.help(self) -> String

Full help for the command selected so far: description, usage, subcommands, arguments and flags, built from the declarations. Show it from the Help outcome; the declarations made before finish decide what it lists.

Parser.new

pub fn Parser.new(name: String, argv: &Array[os.OsString], about: String = "") -> Parser

A parser for argv, the arguments after the program name; the strings are copied, so argv stays usable.

Parser.fromArgs

pub fn Parser.fromArgs(name: String, args: os.Args) -> Parser

A parser for the process arguments; index 0 of args is the program path and is not read as an argument.

Parser.fromArgs

pub fn Parser.fromArgs(name: String, args: os.Args, about: String) -> Parser

fromArgs with a one-line description for help.

Parser.arg

pub fn Parser.arg[T: FlagValue](mut self, name: String, dest: &mut T, help: String = "")

Declares the next positional argument and writes it into dest. A plain destination is required, an Option is optional and an Array takes every argument that is left, including all of those after --. Declare the flags of the level first.

Parser.argOs

pub fn Parser.argOs(mut self, name: String, dest: &mut os.OsString, help: String = "")

arg for a destination that keeps the argument exactly as the OS passed it.

Parser.argOsOption

pub fn Parser.argOsOption(mut self, name: String, dest: &mut os.OsString?, help: String = "")

argOs for an optional OsString.

Parser.argOsRest

pub fn Parser.argOsRest(mut self, name: String, dest: &mut Array[os.OsString], help: String = "")

argOs for the rest of the arguments as OsStrings.

Parser.withArg

pub fn Parser.withArg[T: FlagValue](move self, name: String, dest: &mut T, help: String = "") -> Parser

arg in the chain form.

Parser.subcommand

pub fn Parser.subcommand(mut self, name: String, about: String = "") -> Bool

Declares a subcommand and returns whether the command line selected it; later calls then belong to it, with the flags above still in force. Test the subcommands of one level as an else if chain: a second if after a selected branch reads as a subcommand of that branch.

Parser.path

pub fn Parser.path(self) -> Array[String]

The command names selected so far, the program first.

Parser.finish

pub fn Parser.finish(move self) -> Result[Outcome, ParseError]

Ends the declarations and consumes the parser. Returns Help when help was asked for, otherwise the first problem found: a declaration or conversion error in call order, then the first undeclared argument in command line order, last a subcommand that requireCommand demands.

Parser.requireCommand

pub fn Parser.requireCommand(mut self)

Makes a subcommand mandatory at the current level, so finish reports MissingSubcommand when none was selected. Call it before the subcommand tests of that level, since selecting one moves the parser down a level.

Parser.flag

pub fn Parser.flag[T: FlagValue](mut self, name: String, dest: &mut T, help: String = "", short: String = "", required: Bool = false)

Declares --name (and -c for a one-character short) and writes its occurrences into dest. A Bool is a switch, an Array collects every occurrence, anything else keeps the last; dest keeps its value when the flag is absent, and required rejects that.

Parser.flagWith

pub fn Parser.flagWith[T](mut self, name: String, dest: &mut T, argName: String, convert: fn(String) -> Result[T, String], help: String = "", short: String = "", required: Bool = false)

flag for a destination that is not a FlagValue: convert reads the argument as text and returns the value or a reason.

Parser.withFlag

pub fn Parser.withFlag[T: FlagValue](move self, name: String, dest: &mut T, help: String = "", short: String = "", required: Bool = false) -> Parser

flag in the chain form: takes the parser and gives it back, so a command line can be declared in one expression.

Parser.flagOs

pub fn Parser.flagOs(mut self, name: String, dest: &mut os.OsString, help: String = "", short: String = "", required: Bool = false)

flag for a destination that keeps the argument exactly as the OS passed it. OsString is not a FlagValue, so the OsString forms have their own names.

Parser.flagOsOption

pub fn Parser.flagOsOption(mut self, name: String, dest: &mut os.OsString?, help: String = "", short: String = "", required: Bool = false)

flagOs for an optional OsString.

Parser.flagOsMany

pub fn Parser.flagOsMany(mut self, name: String, dest: &mut Array[os.OsString], help: String = "", short: String = "", required: Bool = false)

flagOs for a repeatable OsString: every occurrence is appended.

Outcome

pub type Outcome =
    | Run
    | Help(text: String)

What a successfully read command line asks for: to run, or to show help (--help or -h, unless a flag of that name was declared).

Shape

pub type Shape =
    | Switch
    | Single
    | Optional
    | Many

How a command line reads a value of a type: a bool flag that needs no argument, exactly one value, an optional one, or any number of them.

ValueInfo

pub type ValueInfo = {
    pub name String
    pub shape Shape
}

What help and the parser need to know about a destination type; name is the placeholder shown in help, such as int.

Interfaces

FlagValue

pub interface FlagValue {
    fn parseFlag(arg: &os.OsString) -> Result[Self, String]
    fn absorbFlag(mut self, value: Self)
    fn flagInfo() -> ValueInfo
}

Types a flag or positional argument can write into. The standard scalar types, String, OsString, Option[T] and Array[T] implement it. A reason in Err is a short phrase such as expected an integer; the parser adds the flag and the offending value.

Methods of i64

i64.parseFlag

pub fn i64.parseFlag(arg: &os.OsString) -> Result[i64, String]

i64.absorbFlag

pub fn i64.absorbFlag(mut self, value: i64)

i64.flagInfo

pub fn i64.flagInfo() -> ValueInfo

Methods of i8

i8.parseFlag

pub fn i8.parseFlag(arg: &os.OsString) -> Result[i8, String]

i8.absorbFlag

pub fn i8.absorbFlag(mut self, value: i8)

i8.flagInfo

pub fn i8.flagInfo() -> ValueInfo

Methods of i16

i16.parseFlag

pub fn i16.parseFlag(arg: &os.OsString) -> Result[i16, String]

i16.absorbFlag

pub fn i16.absorbFlag(mut self, value: i16)

i16.flagInfo

pub fn i16.flagInfo() -> ValueInfo

Methods of i32

i32.parseFlag

pub fn i32.parseFlag(arg: &os.OsString) -> Result[i32, String]

i32.absorbFlag

pub fn i32.absorbFlag(mut self, value: i32)

i32.flagInfo

pub fn i32.flagInfo() -> ValueInfo

Methods of u8

u8.parseFlag

pub fn u8.parseFlag(arg: &os.OsString) -> Result[u8, String]

u8.absorbFlag

pub fn u8.absorbFlag(mut self, value: u8)

u8.flagInfo

pub fn u8.flagInfo() -> ValueInfo

Methods of u16

u16.parseFlag

pub fn u16.parseFlag(arg: &os.OsString) -> Result[u16, String]

u16.absorbFlag

pub fn u16.absorbFlag(mut self, value: u16)

u16.flagInfo

pub fn u16.flagInfo() -> ValueInfo

Methods of u32

u32.parseFlag

pub fn u32.parseFlag(arg: &os.OsString) -> Result[u32, String]

u32.absorbFlag

pub fn u32.absorbFlag(mut self, value: u32)

u32.flagInfo

pub fn u32.flagInfo() -> ValueInfo

Methods of isize

isize.parseFlag

pub fn isize.parseFlag(arg: &os.OsString) -> Result[isize, String]

isize.absorbFlag

pub fn isize.absorbFlag(mut self, value: isize)

isize.flagInfo

pub fn isize.flagInfo() -> ValueInfo

Methods of u64

u64.parseFlag

pub fn u64.parseFlag(arg: &os.OsString) -> Result[u64, String]

u64.absorbFlag

pub fn u64.absorbFlag(mut self, value: u64)

u64.flagInfo

pub fn u64.flagInfo() -> ValueInfo

Methods of usize

usize.parseFlag

pub fn usize.parseFlag(arg: &os.OsString) -> Result[usize, String]

usize.absorbFlag

pub fn usize.absorbFlag(mut self, value: usize)

usize.flagInfo

pub fn usize.flagInfo() -> ValueInfo

Methods of i128

i128.parseFlag

pub fn i128.parseFlag(arg: &os.OsString) -> Result[i128, String]

i128.absorbFlag

pub fn i128.absorbFlag(mut self, value: i128)

i128.flagInfo

pub fn i128.flagInfo() -> ValueInfo

Methods of u128

u128.parseFlag

pub fn u128.parseFlag(arg: &os.OsString) -> Result[u128, String]

u128.absorbFlag

pub fn u128.absorbFlag(mut self, value: u128)

u128.flagInfo

pub fn u128.flagInfo() -> ValueInfo

Methods of f64

f64.parseFlag

pub fn f64.parseFlag(arg: &os.OsString) -> Result[f64, String]

f64.absorbFlag

pub fn f64.absorbFlag(mut self, value: f64)

f64.flagInfo

pub fn f64.flagInfo() -> ValueInfo

Methods of f32

f32.parseFlag

pub fn f32.parseFlag(arg: &os.OsString) -> Result[f32, String]

f32.absorbFlag

pub fn f32.absorbFlag(mut self, value: f32)

f32.flagInfo

pub fn f32.flagInfo() -> ValueInfo

Methods of String

String.parseFlag

pub fn String.parseFlag(arg: &os.OsString) -> Result[String, String]

String.absorbFlag

pub fn String.absorbFlag(mut self, value: String)

String.flagInfo

pub fn String.flagInfo() -> ValueInfo

Methods of Bool

Bool.parseFlag

pub fn Bool.parseFlag(arg: &os.OsString) -> Result[Bool, String]

Bool.absorbFlag

pub fn Bool.absorbFlag(mut self, value: Bool)

Bool.flagInfo

pub fn Bool.flagInfo() -> ValueInfo

Methods of Char

Char.parseFlag

pub fn Char.parseFlag(arg: &os.OsString) -> Result[Char, String]

Char.absorbFlag

pub fn Char.absorbFlag(mut self, value: Char)

Char.flagInfo

pub fn Char.flagInfo() -> ValueInfo

Methods of Option

Option.parseFlag

pub fn Option[T: FlagValue].parseFlag(arg: &os.OsString) -> Result[T?, String]

Option.absorbFlag

pub fn Option[T: FlagValue].absorbFlag(mut self, value: T?)

Option.flagInfo

pub fn Option[T: FlagValue].flagInfo() -> ValueInfo

Methods of Array

Array.parseFlag

pub fn Array[T: FlagValue].parseFlag(arg: &os.OsString) -> Result[Array[T], String]

Array.absorbFlag

pub fn Array[T: FlagValue].absorbFlag(mut self, value: Array[T])

Array.flagInfo

pub fn Array[T: FlagValue].flagInfo() -> ValueInfo