kex docs Standard Library

OptionParser

type OptionKind

Declarative command-line parsing shared by Kex tools and applications.

Variants

  • StringValue
  • IntegerValue
  • FlagValue

record OptionSpec

Fields

long
String
short
Char? optional
kind
OptionKind optional
description
String optional
default
String? optional
required?
Bool optional

type CommandHandler

What a command does once the line has been parsed. It receives the parsed options with the command's own words already removed, so tey add greet hands its handler ["greet"], and returns the process exit code.

record CommandSpec

Fields

name
String
description
String optional
usage
String optional
handler
CommandHandler
section
String optional

record OptionConfig

Fields

name
String optional
description
String optional
options
[OptionSpec] optional
commands
[CommandSpec] optional

Methods

string

string(long: String, short: Char?, description: String, default: String?, required?: Bool) -> OptionConfig

integer

integer(long: String, short: Char?, description: String, default: String?, required?: Bool) -> OptionConfig

flag

flag(long: String, short: Char?, description: String) -> OptionConfig

command

command(name: String, usage: String, description: String, section: String, handler: CommandHandler) -> OptionConfig

Declares a command. usage is what the help line shows after the name (<name>, [args...]); leave it empty for a command that takes none.

run

run(args: [String]) -> Integer

Parses args and runs the command they name, returning its exit code. A parse failure, an unknown command, or a line with no command at all reports the problem with the help text and returns 1 — the one place that policy has to live for every tool to behave the same way.

printHelp

printHelp : Integer

help

help : String

The help text, styled. Every escape comes from Console, which the runtime blanks under --no-colors and KEX_COLORS=0, so the same code produces plain text down a pipe and this needs no second rendering path.

Widths are measured on the UNSTYLED label throughout: an escape sequence has a length that a terminal does not draw, so padding computed from a coloured string lines the columns up on paper and nowhere else.

record ParsedOptions

Fields

values
{String: String}
arguments
[String]

Methods

value

value(name: String, default: String) -> String?

flagEnabled?

flagEnabled?(name: String) -> Bool

integerValue

integerValue(name: String) -> Integer?

type OptionParseError

Variants

  • UnknownOption(String)
  • MissingValue(String)
  • UnexpectedValue(String)
  • MissingRequired(String)
  • InvalidInteger(String, String)

module OptionParser

define

define(name: String, description: String) -> OptionConfig

commandLabel

commandLabel(command: CommandSpec) -> String

commandFor

commandFor(commands: [CommandSpec], arguments: [String]) -> (CommandSpec, [String])?

The declared command whose words open arguments, with what is left after them. Longest match first, so kex install is preferred over a kex that also exists.

opensWith?

opensWith?(arguments: [String], name: String) -> Bool

errorMessage

errorMessage(error: OptionParseError) -> String

parse

parse(options: [OptionSpec], args: [String]) -> Result<ParsedOptions, OptionParseError>