Base

:= []

on_successful_arg_parse : ArgParser(a), (ArgParserState(a) -> ArgParserResult(ArgParserState(b))) -> ArgParser(b)

A bind operation for ArgParserState.

map_successfully_parsed : ArgParserResult(a), (a -> b) -> ArgParserResult(b)

Maps successfully parsed data in an ArgParserResult.

str_type_name : Str

num_type_name : Str

arg_to_bytes : Path -> List(U8)

Convert an OS-aware argument to bytes, using big-endian code units on Windows.

help_option : OptionConfig

Metadata for the -h/--help option that we parse automatically.

version_option : OptionConfig

Metadata for the -V/--version option that we parse automatically.

ArgParserResult

:= [
    ShowHelp({ subcommand_path : List(Str) }),
    ShowVersion,
    IncorrectUsage(ArgExtractErr, { subcommand_path : List(Str) }),
    SuccessfullyParsed(a),
]

The result of attempting to parse args into config data.

is_eq : _

ArgParserParams : { args : List(ParsedArg), subcommand_path : List(Str) }

The parameters that an ArgParser takes to extract data from args.

ArgParserState : { data : a, remaining_args : List(ParsedArg), subcommand_path : List(Str) }

The intermediate state that an ArgParser passes between steps.

ArgParser : ArgParserParams -> ArgParserResult(ArgParserState(a))

A function that extracts configuration data from parsed arguments.

ArgExtractErr : [
    NoSubcommandCalled,
    MissingOption(OptionConfig),
    OptionCanOnlyBeSetOnce(OptionConfig),
    NoValueProvidedForOption(OptionConfig),
    OptionDoesNotExpectValue(OptionConfig),
    CannotUsePartialShortGroupAsValue(OptionConfig, List(Str)),
    ValueOptionMustBeLastInShortGroup(OptionConfig, List(Str)),
    InvalidOptionValue(InvalidValue, OptionConfig),
    InvalidParamValue(InvalidValue, ParameterConfig),
    MissingParam(ParameterConfig),
    UnrecognizedSubcommand(Path),
    UnrecognizedShortArg(Str),
    UnrecognizedLongArg(Str),
    ExtraParamProvided(Path),
]

Errors that can occur while extracting values from command line arguments.

TextStyle : [Color, Plain]

Whether help text should have fancy styling.

ExpectedValue : [ExpectsValue(Str), NothingExpected]

The type of value that an option expects to parse.

Plurality : [Optional, One, Many]

How many values an option/parameter can take.

SpecialFlags : { help : Bool, version : Bool }

The two built-in flags that we parse automatically.

InvalidValue : [InvalidNumStr, InvalidValue(Str), InvalidUtf8]

DefaultValue : [NoDefault, Value(a), Generate({  } -> a)]

ValueParser : Path -> Try(a, InvalidValue)

A parser that extracts an argument value.

OptionConfigBaseParams : { short : Str, long : Str, help : Str }

DefaultableOptionConfigBaseParams : {
    short : Str,
    long : Str,
    help : Str,
    default : DefaultValue(a),
}

OptionConfigParams : {
    short : Str,
    long : Str,
    help : Str,
    type : Str,
    parser : ValueParser(a),
}

Options for creating an option with a custom parser.

DefaultableOptionConfigParams : {
    short : Str,
    long : Str,
    help : Str,
    type : Str,
    parser : ValueParser(a),
    default : DefaultValue(a),
}

Options for creating an option with a custom parser and default.

OptionConfig : {
    expected_value : ExpectedValue,
    plurality : Plurality,
    required : Bool,
    short : Str,
    long : Str,
    help : Str,
}

Metadata for options in our CLI building system.

ParameterConfigBaseParams : { name : Str, help : Str }

DefaultableParameterConfigBaseParams : { name : Str, help : Str, default : DefaultValue(a) }

ParameterConfigParams : {
    name : Str,
    help : Str,
    type : Str,
    parser : ValueParser(a),
}

Options for creating a parameter with a custom parser.

DefaultableParameterConfigParams : {
    name : Str,
    help : Str,
    type : Str,
    parser : ValueParser(a),
    default : DefaultValue(a),
}

Options for creating a parameter with a custom parser and default.

ParameterConfig : {
    name : Str,
    help : Str,
    type : Str,
    plurality : Plurality,
    required : Bool,
}

Metadata for parameters in our CLI building system.

CliConfigParams : {
    name : Str,
    authors : List(Str),
    version : Str,
    description : Str,
    text_style : TextStyle,
}

Options for bundling a CLI.

CliConfig : {
    name : Str,
    authors : List(Str),
    version : Str,
    description : Str,
    subcommands : SubcommandsConfig,
    options : List(OptionConfig),
    parameters : List(ParameterConfig),
}

Metadata for a root-level CLI.

SubcommandConfigParams : { name : Str, description : Str }

Options for bundling a subcommand.

SubcommandConfig : {
    description : Str,
    options : List(OptionConfig),
    parameters : List(ParameterConfig),
    subcommands : SubcommandsConfig,
}

Metadata for a subcommand.

SubcommandsConfig

:= [
    NoSubcommands,
    HasSubcommands(
        {
            commands : List((Str, SubcommandConfig)),
            required : Bool,
        },
    ),
]

Subcommands retain declaration order and duplicate names for validation.