Design of the `cli` module API ## Structure: The cli is organized as a set of *nodes*, which are ucode objects objects describing *entries*. Each *entry* can either implement a *command*, or select another *node*, optionally with *parameters*. Additionally, it contains helptext and full *parameter* descriptions, including everything needed for tab completion. The initial *node* on startup is `Root`, representing the main menu. ## Simple example: ### Code: ``` const Example = { hello: { help: "Example command", args: [ { name: "name", type: "string", min: 3, max: 16, required: true, } ], call: function(ctx, argv, named) { return ctx.ok("Hello, " + argv[0]); }, }, hello2: { help: "Example command (named_args version)", named_args: { name: { required: true, args: { type: "string", min: 3, max: 16, } } }, call: function(ctx, argv, named) { return ctx.ok("Hello, " + named.name); }, } }; const Root = { example: { help: "Example node", select_node: "Example", } }; model.add_nodes({ Root, Example }); ``` ### Example interaction: ``` root@OpenWrt:~# cli Welcome to the OpenWrt CLI. Press '?' for help on commands/arguments cli> example cli example> hello Error: Missing argument 1: name cli example> hello foo Hello, foo cli example> hello2 Error: Missing argument: name cli example> hello2 name foo2 Hello, foo2 cli example> ``` ## API documentation: Each module is placed in `/usr/share/ucode/cli/modules` on the root filesystem. When included by the cli code, the scope contains the `model` variable, which is the main cli API object. This variable is also present in the scope of the other callback functions described below. ### `model` methods: - `model.warn(msg)`: Pass a warning to the user (similar to the ucode `warn` function). - `model.exception(e)`: Print an exception with stack trace. - `model.add_module(path)`: Load a single module from `path` - `model.add_modules(path)`: Load multiple modules from the `path` wildcard pattern - `model.add_node(name, obj)`: Add a single node under the given name - `model.add_nodes(nodes)`: Add multiple nodes with taking `name` and `obj` from the `nodes` object. - `model.add_type(name, info)`: Add a data type with validation information, - `model.add_types(types)`: Add multiple data types, taking `name` and `info` from the `types` object. - `model.status_msg(msg)`: Print an asynchronous status message (should not be used from within a node `call` or `select` function). ### Properties of an `entry` inside a `node`: Each entry must have at least `help` and either `call` or `select_node` set. - `help`: Helptext describing the command - `call: function(ctx, argv, named)`: main command handler function of the entry. - `this`: pointer to the `entry` - `ctx`: call context object (see below) - `argv`: array of positional arguments after the command name - `named`: object of named parameters passed to the command - Return value: either `ctx.ok(msg)` for successfull calls, or the result of an error function (see below). - `select_node`: (string) name of the *node* that this entry points to. Mutually exclusive with implementing `call`. - `select: function(ctx, argv, named)`: function for selecting another node. - `this`: pointer to the *entry* - `ctx`: node context object (see below) - `argv`, `named`: see `call` - Return value: either `ctx.set(prompt, data)`, `true`, or the result of an error function (see below). - `args`: array of positional *arguments* (see *argument* property description) - `named_args`: object of named *parameters* (see *parameter* property description) - `available: function(ctx)`: function indicating if the entry can be used (affects tab completion and running commands) - `this`: pointer to the *entry* - `ctx`: node context object (see below) - Return value: `true` if available, `false` otherwise. - `validate: function (ctx, argv, named)`: validate command arguments - Function parameters: see `call` ### Named *parameter* properties: - `help`: Description of the named parameter's purpose - `args`: Either an array of *argument* objects, or an object with a single *argument* (see below). If not set, paramter will not take any arguments, and its value will be `true` if the parameter was specified on the command line. - `available: function(ctx, argv, named)`: function indicating if the named parameter can be used (affects tab completion and argument validation). May depend on *arguments*/*parameters* specified before this one. - `multiple` (bool): indicates if an argument may be specified multiple times. Turns the value in `named` into an array. - `required` (bool): Parameter must be specified for the command - `default`: default value for the parameter. - `allow_empty`: empty values are allowed and can be specified on the command line using `-param_name` instead of `param_name`. The value in the `named` object will be `null` in that case. ### Positional *argument* properties: - `name`: Short name of the *argument* - `help`: Longer description of the *argument* (used in helptext/completion) - `type`: data type name (see below) - `required` (bool): Value must not be empty - `value`: possible values for tab completion, one of: - array of objects with the following contents: - `name`: value string - `help`: help text for this value - `function(ctx, argv, named)` returning the above. - extra properties specific to the data type (see below) ### Default data types: - `int`: Integer value. The valid range can be specified using the `min` and `max` properties. - `string`: String value. The valid string length can be specified using the `min` and `max` properties. - `bool`: Boolean value. Converts `"1"` and `"0"` to `true` and `false` - `enum`: String value that must match one entry of the list provided via the `value` property. Case-insensitive match can be enabled using the `ignore_case` property. - `path`: Local filesystem path. When the `new_path` property is set, only match directories for a file to be created. - `host`: Host name or IP address - `macaddr`: MAC address - `ipv4`: IPv4 address - `ipv6`: IPv6 address - `cidr4`: IPv4 address with netmask size, e.g. 192.168.1.1/24. Allows `auto` as value if the `allow_auto` property is set. ### `call` context: Passed as `ctx` argument to entry `call` functions. - `ctx.data`: Object containing any data passed via `ctx.set()` from a `select` context. - `ctx.ok(msg)`: Indicates successful call, passes the message `msg` to the user. - `ctx.select(...args)`: After completion, switch to a different *node* by running the command chain provided as function argument (only entries with `.select_node` are supported). - `ctx.string(name, val)`: Passes a string to the caller as return value. - `ctx.list(name, val)`: Passes a list of values to the caller as return value. `val` must be an array. - `ctx.table(name, val)`: Passes a table as value to the caller. `val` can be an array `[ column_1, column_2 ]`, where each member of the outer array describes a row in the table. It can also be an object, where the property name is the first column value, and the value the second column value. - `ctx.multi_table(name, val)`: Passes multiple tables to the caller. Can be an array of `[ title, table ]`, or an object. - Error functions (see below) ### `select` context: - `ctx.data`: Object containing any data passed via parent `ctx.set` calls. - `ctx.set(prompt, data)`: Modify the prompt and `ctx.data` for the child context. The string given in `prompt` is appended to the existing prompt. The data given in the `data` object is merged with the previous `ctx.data` value. - Error functions (see below) ### Error functions: All error messages accept a format string in `msg`, with arguments added after it. - `ctx.invalid_argument(msg, ...args)`: Indicates that invalid arguments were provided. - `ctx.missing_argument(msg, ...args)`: Indicates that an expected argument was missing. - `ctx.command_failed(msg, ...args)`: Indicates that the command failed. - `ctx.not_found(msg, ...args)`: Indicates that a given entry was not found. - `ctx.unknown_error(msg, ...args)`: Indicates that the command failed for unknown or unspecified reasons. - `ctx.error(id, msg, ...args)`: Generic error message with `id` specifying a machine readable error type string. ## Editor API documentation The editor API provides a layer of abstraction above node entries/calls in order to make it easy to edit properties of an object based on an attribute list, as well as create/destroy/show object instances using a consistent user interface. ### Simple example: ``` import * as editor from "cli.object-editor"; let changed = false; let data = { things: { foo: { label_str: [ "bar" ], id: 31337, } }, }; const thing_editor = { change_cb: function(ctx) { changed = true; }, named_args: { label: { help: "Thing label", attribute: "label_str", multiple: true, args: { type: "string", min: 2, max: 16 }, }, id: { help: "Thing id", required: true, args: { type: "int", min: 1, }, }, }, }; const ExampleThing = editor.new(thing_editor); let Example = { dump: { help: "Dump current data", call: function(ctx, argv, named) { return ctx.json("Data", { changed, data }); }, } }; const example_editor = { change_cb: function(ctx) { changed = true; }, types: { thing: { node_name: "ExampleThing", node: ExampleThing, object: "things", }, }, }; editor.edit_create_destroy(example_editor, Example); const Root = { example: { help: "Example node", select_node: "Example", select: function(ctx, argv, named) { return ctx.set(null, { object_edit: data, }); } } }; model.add_nodes({ Root, Example, ExampleThing }); ``` ### Example interaction: ``` root@OpenWrt:~# cli Welcome to the OpenWrt CLI. Press '?' for help on commands/arguments cli> example cli example> dump Data: { "changed": false, "data": { "things": { "foo": { "label_str": [ "bar" ], "id": 31337 } } } } cli example> thing foo set id 1337 cli example> create thing bar id 168 label l1 label l2 Added thing 'bar' cli example> thing bar show Values: id: 168 label: l1, l2 cli example> thing bar remove label 1 cli example> thing bar show Values: id: 168 label: l2 cli example> dump Data: { "changed": true, "data": { "things": { "foo": { "label_str": [ "bar" ], "id": 1337 }, "bar": { "id": 168, "label_str": [ "l2" ] } } } } cli example> destroy thing foo Deleted thing 'foo' cli example> ``` ### API documentation Prelude: `import * as editor from "cli.object-editor";` #### Object editor: For editing an object, the following user commands are defined: - `set`: Changes property values - `show` Show all values If properties with `multiple: true` are defined, the following commands are also defined: - `add`: Add values to properties - `remove` Remove specific values from properties ##### Variant 1 (editor-only node): `const Node = editor.new(editor_data)` ##### Variant 2 (merge with existing entries): `let Node = {};` `editor.new(editor_data, Node);` The editor code assumes that the *node* that selects the editor node uses `ctx.set()` to set the `edit` field in `ctx.data` to the object being edited. #### `editor_data` properties: - `change_cb: function(ctx)`: Called whenever a property is changed by the user - `named_args`: Parameters for editing properties (based on *entry* `named_args`, see below) - `add`, `set`, `show`, `remove`: Object for overriding fields of the commands defined by the editor. Primarily used to override the helptext. #### Instance editor `named_args` entry properties: All *entry* `named_args` properties are supported, but the meaning is extended slightly: - `multiple`: Property array values can be added/removed - `default`: Default value when creating the object - `allow_empty`: Property can be deleted - `required`: Property is mandatory in the object. #### Object instance editor: For managing object instances, the following user commands are defined: - `create <...>`: Create a new instance. Also takes parameter values to be set on the object. - `destroy `: Delete an instance. - `list ` List all instances of a given type. The instance editor code assumes that the *node* that selects the editor node uses `ctx.set()` to set the `object_edit` field in `ctx.data` to the object being edited. ##### Variant 1 (editor-only node): `const Node = editor.edit_create_destroy(instance_data);` ##### Variant 2 (merge with existing entries): `let Node = {};` `editor.edit_create_destroy(instance_data, Node);` #### `instance_data` properties: - `change_cb: function(ctx)`: Called whenever an instance is added or deleted - `types`: Metadata about instances types (see below) #### `instance_data.types` object properties: - `node_name`: name of the *editor node* belonging to the object instance. - `node`: The *editor node* itself. - `object`: Name of the type specific container object inside the object pointed to by `ctx.data.object_edit`.