openwrt-cghmn-mt300n/package/utils/cli/docs/MODULE-API.md

 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 <type> <name> <...>`: Create a new instance. Also takes parameter values to be set on the object.
- `destroy <type> <name>`: Delete an instance.
- `list <type>` 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`.