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.