Skip to content
nixptPublic

About

CLI argument parser and help renderer for Crush programs, written in Crush

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

facet

CLI argument parser and help renderer for Crush programs — like Python's argparse/click, but in the Crush language, for the Crush language, driven by one declarative spec map.

// one spec map drives parsing, defaults, usage, --help, subcommands
let spec = { name: "greet", usage: "greet [options] [files...]", flags: [ { short: "-v", long: "--verbose", help: "say more" } ], options: [ { long: "--level", short: "-l", type: "int", default: 1, choices: [1, 2, 3], help: "verbosity" }, { long: "--name", type: "str", required: true, help: "who" } ], positionals: [ { name: "files", repeat: true, help: "extra files" } ] }

let args = facet_parse(spec)     // bad input ⇒ error + usage + exit(2)
io.print("Hello, " + args.name + " (level " + conv.to_str(args.level) + ")")

That yields --help, -vh-style bundling, --level=2/-l2/-l 2, positional collection, typed defaults and column-aligned help — all from the spec. Runnable examples in demo/.

Consuming facet

facet is one definitions-only file, so Crush's compile-time import (CRUSH-110) works on it. Use the brace form, which binds the names bare:

import facet { facet_run, facet_fail }   // only public names import; __facet_* do not

1. import + -L (scripts and projects):

crush-run run -L <facet dir> my_program.crush -- --help
# or: CRUSH_PATH=<facet dir> crush-run run my_program.crush -- --help

(Plain import facet also works, but namespaces the functions: call facet.facet_parse(spec); bare calls then fail with Undefined function.)

2. crush-pkg path dependency (see examples/consumer/):

[[dependencies]]
name = "facet"
path = "../facet"
crush-pkg run -- --help       # keep `import facet { ... }` in main.crush

3. Concatenation (fallback for one-off scripts; the program must NOT have an import facet line, or the names collide):

cat facet.crush my_program.crush > /tmp/my_program.crush
crush-run run /tmp/my_program.crush -- --help

Env fallback needs the facet_env.crush companion. It imports facet itself, so it is import-only: do not concatenate it with facet.crush (the names collide). In your program:

import facet { facet_parse }
import facet_env { facet_env_apply }

Grant --env BEFORE the --, even for --help (the capability check covers the whole program): crush-run run -L . --env prog.crush -- --name Ada.

A whole CLI in one call

fn main() {
    // keep each map literal on one line until crush-ast CRUSH-345 lands
    let add = { name: "add", help: "add an item", options: [ { short: "-p", long: "--priority", type: "int", default: 1, choices: [1, 2, 3], help: "1 = low, 3 = urgent" } ], positionals: [ { name: "text", required: true, help: "what to do" } ] }
    let list = { name: "list", help: "show items", flags: [ { short: "-a", long: "--all", help: "include done items" } ] }
    let spec = { name: "todo", version: "0.2.0", about: "A tiny todo list.", subcommands: [add, list] }

    facet_run(spec, { add: |args| => cmd_add(spec, args), list: |args| => cmd_list(args) })
}

That gives todo --help, todo --version, todo add --help (the subcommand's own options), typed and validated arguments, and exit status 0 / 2 everywhere, with no other code. Full program: demo/todo.crush.

API

function behavior
facet_run(spec, handlers) facet_parse + facet_dispatch: the whole CLI in one call
facet_parse(spec) parse sys.args(). Bad input ⇒ facet: <name>: <error> + usage (the subcommand's, if the error is in one) + exit(2). -h/--help ⇒ full help (or the subcommand's after it) + exit(0). --version/-V ⇒ name version + exit(0) when the spec has version. A spec with problems ⇒ facet: spec error: … + exit(70)
facet_dispatch(spec, handlers, args) call handlers[args.subcommand] (or handlers.main without subcommands) with args, return its result; no handler ⇒ exit(70)
facet_fail(spec, message) your own argument check, reported like facet's: message + usage + exit(2)
facet_resolve(spec, argv) what argv asks for, without printing or exiting: { action: "help" | "version" | "error" | "run", text?, args?, spec? }
facet_parse_debug(spec, argv) the parse alone over an argv array: { ok, data, error } (embedders + tests)
facet_check_spec(spec) problems in a spec as lines ([] when fine): unknown keys such as requried, entries without long/short, a positional without name, an unknown option type
facet_usage(spec) / facet_help(spec) the one-line usage / the full help text
facet_version_text(spec) name version ("" without version)

Handlers are closures or function references stored in a map: { add: |args| => do_add(args) } or { main: run }. (Call them through facet_run/facet_dispatch: handlers.add(args) directly hits crush-ast #362.)

Result map keys come from long (--build-dir ⇒ build_dir) unless the entry sets name. Declared-but-unset options/positionals are present as null; flags are false. _provided lists the keys that actually came from argv (used by env fallback; handy for scripts).

Spec entries

Count flags: { short: "-v", long: "--verbose", count: true } yields an int (0 when absent; -v 1, -vvv 3, -v -v 2, -vqv counts v twice). count is allowed on flags only and cannot be combined with type or default; --verbose=3 is a parse error. Help marks it "(repeatable)". It lands in _provided only when it appears in argv. required: true on a count flag means at least one occurrence (help: "(repeatable, required)").

spec:        { name, usage?, version?, about?, epilog?,
               flags?, options?, positionals?, subcommands?, groups? }
flags:       { short?, long?, name?, default?, required?, count?, help? } // boolean; count: true => int
options:     { short?, long?, name?, type?, default?, required?,        // type: str|int|float|bool
               choices?, env?, help? }
positionals: { name, type?, default?, required?, repeat?, help? }
subcommands: { name, usage?, help?, about?, epilog?, flags?, options?, positionals?, groups? }
groups:      [ { exclusive: [...] } | { together: [...] } | { one_of: [...] } ]

Option groups (groups, top level or on a subcommand): each group object has exactly one kind and lists 2+ members, a flag's or option's long name ("--json"), or its short name ("-j") when it has no long. Members must be declared at the same level as the group. Violations are parse errors (exit 2):

  • exclusive: at most one given: --json and --table are mutually exclusive (the first two given, in declared order).
  • together: if any is given, all must be: --user requires --pass (first given, first missing).
  • one_of: at least one given: one of --a, --b is required. Exactly-one is one_of plus exclusive over the same members.

"Given" means it came from argv (it is in _provided): defaults do not count, and facet_env values (filled after the parse) do not count either. Group checks run after the required and choices checks, in declared group order. facet_check_spec rejects unknown members, groups with fewer than 2 members and group objects without exactly one kind (exit 70). --help does not list groups yet.

Semantics: -- ends option parsing; -abc bundles boolean shorts; -lv5 = -l v5; unknown option / missing value / bad type / choices miss / missing required ⇒ exit 2. Options with env: need the facet_env.crush companion (import-only; facet_env_apply(spec, args), precedence argv > env > default, requires --env).

Engine support

  • PortableVm / scheduler (CVM1): fully verified — 77-check self test plus demo runs (crush-run).
  • FastVM / JIT: same shared capability implementations; the differential harness cannot yet wire capabilities for FastVM (it abstains), so untested.
  • AOT backends: blocked upstream, not by facet — the Rust AOT lowerer currently rejects sys.args, sys.exit and conv.*; the C AOT backend rejects dynamic-text caps and cannot compile try/catch or env.get at all (CRUSH-xps-13). facet.crush deliberately contains no try/catch and no env.get so that consumers are not gated further; env fallback lives in the separate companion.

Tests

./test/run.sh

Runs each demo's --help through the import form, then concatenates facet.crush + facet_test.crush for the self test (it needs the internals; needs crush-run on PATH). Design notes: docs/plans/2026-10-31-facet-design.md. Requires crush-ast ≥ 0.9.0.

About

CLI argument parser and help renderer for Crush programs, written in Crush

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages