`clif`

High-level CLI framework - Cobra/Clap-style subcommands, typed long/short flags with defaults, positional arguments, auto-generated help text, version printing, pre-run hooks, confirm prompts, select menus, progress bars, Braille spinners, and aligned table output.

Load with: use clif

What this module does

clif lets you build well-structured command-line tools without manually parsing argv. Define a program with a name and description, add typed flags (string, int, float, bool), positional arguments, and subcommands. Call clru and the framework parses the real argv, dispatches to the correct subcommand, validates required flags and arguments, and invokes your handler with a typed context object.

-h/--help and -v/--version are handled automatically. Interactive prompts (clcf, clsl), progress bars (clpr), spinners (clsp), and aligned table output (cltb) round out the toolkit for rich terminal UIs.

Quick example

use clif

p = clne("mytool")
clds(p, "A sample CLI tool")
clvr(p, "1.2.0")

# Add flags
clfl(p, "output", "o", "out.txt", "Output file path", "str")
clbo(p, "verbose", "Enable verbose output")

# Add a positional argument
clar(p, "input", "Input file", tru)

# Add a subcommand
sub = clcm(p, "convert", \(ctx)
    prn("Converting " + ctx.ar.input + " to " + ctx.fl.output)
)

# Run (reads argv automatically)
clru(p, nil)

Functions

Program definition

clne(name)

Creates a new CLI program with version "0.0.1", empty flags, arguments, commands, and no run handler or pre-run hook.

clvr(prog, version)

Sets the version string on the program.

clds(prog, description)

Sets the description shown in help output.

Flags

clfl(prog, name, short, default, description, type)

Defines a typed flag. type is one of "str", "int", "num", "bool". short is the single-character short form (e.g. "o" for -o), or nil. Returns the updated program.

clbo(prog, name, description)

Convenience shorthand for a boolean flag (type "bool", default fls, no short form).

Arguments

clar(prog, name, description, required)

Defines a positional argument. If required is tru, clru will error if the argument is not supplied. Arguments are matched in the order they are defined.

Subcommands

clcm(prog, name, fn)

Defines a subcommand with a handler function. The handler receives the same context object as the root run handler. Returns the new subcommand object (which can have its own flags, arguments, and sub-subcommands).

clcm(prog, fn)

Sets the run handler for the program or subcommand directly (no new subcommand created).

Execution

clru(prog, argv)

Parses argv (or reads from hp_argv()/__sys_args() if nil) and runs the program. Flow:

If -h or --help is in argv → print help and exit 0.
If -v or --version → print version and exit 0.
If the first non-flag token matches a subcommand name → recurse into that subcommand.
Otherwise parse long flags (--name=value or --name value), short flags (-n value), and positional arguments.
Check required flags; error if missing.
Assign positional arguments to their names; error if a required argument is missing.
Call the pre-run hook (prog.hd) if set, then the run handler (prog.rn).

The handler receives {fl: {name: value, ...}, ar: {name: value, ...}, p: prog}.

clpa(type, value)

Parses a flag value string to the given type: "str", "int", "num", or "bool" ("true"/"yes"/actual boolean).

Help and hooks

clhp(prog)

Prints a formatted help page: program name and description, version, usage line with flags/args/commands, sorted flag list with defaults and descriptions, argument list, and subcommand list.

clhd(prog, fn)

Sets a pre-run hook function called before the main handler. Useful for setup, authentication checks, etc.

Interactive prompts

clcf(message)

Prints a [y/N] confirmation prompt. Returns tru if the user types y or yes (case-insensitive).

clsl(options, message)

Prints a numbered menu of options and prompts for a selection index. Returns the selected option string, or nil if the index is out of range.

Progress and spinners

clpr(message, current, max)

Prints an inline progress bar with percentage. Uses \r to overwrite the current line.

clprf()

Finalises the progress bar by printing a newline.

clsp(message)

Creates a Braille-dot spinner state object. Call its fn function repeatedly in a loop to animate it. Stop with clstp.

clstp(spinner)

Stops the spinner and replaces it with a ✓ message line.

Table output

cltb(headers, rows)

Prints an auto-sized table. headers is a list of column name strings. rows is a list of objects keyed by the header names. Column widths are auto-sized to the widest cell. Prints the header, a -+- separator line, and data rows.

Notes

The context passed to run handlers has ctx.fl for flag values, ctx.ar for argument values, and ctx.p for the program object.
Short flags must be a single character. Long flags support --name value and --name=value syntax.
Requires trl, txt, args, and host_run_ctx.