`std/cli`

Command lines: a program with several commands, flags, options and positional arguments, its help text and its errors, declared once. It is the standard library's answer to Rust's clap.

const cli = command "greet" {
  description "Greets people"
  flag "shout", help: "Write the greeting in capitals"
  option<Int>("times", help: "How often", default: 1)
  arguments "names", help: "Who to greet"
  run { input =>
    for name in input.arguments("names") {
      print "Hello, {name}"
    }
  }
}

cli.run Process.arguments()

There are no annotations and no reflection in the language, so the declaration is a builder on receiver closures, the same means project.trb uses. Nothing is registered by scanning: a subcommand is part of the tree because a command block names it.

The help text and the errors are generated. --help and -h print the help text of the command the line chose, help followed by the names of a command prints that one, and a wrong line ends with a message that names the command and the argument (CliError) and exit code 2.

The package is pure except for Command.run. Command.parse reads a list of strings and answers a Parsed or a CliError; Command.help answers the help text. A test hands them argument lists and compares what comes back.

Options are typed. option<Int>("jobs", default: 4) is read as input.option<Int>("jobs"). Int, Float64, Bool and String are Arguments, and a type of the program joins them with an extend.

Options may be optional or repeatable, and a command may pass its arguments on. optional<Path>("output") is read as input.optional<Path>("output"), a Path?; repeatable<String>("filter") as input.repeated<String>("filter"), a list in the order of the line; arguments("rest", passthrough: true) collects the first positional argument and everything behind it, flags too, for a command that hands them to another program.

Modules

std/cli/argumentArgument: the types an option of a command can have.
std/cli/commandCommand: a tree of commands declared once, with the flags, options and positional arguments of each, and what reads a command line against it.
std/cli/errorCliError: what is wrong with a command line.
std/cli/inputInput: what a command line said, as a handler reads it.

Everything

trait ArgumentA type that an option can be read as: it says what its name is in a message and how text becomes a value.
type ArgumentsSpecThe positional arguments of a command, collected as a list.
extend Bool with Argumenttrue or false, and nothing else.
type CliErrorWhy a command line was refused.
type CommandA command with its flags, options, positional arguments and subcommands: the tree [command] builds.
fn commandDeclares a program or a command: its description, its flags, options and positional arguments, its subcommands and what run does.
type CommandBuilderThe receiver of a command block: everything a command can say about itself.
type FlagSpecA switch that is there or is not: --statistics.
extend Float64 with ArgumentDecimal numbers.
type InputThe values of one command line, read by the handler of the command it chose.
extend Int with ArgumentWhole numbers: an optional sign and digits.
type OptionSpecA named value: --jobs 8 or --jobs=8.
type ParsedWhat [Command.parse] read: the command the line chose, its values, and whether the line asked for its help text.
extend String with ArgumentAny text.