IF Commons GitHub

logical/machine-args

Written to: 2 requirements: 2 proved, 0 partly, 0 failing, 0 with no test recorded. 0013-mcp-surface FR-001, 0013-mcp-surface FR-005

What a machine surface offers of a command and how it turns the arguments of a call into a command line (commons headless 0013-mcp-surface FR-001, FR-005 and 0014-rest-surface FR-001): the options a caller may give (the command's own, but not those that only a person may give, and --dry-run and --check where the command has them), the JSON Schema of each, and the argument vector that a call's arguments make. Shared by the tool server and the REST interface, so that the two take the same arguments in the same way. Pure.

An operand that starts with a dash is refused, so that an argument can never become a flag; a value option is written --name=value, so that a value that starts with a dash is still its value.

import { flagOf } from "./machine-args.ts";
flagOf("dryRun"); // "--dry-run"

Source: commons/headless/src/logical/machine-args.ts

3 of 14 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

logical.ArgSchematypeno test imports it
type ArgSchema =
  | { readonly type: "boolean"; readonly description: string }
  | { readonly type: "string"; readonly description: string }
  | { readonly type: "array"; readonly items: { readonly type: "string" }; readonly description: string };

The JSON Schema of one argument: the few forms the options of a command line need.

logical.flagOffunctionno test imports it
function flagOf(key: string): string

The camelCase key as an option is written (dryRun is --dry-run).

logical.offeredOptionsfunctionno test imports it
function offeredOptions(p: Placed): Readonly<Record<string, Option>>

The options of a command a client may give, by key: the command's own except those only a person may give, and dryRun and check where it has them.

logical.schemaOfOptionfunctionno test imports it
function schemaOfOption(o: Option): ArgSchema

The JSON Schema of one option.

logical.ArgErrortypeno test imports it
type ArgError =
  | { readonly kind: "not-an-object" }
  | { readonly kind: "unknown-argument"; readonly name: string }
  | { readonly kind: "wrong-type"; readonly name: string; readonly expected: "boolean" | "string" | "array of strings" }
  | { readonly kind: "missing-argument"; readonly name: string }
  | { readonly kind: "looks-like-an-option"; readonly name: string };

Why arguments are not a command line.

logical.argErrorMessagefunctionno test imports it
function argErrorMessage(e: ArgError): string

The one sentence of an argument error.

logical.argvOffunctionno test imports it
function argvOf(p: Placed, args: unknown): Result<readonly string[], ArgError>

The command line a call's arguments make: the words of the command, its options and operands; the operands are not options, whatever they hold.

ArgSchematypeno test imports it
type ArgSchema =
  | { readonly type: "boolean"; readonly description: string }
  | { readonly type: "string"; readonly description: string }
  | { readonly type: "array"; readonly items: { readonly type: "string" }; readonly description: string };

The JSON Schema of one argument: the few forms the options of a command line need.

flagOffunction
function flagOf(key: string): string

The camelCase key as an option is written (dryRun is --dry-run).

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

offeredOptionsfunctionno test imports it
function offeredOptions(p: Placed): Readonly<Record<string, Option>>

The options of a command a client may give, by key: the command's own except those only a person may give, and dryRun and check where it has them.

schemaOfOptionfunctionno test imports it
function schemaOfOption(o: Option): ArgSchema

The JSON Schema of one option.

ArgErrortypeno test imports it
type ArgError =
  | { readonly kind: "not-an-object" }
  | { readonly kind: "unknown-argument"; readonly name: string }
  | { readonly kind: "wrong-type"; readonly name: string; readonly expected: "boolean" | "string" | "array of strings" }
  | { readonly kind: "missing-argument"; readonly name: string }
  | { readonly kind: "looks-like-an-option"; readonly name: string };

Why arguments are not a command line.

argErrorMessagefunction
function argErrorMessage(e: ArgError): string

The one sentence of an argument error.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

argvOffunction
function argvOf(p: Placed, args: unknown): Result<readonly string[], ArgError>

The command line a call's arguments make: the words of the command, its options and operands; the operands are not options, whatever they hold.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.