#args API reference

A declarative command-line argument parser, at the common surface of Python's argparse plus the features an argparse user misses immediately: typed flags (long + short), defaults, required args, choices, count / append actions, positionals with nargs, subcommands, and --version. It is the structured layer over os.ARGS (os.hasFlag / os.flag are primitive lookups). Pure Jennifer over strings + convert + lists + maps, so it runs on both binaries.

Build a value-semantic Parser with the copy-returning builder pattern (args.parser then args.flag / args.intFlag / args.positional / ...), then args.parse($p, os.ARGS) -> a Result. Read values back with the typed accessors (args.asString / asInt / asFloat / asBool / asList / args.count). An unknown flag, a missing required arg, a bad-type value, or a choices violation throws a catchable Error{kind: "args"}; -h / --help (and --version) set the result's done flag with helpText to print, rather than exiting the process, so it composes with try / catch.

Import with import "args.j" as args;. See the args guide for prose and examples.

#Functions

#args.asBool(r as Result, name as string)

The bool value of a flag (true when the stored value is "true").

Parameters

• r {Result} - the parse result
• name {string} - the flag name

Returns {bool} - the value

#args.asFloat(r as Result, name as string)

The float value of an argument.

Parameters

• r {Result} - the parse result
• name {string} - the argument name

Returns {float} - the value (0.0 if unset)

#args.asInt(r as Result, name as string)

The int value of an argument (parsed from its stored string).

Parameters

• r {Result} - the parse result
• name {string} - the argument name

Returns {int} - the value (0 if unset)

#args.asList(r as Result, name as string)

The list value of an append flag or variadic positional.

Parameters

• r {Result} - the parse result
• name {string} - the argument name

Returns {list of string} - the collected values ([] if none)

#args.asString(r as Result, name as string)

The string value of an argument (its provided value or default; "" if unset).

Parameters

• r {Result} - the parse result
• name {string} - the argument name

Returns {string} - the value

#args.boolFlag(p as Parser, long as string, short as string, help as string)

Add a boolean flag (presence sets it true; the argparse store_true action).

Parameters

• p {Parser} - the parser
• long {string} - the long name
• short {string} - the short name ("" for none)
• help {string} - the help text

Returns {Parser} - the updated parser

#args.choices(p as Parser, allowed as list of string)

Constrain the most-recently-added argument to a set of allowed values.

Parameters

• p {Parser} - the parser
• allowed {list of string} - the permitted values

Returns {Parser} - the updated parser

Throws

• {Error} - kind "args" if no argument has been added yet

#args.command(p as Parser, name as string, help as string, sub as Parser)

Add a subcommand with its own parser (argparse subparsers).

Parameters

• p {Parser} - the parent parser
• name {string} - the subcommand word
• help {string} - the subcommand's one-line help
• sub {Parser} - the subcommand's own parser

Returns {Parser} - the updated parser

#args.count(r as Result, name as string)

The tally of a count flag.

Parameters

• r {Result} - the parse result
• name {string} - the flag name

Returns {int} - the number of occurrences (0 if none)

#args.countFlag(p as Parser, long as string, short as string, help as string)

Add a repeatable counting flag: each occurrence increments a tally (-vvv -> 3), the argparse count action. Read with args.count.

Parameters

• p {Parser} - the parser
• long {string} - the long name
• short {string} - the short name ("" for none)
• help {string} - the help text

Returns {Parser} - the updated parser

#args.dispatch(r as Result, handlers as map of string to func)

Dispatch the parsed subcommand to its handler. handlers maps a subcommand name to a func value func(r as Result); the handler for r.command is called with the whole Result (so it reads its own args with args.asString / asInt / ...), and its return value is passed back - so a handler may return an exit code. A Result with done set (a handled --help / --version) dispatches nothing and returns null; a caller usually checks r.done and prints r.helpText before calling this. A missing handler for the selected subcommand, or a selection of none, is a catchable error.

The handlers are ordinary func values, not names - a func value called here runs in the entry program's own context, so it resolves its own imports.

Parameters

• r {Result} - the parse result
• handlers {map of string to func} - subcommand name -> its handler

Throws

• {Error} - kind "args" when no subcommand was selected or none matches

#args.flag(p as Parser, long as string, short as string, deflt as string, help as string)

Add a string-valued optional flag (--long / -short), with a default.

Parameters

• p {Parser} - the parser
• long {string} - the long name (used without the leading "--")
• short {string} - the single-char short name ("" for none)
• deflt {string} - the default when the flag is absent
• help {string} - the flag's help text

Returns {Parser} - the updated parser

#args.floatFlag(p as Parser, long as string, short as string, deflt as float, help as string)

Add a float-valued optional flag.

Parameters

• p {Parser} - the parser
• long {string} - the long name
• short {string} - the short name ("" for none)
• deflt {float} - the default value
• help {string} - the help text

Returns {Parser} - the updated parser

#args.has(r as Result, name as string)

Whether an argument was actually supplied on the command line (as opposed to taking its default).

Parameters

• r {Result} - the parse result
• name {string} - the argument name

Returns {bool} - true if supplied

#args.intFlag(p as Parser, long as string, short as string, deflt as int, help as string)

Add an int-valued optional flag.

Parameters

• p {Parser} - the parser
• long {string} - the long name
• short {string} - the short name ("" for none)
• deflt {int} - the default value
• help {string} - the help text

Returns {Parser} - the updated parser

#args.listFlag(p as Parser, long as string, short as string, help as string)

Add a repeatable value flag: each occurrence appends to a list (the argparse append action). Read with args.asList.

Parameters

• p {Parser} - the parser
• long {string} - the long name
• short {string} - the short name ("" for none)
• help {string} - the help text

Returns {Parser} - the updated parser

#args.parse(p as Parser, argv as list of string)

Parse argv (the full os.ARGS, whose first element is the program name and is skipped) against the parser.

Parameters

• p {Parser} - the specification
• argv {list of string} - the argument vector (pass os.ARGS)

Returns {Result} - the parsed values; check .done for --help / --version

Throws

• {Error} - kind "args" on an unknown flag, missing required arg, bad type, or bad choice

#args.parser(prog as string, help as string)

Start a parser with a program name and one-line description.

Parameters

• prog {string} - the program name (shown in usage)
• help {string} - the one-line description

Returns {Parser} - an empty parser

#args.positional(p as Parser, name as string, help as string)

Add a single required positional argument.

Parameters

• p {Parser} - the parser
• name {string} - the positional's name (its result key)
• help {string} - the help text

Returns {Parser} - the updated parser

#args.positionalList(p as Parser, name as string, help as string)

Add a variadic positional collecting zero or more values into a list (nargs "*"). Read with args.asList.

Parameters

• p {Parser} - the parser
• name {string} - the positional's name
• help {string} - the help text

Returns {Parser} - the updated parser

#args.positionalList1(p as Parser, name as string, help as string)

Add a variadic positional requiring one or more values (nargs "+"). Read with args.asList.

Parameters

• p {Parser} - the parser
• name {string} - the positional's name
• help {string} - the help text

Returns {Parser} - the updated parser

#args.positionalN(p as Parser, name as string, n as int, help as string)

Add a positional taking exactly n values into a list (nargs N).

Parameters

• p {Parser} - the parser
• name {string} - the positional's name
• n {int} - the exact number of values
• help {string} - the help text

Returns {Parser} - the updated parser

#args.positionalOpt(p as Parser, name as string, deflt as string, help as string)

Add an optional positional (nargs "?", 0 or 1) with a default.

Parameters

• p {Parser} - the parser
• name {string} - the positional's name
• deflt {string} - the default when absent
• help {string} - the help text

Returns {Parser} - the updated parser

#args.required(p as Parser)

Mark the most-recently-added argument as required.

Parameters

• p {Parser} - the parser

Returns {Parser} - the updated parser

Throws

• {Error} - kind "args" if no argument has been added yet

#args.usage(p as Parser)

The generated usage / help text for a parser (what --help prints).

Parameters

• p {Parser} - the parser

Returns {string} - the multi-line help text

#args.version(p as Parser, ver as string)

Enable a --version action printing ver.

Parameters

• p {Parser} - the parser
• ver {string} - the version string

Returns {Parser} - the updated parser

#Structs

#args.Arg

One argument definition (a flag or a positional). Built by the flag / positional family; not usually constructed directly.

#args.Command

A subcommand: a name plus its own Parser (its own flags and positionals).

#args.Parser

A command-line specification: the program name, description, arguments, and any subcommands. Value-semantic - every builder returns an updated copy.

#args.Result

The outcome of a parse. Read it with the typed accessors rather than poking the maps directly. When done is true the parser handled -h/--help/--version: print helpText and stop.