feat(lang): std.cli exit-code + --json contract helpers [F3.3]
Foundation milestone close — the minimal exit-code / --json contract `dist` relies on, in pure sx (no compiler change). - EX_OK (0) / EX_USAGE (64, sysexits.h) / EX_UNAVAILABLE (70) named constants in std.cli. - exit_ok() / exit_usage() terminators routing through the canonical process.exit(code: u8) — removes the hand-rolled cli_bail_exit `_exit` binding; the unsupported-platform path now uses proc.exit(EX_UNAVAILABLE). - --json read is parsed.json (already parsed by F3.2); documented as the detection point with a stdout-pure / stderr-human convention. - examples/0718-modules-cli-exit-json.sx exercises the contract: json true with --json / false without, EX_USAGE == 64, and a usage path that exits 64 via exit_usage() (expected .exit = 64). - readme.md gains a std.cli command-line-interface subsection.
This commit is contained in:
27
readme.md
27
readme.md
@@ -425,6 +425,33 @@ The standard library (`modules/std.sx`) provides:
|
||||
- **Math**: `sqrt`, `sin`, `cos`
|
||||
- **Introspection**: `type_of`, `type_name`, `field_count`, `field_name`, `field_value`, `size_of`
|
||||
|
||||
### Command-line interface (`modules/std/cli.sx`)
|
||||
|
||||
`std.cli` builds command-line front-ends over an explicit logical argv
|
||||
(`[]string`): `os_args(buf)` reads the real process argv, and
|
||||
`parse(args, commands, diag) -> !Parsed` does subcommand dispatch + `--flag`
|
||||
parsing. On top of that it defines the small **exit-code / `--json` contract**
|
||||
a CLI program (e.g. `dist`) relies on:
|
||||
|
||||
```sx
|
||||
#import "modules/std/cli.sx";
|
||||
|
||||
p, e := parse(args, cmds, @diag); // (Parsed, !CliError)
|
||||
if e == error.UnknownCommand {
|
||||
log.err("unknown command '{}'", diag.token); // human text -> stderr
|
||||
exit_usage(); // usage error -> exit 64
|
||||
}
|
||||
if p.json { /* emit ONLY machine output on stdout */ }
|
||||
```
|
||||
|
||||
- **Named exit codes** — `EX_OK` (0), `EX_USAGE` (64, the sysexits.h
|
||||
command-line-usage code), `EX_UNAVAILABLE` (70, unsupported platform).
|
||||
- **Terminators** — `exit_ok()` / `exit_usage()` end the process with the
|
||||
matching code; both route through the canonical `process.exit(code: u8)`.
|
||||
- **`--json` mode** — the reserved global `--json` flag surfaces as
|
||||
`parsed.json` (true iff `--json` is in the argv). Convention: in json mode
|
||||
stdout carries only the machine result; human diagnostics go to stderr.
|
||||
|
||||
## Cross-Compilation
|
||||
|
||||
```sh
|
||||
|
||||
Reference in New Issue
Block a user