`args`

CLI argument parsing - flags, short options, subcommands, required args, help text, and interactive prompts.

Load with: use args

What this module does

args parses command-line arguments. Create a parser with argne, define your flags with argad, mark required ones with argrq, then call argpr with the raw argument list. You get back a result object with your parsed flags, positional arguments, and detected subcommand.

It handles --long-flag value, --long-flag=value, short flags (-f value), flag type coercion (str, int, num, bool), subcommand dispatch, and auto-generated help and version output.

Quick example

use args

ar = argne("My CLI tool")
ar = argad(ar, "output", "o", "str", "out.txt", "Output file path")
ar = argad(ar, "verbose", "v", "bool", fls, "Enable verbose output")
ar = argrq(ar, "output")

result = argpr(ar, os.argv())
prn(result.rs.output)   # the --output value
prn(result.ar)          # positional arguments
prn(result.cm)          # subcommand if any

Functions

Parser setup

argne(de)

Creates a new argument parser with a description string. Returns a parser object with empty options, args, and commands.

argad(ar, nm, sh, tp, df, ds)

Adds a flag to the parser. nm is the long name (e.g. "output"), sh is the short name (e.g. "o") or nil, tp is the type ("str", "int", "num", or "bool"), df is the default value, ds is the description. Overloaded: the second form adds a positional argument.

argrq(ar, nm)

Marks the flag named nm as required. Parsing will error if it's missing.

argdc(ar, nm, fn, ds)

Registers a subcommand with name nm, handler function fn, and description ds.

argve(ar, v)

Enables version flag support (-v / --version).

arghl(ar, h)

Sets the help text shown below the usage line.

Parsing

argpr(ar, av)

Parses the argument list av. Handles --long, --long=val, -s, -s val, -- (end of flags), subcommands, and positional args. Errors if a required flag is missing. Returns {rs, ar, cm} - rs is the parsed flags object, ar is positional args, cm is the detected subcommand.

argst(ar, rs, nm, vl)

Internal: sets a long-name flag value in the result object, coercing the value to the flag's declared type.

args0(ar, rs, sh, vl)

Internal: sets a short-name flag value in the result object.

argcv(tp, vl)

Coerces a raw string value to the given type. "str" → string, "int" → integer, "num" → float, "bool" → boolean (accepts "true"/"yes"/"1" and "false"/"no"/"0").

Help and version output

arghp(ar, nm)

Prints usage, help text, all defined flags with their short forms and defaults, and all registered subcommands to stdout.

argvr(nm, vs)

Prints "{nm} version {vs}" to stdout.

argau(ar, av, nm, vs)

Auto-handles -h/--help and -v/--version flags - prints the appropriate output and exits with code 0 if detected.

Interactive prompts

argpr(t, dv)

Prints a prompt string and reads a line from stdin. Returns the default value dv if the input is empty. Note: overloaded with the parse function above.

argcf(t)

Prints a [y/N] confirmation prompt and reads from stdin. Returns tru if the user enters y or yes, fls otherwise.

argps(t)

Prints a prompt and reads a line from stdin. Returns the raw input string (no default).

Notes

argpr is overloaded: with two args where the first is a parser it parses argv; with two args where the first is a string it prompts interactively.
-- stops flag parsing - everything after it is treated as a positional argument.
Short flags can be stacked (e.g. -abc is parsed as -a -b -c), with the last one picking up a value if the next token doesn't start with -.