velt/cli

API reference

Command-line argument parsing with Node util.parseArgs rules and a commander-style builder. parse takes the argument array, so a parser is easy to test; in a program, pass it args() from velt/process. For a walkthrough, read the guide.

import { ArgParser } from "velt/cli";

Exports

ArgParserA command-line parser declared with flag, option and positional (see the header).CliErrorA usage error: unknown option, missing or unexpected value, bad integer.ParsedArgsThe result of ArgParser.parse (constructed by it).FlagSpecSettings of a boolean flag.OptionSpecSettings of an option that takes a value.

class

ArgParser

#std/cli/arg_parser.vlt:50

Re-exported from velt/cli/arg_parser

A command-line parser declared with flag, option and positional (see the header).

constructor(program: string, description: string = "")

program is the name shown in help(); description is printed under the usage line.

flag(name: string, spec: FlagSpec = {}): ArgParser

Declares boolean flag --name (also --no-name).

option(name: string, spec: OptionSpec = {}): ArgParser

Declares option --name <value>.

positional(name: string, help: string = ""): ArgParser

Names the next positional argument (for help() and ParsedArgs.get(name)); positionals are optional and extra ones are allowed — check positionals.length yourself.

parse(args: string[]): ParsedArgs

Parses args (without the program path). Throws CliError on unknown options, missing option values and values given to flags.

help(): string

Usage text: the usage line, description, arguments and options with help and defaults.

class

CliError

#std/cli/errors.vlt:4

Re-exported from velt/cli/errors

class CliError extends Error

A usage error: unknown option, missing or unexpected value, bad integer.

class

ParsedArgs

#std/cli/parsed_args.vlt:6

Re-exported from velt/cli/parsed_args

The result of ArgParser.parse (constructed by it).

Returned byArgParser.parse

positionals: string[]

Arguments that are not options, in order (including those after --).

constructor(positionals: string[], flagNames: string[], flagValues: bool[], values: Map<string, string[]>, defaults: Map<string, string>, positionalNames: string[])

No doc comment yet

flag(name: string): bool

Whether flag name was given (the last --name / --no-name wins).

get(name: string): string | null

The last value of option name, else its default, else the declared positional of that name, else null.

getOr(name: string, fallback: string): string

get(name), or fallback when it is null.

getAll(name: string): string[]

Every value given for option name, in order (the default is not included).

has(name: string): bool

Whether option or flag name was given explicitly.

getInt(name: string): i64 | null

get(name) as an integer (decimal digits with an optional sign), or null when absent; throws CliError if the value is not an integer.

struct

FlagSpec

#std/cli/flag_spec.vlt:4

Re-exported from velt/cli/flag_spec

Settings of a boolean flag.

Parameter ofArgParser.flag

Field	Type	Description
short?	`string`	One-character alias (`v` for `-v`).
help?	`string`	—

struct

OptionSpec

#std/cli/option_spec.vlt:4

Re-exported from velt/cli/option_spec

Settings of an option that takes a value.

Parameter ofArgParser.option

Field	Type	Description
short?	`string`	One-character alias (`o` for `-o`).
default?	`string`	Value when the option is absent.
help?	`string`	—
valueName?	`string`	Placeholder shown in `help()` (default `value`).