Command System
You can add a command by shell.add. You can call a command by shell.input.
key.setViewKey(':', function () { shell.input(); }, "Command System");
key.setViewKey('t', function () { shell.input("tabopen "); }, "Open tab");
key.setViewKey('o', function () { shell.input("open "); }, "Open");
key.setViewKey('s', function () { shell.input("tabopen google "); }, "Google word");
See, this page for examples.
shell.add(names, description, callback, extra, replace);
- names(Array)
- An array of strings of command names.
- description(String)
- A short description of the command.
- callback(Function)
- A function object to be called.
- additional(Object)
- An object that contains completion and/or arguments to pass (optional).
- replace(Boolean)
- Replace the command name if it already exists (optional).
Details are described below.
You can execute this function by the three commands: helloword, hello, and hw by the following setting.
shell.add(["hello[world]","hw"], "print hello world",
function () {
window.alert("Hello World");
}
);
The latter part of the command name, which is enclosed by [], is optional, and it will be expanded as helloword, and hello.
Names such as [“[hello]world”] and [“hello[worl]d”] are invalid.
Description of the command. It will be used in completing the command name. It is better to write as M({ja: “説明”, en: "Description"}) in a plugin.
A function that will be executed when a user input the command and hit Enter. This function takes the two argument.
- args(Array)
- extra(Object)
Details of the arguments are described below.
The ‘args’ argument takes the arguments passed by a user. Note that the string that a user input will be parsed in space-delimited form, and will be contained as an array in args.
If you want to pass the argument as a string, you have to use extra.left .
The extra object takes these values.
- left
- A string located in the left side of the cursor when a user hit Enter.
- whole
- The whole string in the prompt when a user hit Enter (except the command name).
- bang
- A boolean value that the command is called with ! or not.
- count
- Prefix arguments
It is better to use extra.left when literal : 0 is set in the ‘additional’ argument.
The ‘additional’ argument have these properties. Detailed behavior can be decided in these properties.
- completer
- A function that returns completion result in completing a tab.
- options
- An array that is used in parsing the command arguments.
- argCount
- A string that defines the number of the command arguments.
- bang
- Set it true when you allow ! like command!.
- literal
- Set it 0 if you want the command not to be parsed, to get the argument as a string, or to implement a completion system by yourself.
Details are described below.
Generate completion candidates by ‘completer’ in inputting the command argument. It is hard to write a completion system from scratch, so it is better to use the default completer.
These are examples of completer. Note that the collection is an array which contains completion candidates (like [“hoge”, “huga”, “hehe”]),
and the string that a user inputs is denoted as ‘query’.
You should also be careful to replace extra.query to extra.left when literal : 0 is set (In that case, extra.query is an empty string).
This completer compares the query and each elements in the collection from the first element, and returns matched elements.
function (args, extra) {
return completer.matcher.header(collection)(extra.query || "");
}
This completer returns elements that contains the query as a substring.
function (args, extra) {
return completer.matcher.substring(collection)(extra.query || "");
}
When XUL/Migemo is installed, this completer compares the query and each elements by the Migemo matching, and returns matched elements.
function (args, extra) {
return completer.matcher.migemo(collection)(extra.query || "");
}
When XUL/Migemo is not installed, completer.matcher.substring is used alternatively.
This completer throws the query to a search engine, get suggested candidates, and returns them.
function (args, extra) {
let engines = [util.suggest.ss.getEngineByName("Google")];
return completer.fetch.suggest(engines, true)(extra.query || "");
}
An array like the below. Each line corresponds to one option.
[ [[option's name], option's type, validator or null, option's completion candidates], [[option's name], option's type, validator or null, option's completion candidates] ]
You have to set an option’s name as the array that contains the option’s names. ex. [“-foo”, “-f”].
These values are available as an option’s type.
| shell.option.ANY | Anything OK. When the option is a string, the string is the option. When the option has no value, it is null. |
| shell.option.NOARG | The option’s value is expected not to be set. The value is always null even the option is treated as parsed. |
| shell.option.BOOL | The option’s value is expected to be given true or false, so it should be boolean. |
| shell.option.STRING | The option’s value is expected to be a string. |
| shell.option.INT | The option’s value is expected to be an integer. (A floating-point number is ignored.) |
| shell.option.FLOAT | The option’s value is expected to be an floating-point number (A floating-point number is permitted as OPTION_INT discards) |
| shell.option.LIST | The option’s value is expected to be a comma-separated list (DO NOT include spaces like ", "). The value is an array. |
The validator is a function that takes a value in inputting an option, and returns a boolean value by judging the value is valid or not.
In usual cases, it is enough to set it null.
You have to set an array like [“value1”, “value2”, “value3”] as the completion candidate of an option.
These are examples of options.
[
[["-fullscreen", "-f"], shell.option.BOOL, null, ["true", "false"]],
[["-language"], shell.option.STRING, null, ["perl", "ruby"]],
[["-speed"], shell.option.INT],
[["-acceleration"], shell.option.FLOAT],
[["-accessories"], shell.option.LIST, null, ["foo", "bar"]],
[["-other"], shell.option.ANY]
];
The number of the arguments that the command takes. Note that options are not counted as arguments.
| “0” | No argument |
| “1” | Exactly one argument |
| “2” | Exactly two arguments |
| “n” | Exactly n arguments |
| “+” | More than or equal to one argument |
| “*” | More than or equal to zero argument |
| “?” | Zero or one argument |
A boolean value to decide whether replace the existing command or not. In usual cases, you do not have to consider.