Vimperator

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

liberator.modules.commands.addUserCommand
commands.addUserCommand

または

liberator.modules.commands.add
commands.add

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

commands.addUseCommand(
  ["he[llo]","h"],  // コマンド名
  "description",     // コマンドの説明
  function(args, bang, count) {... },  // コマンド本体の処理（functionオブジェクト）
  {  /* extras */
    completer : function (context, args) {  // 補完関数
　　　context.anchor = false;     // （省略可）
      context.ignoreCase = true;  // （省略可）
      context.title = ["url", "title"];
      context.completions = [
        ["候補1URL", "候補タイトル1"],
        ["候補2URL", "候補タイトル2"],
      ];
    },
    options : [
     [["-optionA", "-a"], 
      OPTION_ANY,  
      function(arg) {... },      // オプション値の正当性をチェックする関数?
      function(context) {... },  // 
     ]],
    argCount: "*",       // "0"|"1"|"+"|"?"|"*"
    hereDoc: false,      // ヒアドキュメントとして受け取るか
    bang: false,         // !を許可するか
    count: false,        // 回数指定で実行可能か
    literal: false       // リテラルとして扱うか
  },
  replace               // 既存のコマンドを置き換えるかどうか
);

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

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

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

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

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

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

1. コマンド引数をliberator.modules.commands.parseArgsでパースした結果(オブジェクト)
2. コマンド後部!の有無を示す真偽値
3. コマンド頭部のある数値

version1.2preまでと異なり、第一引数に渡るコマンド引数はextraオブジェクトのoptionsやargCountなどの内容によって変化し、パースされた結果(object)となるので注意

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

completer

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

options

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

argCount

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

hereDoc

ヒアドキュメントで引数を渡せるかどうかの真偽値

bang

コマンドが"!"を使用するかどうかの真偽値

count

コマンドがrange(コマンド先頭の数値)を使うかどうかの真偽値

literal

コマンドがargCountより多い引数を必要とするかどうかの真偽値

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

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

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

1. context(Object)
2. args(Array)

• args.bang には(!の有無)(Boolean)
• args[オプション名] にオプションの値
• 各配列データに引数

第一引数のcontext にあるcontext.titleに

contenxt.title = ["名前"];

もしくは

context.title = ["名前","概要"];

の様に代入する。

第一引数のcontextにあるcontext.completionsに

context.completions = [
  ["候補値_1(String)","候補値_1の説明(String)"],
  ["候補値_2(String)","候補値_2の説明(String)"],
];

の様に代入する。

completer: function(context, arg){
  context.title = ["exampleplugin"];
  let allSuggestions = [
    ["foo","foo description"],
    ["bar","bar description"],
    ["hoge","hoge description"]
  ];
  context.completions = allSuggestions;
},

Vimperator内部で自動的にフィルタリングしてくれるので、特にこちらでフィルタする必要はない。

context.completionsに代入する前に、context.ignoreCaseに真偽値を入れることで大文字/小文字の区別の制御が可能である。
trueを代入することでbAとしてもbarと補完することが可能になる。
デフォルトではcontext.ignoreCaseはfalseになっている。また、ユーザがwildcaseをignoreに設定することでも可能。

completer: function(context, args){
	context.ignoreCase = true; //大文字/小文字の区別をなくす
	context.completions = [
		["bar","bar desc"],
		//...
	];
},

通常、fooを補完したい場合、先頭から入力してタブ補完する必要がある。ooからは補完できない。これを制御するのが、context.anchoredだ。
デフォルトではtrueになっていて、最初からマッチしないと補完できない。falseを代入することで、補完対象に含まれていればリストに載るようにできる。

completer: function(context, args){
	context.anchored = false;
	context.completions = [
		// ...
	];
}

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

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

を持つObjectとなる。

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

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

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

args = ["http://example.com"];
args["-title"] = "Example";
args["-tags"] = ["example","Tag"];
args["-keyword"] = "keyword";

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

options: [
  [["-title",   "-t"], commands.OPTION_STRING],
  [["-tags",    "-T"], commands.OPTION_LIST],
  [["-keyword", "-k"], 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

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

OPTION_BOOL

オプション値にon/offを期待し、値は真偽値となる。別の値の場合はNaNになる

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個

コマンド引数をヒアドキュメントで与えることが可能かどうかの真偽値。trueに設定すると

:command <<EOM
foo bar
hoge
EOM

とすることが可能になる。

コマンドがbang(!)を使えるかどうかの真偽値。trueにしないと、実行時に!を付けるとエラーとなり、E477: No ! allowedというメッセージが表示される

コマンドがrange(先頭に付ける数値)を使えるかどうかの真偽値。''true'にしないと、2commandNameなどと実行した場合にエラーとなり、E481 No range allowedというメッセージが表示される

argCountと一緒に用いられ、argCount数以降の引数を格納するかどうかの真偽値。trueにしないと、argCountが2で引数を3つ以上つけるとパースエラーとなってしまう。
autocmdコマンドの様に3つの引数を必要とするが2つ目までは固定的で3つ目からは一つの文字列として扱いたいときなどに有効(autocmdの場合はargCount: "2",literal: true となっている)

コマンドに第一引数に渡るコマンド引数はversion 1.2preまでと異なり必ずliberator.modules.commands.parseArgsでパースされる様になり、結果objectとして渡されるので少々複雑になった。
ここではその解説。

パースされて返るオブジェクトを以降argsとする。

argsオブジェクトはArrayである。0,1,2,,,に通常の引数が入るが、他に以下のメンバを持つ。

literalArg(String)

argCountに収まらない以降の引数の文字列(literal:trueの場合)

string(String)

引数全体の文字列

その他

optionsで与えたオプション名の第一要素をメンバ名として、String,Number,Arrayが入る

シェルと同じく引用符で括ると、引用符で閉じられるまでを一つの引数として扱ってくれる。
ダブルコートとシングルコートとでエスケープ文字(\)の扱いが異なり、挙動が変わることがあるので注意(注意するのはコマンド使用者だが)

:echoコマンドを用いて開発時にはいろいろ試してみると良いだろう。

:echo commands.parseArgs("-a -s on foo1 foo2", [[["-all","-a"],commands.OPTION_NOARG],[["-switch","-s"],commands.OPTION_BOOL]], "*")

結果

args = ["foo1","foo2"];
args["-all"] = true;
args["-switch"] = true;
args.literalArg = "";
args.string = "-a hoge -s on";