Command System (Japanese)
コマンドの追加には shell.add を用いる. 追加したコマンドは 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");
使用例は このページなどを参照されたい.
shell.add(names, description, callback, extra, replace);
- names(Array)
- コマンド名となる文字列の配列
- description(String)
- コマンドの簡易説明
- callback(Function)
- 実行される function オブジェクト
- additional(Object)
- 補完機能やコマンド引数などを格納するオブジェクト (省略可能)
- replace(Boolean)
- 既に存在するコマンドの場合、置き換えるか否か (省略可能)
以下, 各引数の詳細.
以下の様なコマンドを登録すると helloworld, hello, hw の 3 つのコマンド名で実行可能になる.
shell.add(["hello[world]","hw"], "print hello world",
function () {
window.alert("Hello World");
}
);
コマンド名となる文字列の後部を[]で囲むと省略可能とされて helloworld, hello の 2 つに展開される. [“[hello]world”] や [“hello[worl]d”] のようなものは無効.
概要を説明する文. コマンド補完時に使用される. プラグインから使う場合は M({ja: “説明”, en: "Description"}) のようにすると良い.
ユーザがコマンドを入力し Enter を押したときに実行される関数. この関数には以下に示す二つの引数が渡される.
- args(Array)
- extra(Object)
以下に, それぞれの詳細を記す.
args には, ユーザの入力したコマンド引数が入る. このとき, ユーザの入力した文字列がスペース区切りでパースされ, args に配列形式で格納されることに注意. 単なる文字列として受け取りたい場合は後述する extra.left を用いる.
extra オブジェクトには, 以下のような値が入る.
- left
- ユーザが Enter を押した時点での, カーソル左にある文字列 (コマンド名は消去済み)
- whole
- ユーザが Enter を押した時点での, プロンプト上の文字列 (コマンド名は消去済み)
- bang
- コマンドに ! が付いていたかどうかの真偽値
- count
- 前置引数
additional で literal : 0 と指定していた場合は, extra.left を用いると良い.
additional には, 以下のようなプロパティを持たせることができる. 細かなコマンドの挙動はここで指定するといって良い.
- completer
- タブ補完時に実行され, 補完値を返す function.
- options
- コマンド引数をパースする際に用いられる配列
- argCount
- コマンド引数の数を定義する文字列
- bang
- command! といった ! を許可する場合は true を指定する
- literal
- 特にコマンドをパースして欲しくない場合, 単なる文字列を受け取りたい場合, 自分で補完システムを全実装したい場合などは, ここに 0 を指定する
以下に, 各プロパティの詳細を記す.
この completer を使い, コマンドの引数入力時に用いられる補完候補を生成する. 一から書くのは大変なので, 元々用意された completer の力を借りるのが良いだろう.
以下にいくつか組み込み completer の使用例を示す. なお, collection は補完候補が格納された配列 ([“hoge”, “huga”, “hehe”] のようなもの) とする. また, ユーザが現在入力している文字列をクエリと表記する.
なお, literal : 0 とした場合は extra.query の部分を extra.left へ置き換える必要があることに注意されたい. (この場合 extra.query には空文字列が入る)
この completer は, クエリと collection 内の各要素を先頭から比較し, マッチしたものを返す.
function (args, extra) {
return completer.matcher.header(collection)(extra.query || "");
}
この completer は, collection からクエリを部分文字列として含む要素を取り出し, 返却する.
function (args, extra) {
return completer.matcher.substring(collection)(extra.query || "");
}
XUL/Migemo がインストールされている場合, クエリを用いて Migemo マッチングを collection 内各要素に対して行い, マッチしたものを返す.
function (args, extra) {
return completer.matcher.migemo(collection)(extra.query || "");
}
XUL/Migemo がインストールされていない場合は completer.matcher.substring が代わりに用いられる.
現在のクエリを検索エンジンのサジェスト機能へ投げ, 返ってきた結果を補完候補として用いる.
function (args, extra) {
let engines = [util.suggest.ss.getEngineByName("Google")];
return completer.fetch.suggest(engines, true)(extra.query || "");
}
以下のような配列を指定する. 各行が一つのオプションに対応する.
[ [[オプション名], オプションタイプ, バリデータ or null, オプションの補完候補], [[オプション名], オプションタイプ, バリデータ or null, オプションの補完候補] ]
オプション名には, オプションの名前が格納された配列を指定する. ex) [“-foo”, “-f”]
オプションタイプには, 以下のような値が使用可能.
| shell.option.ANY | 何でも OK. オプション値に文字列があればオプションの値になるし, 無ければ null となる |
| shell.option.NOARG | オプション値が指定されないことを期待するタイプ/ 解析結果のメンバーに入るが値は null |
| shell.option.BOOL | オプション値に true / false を期待し, 値は真偽値となる |
| shell.option.STRING | オプション値に任意の文字列を期待する |
| shell.option.INT | オプション値が数値であることを期待する (小数点を入れても無視される) |
| shell.option.FLOAT | オプション値が数値であることを期待する (OPTION_INT と違い, 小数点 OK) |
| shell.option.LIST | オプション値が “,” 区切りのリスト (", " とスペースをいれてはいけない) であることを期待し, 値は配列となる |
バリデータは現在入力中のオプション値を受け取り, その値が valid かどうかを真偽値で返す関数. 通常は null を設定しておけば問題ないだろう.
オプションの補完候補には, [“value1”, “value2”, “value3”] といった配列を指定する.
以上を踏まえ, オプション例を以下に示す.
[
[["-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]
];
そのコマンドがいくつ引数を受けとることができるかを指定する. なお, オプションは引数に含まれない.
| “0” | arguments 無し |
| “1” | arguments の数がきっちりと 1 つ |
| “2” | arguments の数がきっちりと 2 つ |
| “n” | arguments の数がきっちりと n 個 |
| “+” | arguments の数が 1 個以上 |
| “*” | arguments の数が 0 個以上 |
| “?” | arguments の数が 0 個か 1 個 |
既にそのコマンドが存在しているときに上書きするか否かの真偽値. 通常は特に必要ない.