silk.cli.parse.

When to use#

Call Cli.read from main to read the process arguments and print help, the version, or errors, Cli.fromHost to handle those yourself, or Cli.parse to parse a list of arguments that you already have, such as in a test.

Details#

The type to parse has CommandLine, which describes it. The description and the type are checked against each other during compilation. The loops over the fields and variants are expanded during compilation too, so the parser that runs only compares each argument with the option names and calls the reader of the matching field type. The parser builds the value after it has read the whole command line, so a subcommand that was not chosen never exists, and a field that the command line does not give takes its Opt.default, its environment variable, or ArgValue.initial.

Subcommands are the variants of a union, named in kebab case: a field marked with Command.subcommand holds the variant that the command line chose.

The parser accepts --name value, --name=value, -n value, -n5, flags such as --loud, grouped one-letter flags such as -abc, positional arguments, and --, after which every argument is positional. An option that takes one value, or a flag, may be given once; a List field takes each occurrence. An unknown option names the closest option, when one is close. --help and -h give Parsed.Help, and --version gives Parsed.Version when the command has a version.

Import as Cli with import silk.cli.parse { Cli }.

Public declarations: 4.

CliError#

pub union CliError

Why a command line was not accepted.

UnknownOption#

UnknownOption

An argument looks like an option, but no option has that name.

Field token#

pub token: String

The argument as given.

Field suggestion#

pub suggestion: string<'static>

The option whose name is closest to the argument, such as --name for --nmae, or empty when no name is close.

Repeated#

Repeated

An option that takes one value, or a flag, is given more than once.

Field option#

pub option: string<'static>

The option, such as --name.

MissingValue#

MissingValue

An option that takes a value is the last argument.

Field option#

pub option: string<'static>

The option, such as --name.

NotAChoice#

NotAChoice

The value of an option or positional argument is not one of its choices.

Field option#

pub option: string<'static>

The option, such as --format, or the positional argument, such as <format>.

Field token#

pub token: String

The value as given.

Field choices#

pub choices: string<'static>

The choices, separated by commas, such as json, text.

InvalidValue#

InvalidValue

The value of an option or positional argument is not valid for its field type.

Field option#

pub option: string<'static>

The option, such as --times, or the positional argument, such as <files>.

Field token#

pub token: String

The value as given.

UnexpectedValue#

UnexpectedValue

A flag was given a value with =.

Field option#

pub option: string<'static>

The flag, such as --loud.

MissingRequired#

MissingRequired

A required option or positional argument is missing.

Field option#

pub option: string<'static>

The option, such as --name, or the positional argument, such as <files>.

UnexpectedArgument#

UnexpectedArgument

There are more positional arguments than the command takes.

Field token#

pub token: String

The argument as given.

MissingCommand#

MissingCommand

A command with subcommands was given none.

Field command#

pub command: string<'static>

The command, such as git remote.

UnknownCommand#

UnknownCommand

An argument names no subcommand.

Field command#

pub command: string<'static>

The command, such as git remote.

Field token#

pub token: String

The argument as given.

Parsed#

pub union Parsed<T>

The result of parsing a command line.

Run#

Run

The command line was accepted. value holds the parsed fields.

Field value#

pub value: T

The parsed struct.

Help#

Help

The command line asked for the help text.

Field command#

pub command: string<'static>

The subcommand path whose help was asked for, such as remote.add, in the names the command line uses. Empty for the root command. Give it to Cli.writeHelp.

Version#

Version

The command line asked for the version.

Failed#

Failed

The command line was not accepted.

Field error#

pub error: CliError

Why.

Variable#

pub struct Variable<'a>

One environment variable, for Cli.parseWith.

Field name#

pub name: string<'a>

The variable name, such as HOME.

Field value#

pub value: string<'a>

The variable value.

Implementation Copy for Variable<'a>#

impl<'a> Copy for Variable<'a>

Cli#

pub struct Cli

The owner type of the parser. It has no fields and is never constructed.

Implementation Cli#

impl Cli

Associated function parse#

pub effect fn parse<T: CommandLine>(arguments: &[string]) -> Parsed<T>
    ! OutOfMemoryError
    ? &mut Allocator

Parses arguments into a T, as T's CommandLine description says. arguments[0] is the program name and is skipped.

Details#

Each field of T is an option unless the description marks it positional or a subcommand. A description that names a field T does not have, or a field type without ArgValue, is a compile error.

Associated function parseWith#

pub effect fn parseWith<T: CommandLine>(
    arguments: &[string],
    environment: &[Variable<'_>],
  ) -> Parsed<T>
    ! OutOfMemoryError
    ? &mut Allocator

Parses like Cli.parse, and reads an option that the command line does not give from environment when the option names a variable with Opt.env. The command line wins over the environment, and the environment wins over Opt.default.

Associated function parseBytes#

pub effect fn parseBytes<T: CommandLine>(
    arguments: &[Bytes],
    environment: &[Variable<'_>],
  ) -> Parsed<T>
    ! OutOfMemoryError
    ? &mut Allocator

Parses like Cli.parseWith, from arguments as the program received them, such as HostInput.arguments. A Bytes field takes its argument's exact bytes; every other field reads the argument as text, where each byte that is not valid UTF-8 reads as ?.

Associated function fromHost#

pub effect fn fromHost<T: CommandLine>() -> Parsed<T>
    ! HostInputError | OutOfMemoryError
    ? &mut HostInput | &mut Allocator

Reads the process arguments, and the environment variables that T's description names, and parses them with Cli.parseWith.

Errors#

• HostInputError if the arguments cannot be read.

• OutOfMemoryError if the Allocator cannot supply the copies.

Associated function read#

pub effect fn read<T: CommandLine>() -> Result<T, i32>
    ! HostInputError | OutOfMemoryError | WriterError
    ? &mut HostInput | &mut Allocator

Reads the command line like Cli.fromHost, and handles everything but a value: it writes the help text or the version to standard output, or the error to standard error. Returns the value, or in Result.Failure the exit code for main to return: 0 after help or the version, 2 after an error.

Errors#

• HostInputError if the arguments cannot be read.

• OutOfMemoryError if the Allocator cannot supply the copies.

• WriterError if standard output or standard error fails.

Associated function writeHelp#

pub effect fn writeHelp<T: CommandLine>(path: string) -> ()
    ! WriterError
    ? &mut Writer

Writes the help text of the command or subcommand at path (from Parsed.Help; empty for the root command) of T.

Errors#

• WriterError if the Writer fails.

Associated function writeVersion#

pub effect fn writeVersion<T: CommandLine>() -> ()
    ! WriterError
    ? &mut Writer

Writes the version of T's command and a line break.

Errors#

• WriterError if the Writer fails.

Associated function writeError#

pub effect fn writeError(error: &CliError) -> ()
    ! WriterError
    ? &mut Writer

Writes a one-line message for error, such as error: unknown option --nmae.

Errors#

• WriterError if the Writer fails.

Associated function message#

pub effect fn message(error: &CliError) -> String
    ! OutOfMemoryError
    ? &mut Allocator

Returns the message for error that Cli.writeError writes, without error: and the line break, such as unknown option --nmae; did you mean --name?.

Errors#

• OutOfMemoryError if the Allocator cannot supply the text.

Category: Command line.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.