Vimperator

以下の関数でコマンド登録が可能

liberator.commands.addUserCommand

または

liberator.commands.add

addメソッドはVimperator自身が使用するメソッドである。また、addメソッドの場合第5引数がなく、既に存在するコマンドの置き換えは不可能である。

1. names(Array):コマンド名となる文字列の配列
2. description(String):コマンドの簡易説明
3. action(Function):実行されるfunctionオブジェクト
4. extra(Object):補完機能やコマンド引数などを格納するオブジェクト(オプション)
5. replace(Boolean):既に存在するコマンドの場合、置き換えるか否か(オプション)

以下の様なコマンドを登録するとhelloworld,hello,hwの3つのコマンド名で実行可能になる。

liberator.commands.addUserCommand(
    ["hello[world]","hw"],
    "print hello world",
    function(){
        liberator.echo("Hello World");
    }
);

コマンド名となる文字列の後部を[]で囲むと省略可能とされてhelloworld,helloの2つに展開される。
["[hello]world"]や["hello[worl]d"]のようなものは無効。

概要を説明する文。コマンド補完時に使用される程度。

実際のコマンドの動作を受け持つfunctionオブジェクト。
以下の引数を受け取ることが出来る

1. コマンド引数の文字列
2. コマンド後部!の有無を示す真偽値
3. コマンド頭部のある数値

第一引数に渡るコマンド引数はextraオブジェクトのoptionsやargCountの内容によって変化し、単純な文字列ではなくパースされた結果となることもある。

どれもオプションであるので無くても構わないが、気の利いたコマンドを作ろうとしたらextraオブジェクトの理解は必須となるだろう。
extraオブジェクトには以下のメンバーを持たせると意味がある。

completer

タブ補完時に実行され、補完値を返すfunctionオブジェクト

options

コマンド引数をパースするときに用いられる配列

argCount

コマンド引数の数を定義する文字列

既にそのコマンドが存在しているときに上書きするか否かの真偽値。
通常は特に必要ないだろう。

コマンド引数の補完機能を受け持つ関数(functionオブジェクト)を定義する。

与えられる引数、返すべき値にはルールがある。

1. 入力されているコマンド引数の文字列(String)
2. コマンドに"!"が使用されているか否かの真偽値(Boolean)

[
  オフセット値(Number),
  [
    ["候補値_1(String)","候補値_1の説明(String)"],
    ["候補値_2(String)","候補値_2の説明(String)"],
    //...
  ]
]

という配列を返さなければならない。

オフセット値

補完を開始する文字列の開始位置

completer: function(filter){
  var allSuggestions = [
    ["foo","foo description"],
    ["bar","bar description"],
    ["hoge","hoge description"]
  ];
  if (!filter) return [0, allSuggestions];
  var suggestions = allSuggestions.filter(function(s){
    return s[0].indexOf(filter) == 0;
  });
  return [0, suggestions];
},

コマンド引数の解析時に用いられる。指定するとaction関数の第一引数が解析された結果となるので注意
パースされた結果、第一引数は文字列(String)ではなく、メンバーに

• arguments: optionsで解析されなかった文字列の配列
• optionsで解析されたオプション名とその値

を持つObjectとなる。

言葉で説明しても分かり難い。実際にbmarkコマンドの例を見たほうが早かろう。
bmarkコマンドはブックマークするURLとタイトルやタグ、キーワードのオプションを指定することができる。

:bmark http://example.com/ -title Example -T example,Tag -k keyword

とすると解析された結果は

{
  arguments: ["http://example.com"],
  -title: "Example",
  -tags:  ["example","Tag"],
  -keyword: "keyword"
}

となる。bmarkコマンドのoptionsの定義は以下の様になっている。

options: [
  [["-title",   "-t"], liberator.commands.OPTION_STRING],
  [["-tags",    "-T"], liberator.commands.OPTION_LIST],
  [["-keyword", "-k"], liberator.commands.OPTION_STRING, function(arg) { return /\w/.test(arg); }]
],

細かい説明は省略。ソースコードに書かれている説明を載せておく

@param str: something like "-x=foo -opt=bar arg1 arg2"
"options" is an array [name, type, validator, completions] and could look like:
options = [[["-force"], OPTION_NOARG],
          [["-fullscreen", "-f"], OPTION_BOOL],
          [["-language"], OPTION_STRING, validateFunc, ["perl", "ruby"]],
          [["-speed"], OPTION_INT],
          [["-acceleration"], OPTION_FLOAT],
          [["-accessories"], OPTION_LIST, null, ["foo", "bar"]],
          [["-other"], OPTION_ANY]];

2番目の要素に指定するタイプ

OPTION_ANY

何でもOK。オプション値に文字列があればオプションの値になるし、無ければnullとなる

OPTION_NOARG

オプション値が指定されないことを期待するタイプ。解析結果のメンバーに入るが値はnull

OPTION_BOOL

オプション値にon/offを期待し、値は真偽値となる

OPTION_STRING

オプション値に任意の文字列を期待する

OPTION_INT

オプション値が数値であることを期待する(小数点を入れても無視される)

OPTION_FLOAT

オプション値が数値であることを期待する(OPTION_INTと違い、小数点OK)

OPTION_LIST

オプション値が","区切りのリストであることを期待すし、値は配列となる

コマンド引数解析時に用いられ、action関数の第一引数が解析された結果となるので注意
おそらくoptionsと共に用いられることになるだろう。コマンド引数解析でオプションとみなされずargumentsに入る値の数を定義するメンバーである。

"0"

arguments無し

"1"

argumentsの数がきっちりと1つ

"+"

argumentsの数が1個以上

"*"

argumentsの数が0個以上

"?"

argumentsの数が0固か1個