`clp`

Minimal plugin CLI command dispatcher - register command thunks by name, dispatch the first argv token to its handler, check command presence, and safely try execution without crashing the host.

Load with: use clp

What this module does

clp is a lightweight command-dispatch table intended for plugin systems and tool hosts where you want to register named commands as functions and then dispatch incoming argv arrays to them. Unlike clif, it has no flag parsing, help generation, or type coercion - it simply maps command names to handler functions and calls the right one.

Each handler receives (args, gl) where args is the remaining argv after the command name and gl is an arbitrary global context object supplied by the caller.

Quick example

use clp

p = clpne()
p = clpre(p, "greet", \(args, gl)
    prn("Hello, " + args[0])
)
p = clpre(p, "bye", \(args, gl)
    prn("Goodbye!")
)

# Dispatch from argv
clpdi(p, ["greet", "world"], nil)  # prints "Hello, world"

# Check if command exists
prn(clpha(p, "greet"))  # tru
prn(clpha(p, "missing")) # fls

# List all registered commands
prn(clpcm(p))  # ["greet", "bye"]

# Safe execution (returns try-result)
r = clptr(p, "greet", ["Alice"], nil)

Functions

Registry

clpne()

Creates an empty command plugin registry (an empty object).

clpre(registry, cmd, fn)

Registers a command handler. cmd must be a string, fn must be a function. Errors via eru.bang on bad types. Returns the updated registry.

clpha(registry, cmd)

Returns tru if the registry contains a handler for cmd.

clpcm(registry)

Returns a list of all registered command names.

Dispatch

clpru(registry, cmd, args, gl)

Calls the handler registered for cmd, passing (args, gl). Errors with "clp: ?{cmd}" if the command is not registered.

clpdi(registry, argv, gl)

Dispatches from an argv list. Takes the first element as the command name and the rest as args, then calls clpru. Errors if the registry or argv is invalid.

clptr(registry, cmd, args, gl)

Wraps clpru in a try and returns the result object {val, err}. Use this when you want to handle unknown commands or handler errors without crashing.

Notes

For richer CLI tooling with flags, help, and subcommands, use clif.
Requires trl, txt, and eru.