core: add optional arguments in completion template, sent to the callback

2016-11-29 20:01:35 +01:00 · 2016-11-29 20:01:35 +01:00 · d0af6b8dce
commit d0af6b8dce
parent 93ef6b0a3e
5 changed files with 104 additions and 29 deletions
--- a/ChangeLog.adoc
+++ b/ChangeLog.adoc
@ -20,6 +20,7 @@ https://weechat.org/files/releasenotes/ReleaseNotes-devel.html[release notes]

 New features::

+  * core: add optional arguments in completion template, sent to the callback
  * core: add option "time" in command /debug
  * api: add info "pid" (WeeChat PID) (issue #850)
  * fifo: add file fifo.conf and option fifo.file.path to customize FIFO pipe path/filename (issue #850)
--- a/doc/en/weechat_plugin_api.en.adoc
+++ b/doc/en/weechat_plugin_api.en.adoc
@ -7053,7 +7053,7 @@ config, completion, modifier, info, info_hashtable, infolist, hdata, focus.

 ==== hook_command

-_Updated in 1.5._
+_Updated in 1.5, 1.7._

 Hook a command.

@ -7083,10 +7083,7 @@ Arguments:
 * _description_: description for command (displayed with `/help command`)
 * _args_: arguments for command (displayed with `/help command`)
 * _args_description_: description of arguments (displayed with `/help command`)
-* _completion_: completion template for command: list of completions for each
-  argument, separated by space. Many completions are possible for one
-  argument, separated by `+|+`. Many templates are possible for same command,
-  separated by `+||+`.
+* _completion_: completion template for command (see format below)
 * _callback_: function called when command is used, arguments and return value:
 ** _const void *pointer_: pointer
 ** _void *data_: pointer
@ -7103,6 +7100,26 @@ Arguments:
  if not NULL, it must have been allocated with malloc (or similar function)
  and it is automatically freed when the hook is deleted

+The _completion_ template is a list of completions for each argument, separated
+by spaces. Many completions are possible for one argument, separated by `+|+`.
+Many templates are possible for same command, separated by `+||+`.
+
+The format of a completion can be:
+
+* _%(name)_: the completion _name_
+* _%(name:arguments)_: the completion _name_ with _arguments_ sent to the
+  callback _(WeeChat ≥ 1.7)_
+* any string: it is used as-is in completion
+
+For example the template `list || add %(filters_names) || del %(filters_names)|-all`
+will complete with following values in command arguments:
+
+* first argument: `list`, `add` and `del`
+* second argument, depending on first argument:
+** `list`: nothing
+** `add`: names of filters
+** `del`: names of filters and `-all`
+
 Default completion codes are:

 include::autogen/plugin_api/completions.adoc[]
@ -7189,7 +7206,7 @@ hook = weechat.hook_command("myfilter", "description of myfilter",

 ==== hook_completion

-_Updated in 1.5._
+_Updated in 1.5, 1.7._

 Hook a completion.

@ -7210,15 +7227,17 @@ struct t_hook *weechat_hook_completion (const char *completion_item,

 Arguments:

-* _completion_item_: name of completion item, after you can use _%(name)_ in
-  a command hooked (argument _completion_)
+* _completion_item_: name of completion item, after you can use _%(name)_
+  (or _%(name:arguments)_ with WeeChat ≥ 1.7) in a command hooked
+  (argument _completion_)
  (priority allowed, see note about <<hook_priority,priority>>)
 * _description_: description of completion
 * _callback_: function called when completion item is used (user is completing
  something using this item), arguments and return value:
 ** _const void *pointer_: pointer
 ** _void *data_: pointer
-** _const char *completion_item_: name of completion item
+** _const char *completion_item_: name of completion item (with WeeChat ≥ 1.7 it
+   can include arguments, with the format: _name:arguments_)
 ** _struct t_gui_buffer *buffer_: buffer where completion is made
 ** _struct t_gui_completion *completion_: structure used to add words for
   completion (see
--- a/doc/fr/weechat_plugin_api.fr.adoc
+++ b/doc/fr/weechat_plugin_api.fr.adoc
@ -7171,7 +7171,7 @@ hdata, focus.

 ==== hook_command

-_Mis à jour dans la 1.5._
+_Mis à jour dans la 1.5, 1.7._

 Accrocher une commande.

@ -7202,11 +7202,7 @@ Paramètres :
 * _args_ : paramètres pour la commande (affichés avec `/help command`)
 * _args_description_ : description des paramètres (affichée avec
  `/help command`)
-* _completion_ : modèle pour la complétion de la commande : liste des
-  complétions pour chaque paramètre, séparés par des espaces. Plusieurs
-  complétions sont possibles pour un paramètre, séparées par `+|+`. Plusieurs
-  modèles de complétions sont possibles pour une même commande, séparés par
-  `+||+`.
+* _completion_ : modèle pour la complétion de la commande (voir le format ci-dessous)
 * _callback_ : fonction appelée lorsque la commande est utilisée, paramètres et
  valeur de retour :
 ** _const void *pointer_ : pointeur
@ -7226,6 +7222,27 @@ Paramètres :
  similaire) et est automatiquement libéré (par free) lorsque le "hook" est
  supprimé

+Le modèle de complétion est une liste de complétions pour chaque paramètre,
+séparés par des espaces. Plusieurs complétions sont possibles pour un paramètre,
+séparées par `+|+`. Plusieurs modèles de complétions sont possibles pour une
+même commande, séparés par `+||+`.
+
+Le format de la complétion peut être :
+
+* _%(nom)_ : la complétion _nom_
+* _%(nom:paramètres)_ : la complétion _nom_ avec des _paramètres_ envoyés au
+  « callback » _(WeeChat ≥ 1.7)_
+* toute chaîne : elle est utilisée telle quelle dans la complétion
+
+Par exemple le modèle `list || add %(filters_names) || del %(filters_names)|-all`
+complètera avec les valeurs suivantes dans les paramètres de commande :
+
+* premier paramètre : `list`, `add` et `del`
+* second paramètre, cela dépend du premier paramètre :
+** `list` : rien
+** `add` : noms des filtres
+** `del` : noms des filtres et `-all`
+
 Les codes complétions par défaut sont :

 include::autogen/plugin_api/completions.adoc[]
@ -7312,7 +7329,7 @@ hook = weechat.hook_command("monfiltre", "description de monfiltre",

 ==== hook_completion

-_Mis à jour dans la 1.5._
+_Mis à jour dans la 1.5, 1.7._

 Accrocher une complétion.

@ -7334,7 +7351,8 @@ struct t_hook *weechat_hook_completion (const char *completion_item,
 Paramètres :

 * _completion_item_ : nom de l'objet de complétion, après vous pouvez utiliser
-  _%(nom)_ dans une commande (paramètre _completion_)
+  _%(nom)_ (ou _%(nom:paramètres)_ avec WeeChat ≥ 1.7) dans une commande
+  (paramètre _completion_)
  (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
 * _description_ : description de la complétion
 * _callback_ : fonction appelée lorsque la complétion est utilisée
@ -7342,7 +7360,8 @@ Paramètres :
  complétion), paramètres et valeur de retour :
 ** _const void *pointer_ : pointeur
 ** _void *data_ : pointeur
-** _const char *completion_item_ : nom de la complétion
+** _const char *completion_item_ : nom de la complétion (avec WeeChat ≥ 1.7 il
+   peut inclure des paramètres, avec le format : _nom:paramètres_)
 ** _struct t_gui_buffer *buffer_ : tampon où la complétion est effectuée
 ** _struct t_gui_completion *completion_ : structure utilisée pour ajouter
   les mots pour la complétion (voir
--- a/doc/ja/weechat_plugin_api.ja.adoc
+++ b/doc/ja/weechat_plugin_api.ja.adoc
@ -7058,7 +7058,7 @@ command、command_run、signal、hsignal、config、completion、modifier、info

 ==== hook_command

-_WeeChat バージョン 1.5 で更新。_
+_WeeChat バージョン 1.5 と 1.7 で更新。_

 コマンドをフックする。

@ -7088,10 +7088,8 @@ struct t_hook *weechat_hook_command (const char *command,
 * _description_: コマンドの説明 (`/help command` で表示されます)
 * _args_: コマンドの引数 (`/help command` で表示されます)
 * _args_description_: 引数の説明 (`/help command` で表示されます)
-* _completion_: コマンドの補完候補テンプレート: 各引数に対する補完候補の空白区切りリスト。1
-  つの引数に対して複数の補完候補を設定するには補完候補同士を `+|+`
-  で区切ってください。1 つのコマンドに対して複数のテンプレートを設定するにはテンプレート同士を
-  `+||+` で区切ってください。
+// TRANSLATION MISSING
+* _completion_: completion template for command (see format below)
 * _callback_: コマンドが使用された際に呼び出すコールバック関数、引数と戻り値:
 ** _const void *pointer_: ポインタ
 ** _void *data_: ポインタ
@ -7108,6 +7106,29 @@ struct t_hook *weechat_hook_command (const char *command,
  このポインタが NULL でない場合、このポインタは malloc (または類似の関数)
  によって割り当てられたものでなければいけません。さらに、このポインタはここで作成したフックが削除された時点で自動的に開放されます

+// TRANSLATION MISSING
+The _completion_ template is a list of completions for each argument, separated
+by spaces. Many completions are possible for one argument, separated by `+|+`.
+Many templates are possible for same command, separated by `+||+`.
+
+// TRANSLATION MISSING
+The format of a completion can be:
+
+* _%(name)_: the completion _name_
+* _%(name:arguments)_: the completion _name_ with _arguments_ sent to the
+  callback _(WeeChat ≥ 1.7)_
+* any string: it is used as-is in completion
+
+// TRANSLATION MISSING
+For example the template `list || add %(filters_names) || del %(filters_names)|-all`
+will complete with following values in command arguments:
+
+* first argument: `list`, `add` and `del`
+* second argument, depending on first argument:
+** `list`: nothing
+** `add`: names of filters
+** `del`: names of filters and `-all`
+
 デフォルトの補完候補コードは:

 include::autogen/plugin_api/completions.adoc[]
@ -7194,7 +7215,7 @@ hook = weechat.hook_command("myfilter", "description of myfilter",

 ==== hook_completion

-_WeeChat バージョン 1.5 で更新。_
+_WeeChat バージョン 1.5 と 1.7 で更新。_

 補完をフック。

@ -7215,15 +7236,19 @@ struct t_hook *weechat_hook_completion (const char *completion_item,

 引数:

-* _completion_item_: 補完要素の名前、この後フックされたコマンドで
-  _%(name)_ を使うことができます (_completion_ 引数)
-  (優先度の設定が可能、<<hook_priority,優先度>>に関する注意を参照)
+// TRANSLATION MISSING
+* _completion_item_: name of completion item, after you can use _%(name)_
+  (or _%(name:arguments)_ with WeeChat ≥ 1.7) in a command hooked
+  (argument _completion_)
+  (priority allowed, see note about <<hook_priority,priority>>)
 * _description_: 補完の説明
 * _callback_: 補完要素 (ユーザはこの要素を使って何かを補完している)
  が使われた場合に呼び出すコールバック関数、引数と戻り値:
 ** _const void *pointer_: ポインタ
 ** _void *data_: ポインタ
-** _const char *completion_item_: 補完要素の名前
+// TRANSLATION MISSING
+** _const char *completion_item_: 補完要素の名前 (with WeeChat ≥ 1.7 it
+   can include arguments, with the format: _name:arguments_)
 ** _struct t_gui_buffer *buffer_: 補完が行われたバッファ
 ** _struct t_gui_completion *completion_:
   補完に際して単語を追加するために使われる構造体
--- a/src/core/wee-hook.c
+++ b/src/core/wee-hook.c
@ -2869,12 +2869,21 @@ hook_completion_exec (struct t_weechat_plugin *plugin,
                      struct t_gui_completion *completion)
 {
    struct t_hook *ptr_hook, *next_hook;
+    const char *pos;
+    char *item;

    /* make C compiler happy */
    (void) plugin;

    hook_exec_start ();

+    pos = strchr (completion_item, ':');
+    item = (pos) ?
+        string_strndup (completion_item, pos - completion_item) :
+        strdup (completion_item);
+    if (!item)
+        return;
+
    ptr_hook = weechat_hooks[HOOK_TYPE_COMPLETION];
    while (ptr_hook)
    {
@ -2883,7 +2892,7 @@ hook_completion_exec (struct t_weechat_plugin *plugin,
        if (!ptr_hook->deleted
            && !ptr_hook->running
            && (string_strcasecmp (HOOK_COMPLETION(ptr_hook, completion_item),
-                                   completion_item) == 0))
+                                   item) == 0))
        {
            ptr_hook->running = 1;
            (void) (HOOK_COMPLETION(ptr_hook, callback))
@ -2898,6 +2907,8 @@ hook_completion_exec (struct t_weechat_plugin *plugin,
        ptr_hook = next_hook;
    }

+    free (item);
+
    hook_exec_end ();
 }