relay: add command "completion" in weechat relay protocol (closes #1484)

3 files changed, 425 insertions, 33 deletions

diff --git a/doc/en/weechat_relay_protocol.en.adoc b/doc/en/weechat_relay_protocol.en.adoc
index f6b50fba9..7a0c70949 100644
--- a/doc/en/weechat_relay_protocol.en.adoc
+++ b/doc/en/weechat_relay_protocol.en.adoc
@@ -86,17 +86,18 @@ List of available commands (detail in next chapters):
 
 [width="100%",cols="^3m,14",options="header"]
 |===
-| Command   | Description
-| handshake | Handshake: prepare client authentication and set options, before _init_ command.
-| init      | Authenticate with _relay_.
-| hdata     | Request a _hdata_.
-| info      | Request an _info_.
-| infolist  | Request an _infolist_.
-| nicklist  | Request a _nicklist_.
-| input     | Send data to a buffer (text or command).
-| sync      | Synchronize buffer(s): get updates for buffer(s).
-| desync    | Desynchronize buffer(s): stop updates for buffer(s).
-| quit      | Disconnect from _relay_.
+| Command    | Description
+| handshake  | Handshake: prepare client authentication and set options, before _init_ command.
+| init       | Authenticate with _relay_.
+| hdata      | Request a _hdata_.
+| info       | Request an _info_.
+| infolist   | Request an _infolist_.
+| nicklist   | Request a _nicklist_.
+| input      | Send data to a buffer (text or command).
+| completion | Request completion of a string.
+| sync       | Synchronize buffer(s): get updates for buffer(s).
+| desync     | Desynchronize buffer(s): stop updates for buffer(s).
+| quit       | Disconnect from _relay_.
 |===
 
 [[command_handshake]]
@@ -447,6 +448,135 @@ input core.weechat /help filter
 input irc.freenode.#weechat hello!
 ----
 
+[[command_completion]]
+=== completion
+
+_WeeChat ≥ 2.9._
+
+Request completion of a string: list of possible words at a given position in
+a string for a given buffer.
+
+Syntax:
+
+----
+(id) completion <buffer> <position> [<data>]
+----
+
+Arguments:
+
+* _buffer_: pointer (_0x12345_) or full name of buffer (for example:
+  _core.weechat_ or _irc.freenode.#weechat_)
+* _position_: position for completion in string (starts to 0);
+  if the value is -1, the position is the length of _data_ (so the completion
+  is made at the end of _data_)
+* _data_: the input string; if not given, completion is performed on an empty
+  string
+
+WeeChat replies with a hdata:
+
+[width="100%",cols="3m,2,10",options="header"]
+|===
+| Name      | Type             | Description
+| context   | string           | Completion context: "null" (no completion), "command", "command_arg", "auto".
+| base_word | string           | The base word used for completion.
+| pos_start | integer          | Index of first char to replace (starts to 0).
+| pos_end   | integer          | Index of last char to replace (starts to 0).
+| add_space | integer          | 1 if a space must be added after words, 0 otherwise.
+| list      | array of strings | List of words found; empty if nothing was found to complete at asked position.
+|===
+
+[NOTE]
+In case of error, for example invalid buffer or internal error on WeeChat side,
+an empty hdata is returned.
+
+Example: completion of a command argument:
+
+----
+(test) completion core.weechat -1 /help fi
+----
+
+Response:
+
+[source,python]
+----
+id: 'test'
+hda:
+  keys: {'context': 'str', 'base_word': 'str', 'pos_start': 'int', 'pos_end': 'int', 'add_space': 'int', 'list': 'arr'}
+  path: ['completion']
+  item 1:
+    __path: ['0x55d0ccc842c0']
+    context: 'command_arg'
+    base_word: 'fi'
+    pos_start: 6
+    pos_end: 7
+    add_space: 0
+    list: ['fifo', 'fifo.file.enabled', 'fifo.file.path', 'filter']
+----
+
+Example: completion of a command in the middle of a word:
+
+----
+(test) completion core.weechat 5 /quernick
+----
+
+Response:
+
+[source,python]
+----
+id: 'test'
+hda:
+  keys: {'context': 'str', 'base_word': 'str', 'pos_start': 'int', 'pos_end': 'int', 'add_space': 'int', 'list': 'arr'}
+  path: ['completion']
+  item 1:
+    __path: ['0x55d0ccc88470']
+    context: 'command'
+    base_word: 'quer'
+    pos_start: 1
+    pos_end: 4
+    add_space: 1
+    list: ['query']
+----
+
+Example: nothing to complete:
+
+----
+(test) completion core.weechat -1 abcdefghijkl
+----
+
+Response:
+
+[source,python]
+----
+id: 'test'
+hda:
+  keys: {'context': 'str', 'base_word': 'str', 'pos_start': 'int', 'pos_end': 'int', 'add_space': 'int', 'list': 'arr'}
+  path: ['completion']
+  item 1:
+    __path: ['0x55d0ccc88470']
+    context: 'auto'
+    base_word: 'abcdefghijkl'
+    pos_start: 0
+    pos_end: 11
+    add_space: 1
+    list: []
+----
+
+Example: invalid buffer:
+
+----
+(test) completion buffer.does.not.exist -1 /help fi
+----
+
+Response:
+
+[source,python]
+----
+id: 'test'
+hda:
+  keys: {}
+  path: ['completion']
+----
+
 [[command_sync]]
 === sync
 
diff --git a/doc/fr/weechat_relay_protocol.fr.adoc b/doc/fr/weechat_relay_protocol.fr.adoc
index c2c63395d..f30621afe 100644
--- a/doc/fr/weechat_relay_protocol.fr.adoc
+++ b/doc/fr/weechat_relay_protocol.fr.adoc
@@ -91,17 +91,18 @@ Liste des commandes disponibles (détail dans les chapitres suivants) :
 
 [width="100%",cols="^3m,14",options="header"]
 |===
-| Commande  | Description
-| handshake | Poignée de main : préparer l'authentification du client et définir des options, avant la commande _init_.
-| init      | S'authentifier avec _relay_.
-| hdata     | Demander un _hdata_.
-| info      | Demander une _info_.
-| infolist  | Demander une _infolist_.
-| nicklist  | Demander une _nicklist_ (liste de pseudos).
-| input     | Envoyer des données à un tampon (texte ou commande).
-| sync      | Synchroniser un/des tampon(s) : recevoir les mises à jour pour le(s) tampon(s).
-| desync    | Désynchroniser un/des tampon(s) : stopper les mises à jour pour le(s) tampon(s).
-| quit      | Se déconnecter de _relay_.
+| Commande   | Description
+| handshake  | Poignée de main : préparer l'authentification du client et définir des options, avant la commande _init_.
+| init       | S'authentifier avec _relay_.
+| hdata      | Demander un _hdata_.
+| info       | Demander une _info_.
+| infolist   | Demander une _infolist_.
+| nicklist   | Demander une _nicklist_ (liste de pseudos).
+| input      | Envoyer des données à un tampon (texte ou commande).
+| completion | Demander la complétion d'une chaîne.
+| sync       | Synchroniser un/des tampon(s) : recevoir les mises à jour pour le(s) tampon(s).
+| desync     | Désynchroniser un/des tampon(s) : stopper les mises à jour pour le(s) tampon(s).
+| quit       | Se déconnecter de _relay_.
 |===
 
 [[command_handshake]]
@@ -464,6 +465,135 @@ input core.weechat /help filter
 input irc.freenode.#weechat bonjour !
 ----
 
+[[command_completion]]
+=== completion
+
+_WeeChat ≥ 2.9._
+
+Demander la complétion d'une chaîne : liste des mots possibles à une position
+donnée dans la chaîne et sur un tampon donné.
+
+Syntaxe :
+
+----
+(id) completion <tampon> <position> [<données>]
+----
+
+Paramètres :
+
+* _tampon_ : pointeur (_0x12345_) ou nom complet du tampon (par exemple :
+  _core.weechat_ ou _irc.freenode.#weechat_)
+* _position_ : position dans la chaîne pour la complétion (démarre à 0) ;
+  si la valeur est -1, la position est la longueur de _données_ (donc la
+  complétion se fait à la fin de _données_)
+* _données_ : la chaîne en entrée ; si non donnée, la complétion est faite sur
+  une chaîne vide
+
+WeeChat répond avec un hdata :
+
+[width="100%",cols="3m,2,10",options="header"]
+|===
+| Nom       | Type               | Description
+| context   | chaîne             | Contexte de complétion : "null" (pas de complétion), "command", "command_arg", "auto".
+| base_word | chaîne             | Le mot de base utilisé pour la complétion.
+| pos_start | entier             | Index du premier caractère à remplacer (démarre à 0).
+| pos_end   | entier             | Index du dernier caractère à remplacer (démarre à 0).
+| add_space | entier             | 1 si un espace doit être ajouté après les mods, 0 sinon.
+| list      | tableau de chaînes | Liste des mots ; vide si rien n'a été trouvé pour compléter à la position demandée.
+|===
+
+[NOTE]
+En cas d'erreur, par exemple un tampon invalide ou une erreur interne du côté
+de WeeChat, un hdata vide est retourné.
+
+Exemple : complétion d'un paramètre de commande :
+
+----
+(test) completion core.weechat -1 /help fi
+----
+
+Réponse :
+
+[source,python]
+----
+id: 'test'
+hda:
+  keys: {'context': 'str', 'base_word': 'str', 'pos_start': 'int', 'pos_end': 'int', 'add_space': 'int', 'list': 'arr'}
+  path: ['completion']
+  item 1:
+    __path: ['0x55d0ccc842c0']
+    context: 'command_arg'
+    base_word: 'fi'
+    pos_start: 6
+    pos_end: 7
+    add_space: 0
+    list: ['fifo', 'fifo.file.enabled', 'fifo.file.path', 'filter']
+----
+
+Exemple : complétion d'une commande au milieu d'un mot :
+
+----
+(test) completion core.weechat 5 /quernick
+----
+
+Réponse :
+
+[source,python]
+----
+id: 'test'
+hda:
+  keys: {'context': 'str', 'base_word': 'str', 'pos_start': 'int', 'pos_end': 'int', 'add_space': 'int', 'list': 'arr'}
+  path: ['completion']
+  item 1:
+    __path: ['0x55d0ccc88470']
+    context: 'command'
+    base_word: 'quer'
+    pos_start: 1
+    pos_end: 4
+    add_space: 1
+    list: ['query']
+----
+
+Exemple : rien à compléter :
+
+----
+(test) completion core.weechat -1 abcdefghijkl
+----
+
+Réponse :
+
+[source,python]
+----
+id: 'test'
+hda:
+  keys: {'context': 'str', 'base_word': 'str', 'pos_start': 'int', 'pos_end': 'int', 'add_space': 'int', 'list': 'arr'}
+  path: ['completion']
+  item 1:
+    __path: ['0x55d0ccc88470']
+    context: 'auto'
+    base_word: 'abcdefghijkl'
+    pos_start: 0
+    pos_end: 11
+    add_space: 1
+    list: []
+----
+
+Exemple : tampon invalide :
+
+----
+(test) completion buffer.does.not.exist -1 /help fi
+----
+
+Réponse :
+
+[source,python]
+----
+id: 'test'
+hda:
+  keys: {}
+  path: ['completion']
+----
+
 [[command_sync]]
 === sync
 
diff --git a/doc/ja/weechat_relay_protocol.ja.adoc b/doc/ja/weechat_relay_protocol.ja.adoc
index 77e0bbf08..a52aee046 100644
--- a/doc/ja/weechat_relay_protocol.ja.adoc
+++ b/doc/ja/weechat_relay_protocol.ja.adoc
@@ -93,18 +93,20 @@ _リレー_ プラグインは _IRC プロキシ_ のように振舞います (�
 
 [width="100%",cols="^3m,14",options="header"]
 |===
-| コマンド  | 説明
+| コマンド   | 説明
 // TRANSLATION MISSING
-| handshake | Handshake: prepare client authentication and set options, before _init_ command.
-| init      | _リレー_ 接続を初期化
-| hdata     | _hdata_ を要求
-| info      | _インフォ_ を要求
-| infolist  | _インフォリスト_ を要求
-| nicklist  | _ニックネームリスト_ を要求
-| input     | バッファにデータを送信 (テキストまたはコマンド)
-| sync      | バッファを同期: バッファの最新情報を取得
-| desync    | バッファを非同期: バッファの更新を止める
-| quit      | _リレー_ から切断
+| handshake  | Handshake: prepare client authentication and set options, before _init_ command.
+| init       | _リレー_ 接続を初期化
+| hdata      | _hdata_ を要求
+| info       | _インフォ_ を要求
+| infolist   | _インフォリスト_ を要求
+| nicklist   | _ニックネームリスト_ を要求
+| input      | バッファにデータを送信 (テキストまたはコマンド)
+// TRANSLATION MISSING
+| completion | Request completion of a string.
+| sync       | バッファを同期: バッファの最新情報を取得
+| desync     | バッファを非同期: バッファの更新を止める
+| quit       | _リレー_ から切断
 |===
 
 // TRANSLATION MISSING
@@ -462,6 +464,136 @@ input core.weechat /help filter
 input irc.freenode.#weechat hello!
 ----
 
+// TRANSLATION MISSING
+[[command_completion]]
+=== completion
+
+_WeeChat ≥ 2.9._
+
+Request completion of a string: list of possible words at a given position in
+a string for a given buffer.
+
+構文:
+
+----
+(id) completion <buffer> <position> [<data>]
+----
+
+引数:
+
+* _buffer_: pointer (_0x12345_) or full name of buffer (for example:
+  _core.weechat_ or _irc.freenode.#weechat_)
+* _position_: position for completion in string (starts to 0);
+  if the value is -1, the position is the length of _data_ (so the completion
+  is made at the end of _data_)
+* _data_: the input string; if not given, completion is performed on an empty
+  string
+
+WeeChat replies with a hdata:
+
+[width="100%",cols="3m,2,10",options="header"]
+|===
+| Name      | Type             | Description
+| context   | string           | Completion context: "null" (no completion), "command", "command_arg", "auto".
+| base_word | string           | The base word used for completion.
+| pos_start | integer          | Index of first char to replace (starts to 0).
+| pos_end   | integer          | Index of last char to replace (starts to 0).
+| add_space | integer          | 1 if a space must be added after words, 0 otherwise.
+| list      | array of strings | List of words found; empty if nothing was found to complete at asked position.
+|===
+
+[NOTE]
+In case of error, for example invalid buffer or internal error on WeeChat side,
+an empty hdata is returned.
+
+Example: completion of a command argument:
+
+----
+(test) completion core.weechat -1 /help fi
+----
+
+Response:
+
+[source,python]
+----
+id: 'test'
+hda:
+  keys: {'context': 'str', 'base_word': 'str', 'pos_start': 'int', 'pos_end': 'int', 'add_space': 'int', 'list': 'arr'}
+  path: ['completion']
+  item 1:
+    __path: ['0x55d0ccc842c0']
+    context: 'command_arg'
+    base_word: 'fi'
+    pos_start: 6
+    pos_end: 7
+    add_space: 0
+    list: ['fifo', 'fifo.file.enabled', 'fifo.file.path', 'filter']
+----
+
+Example: completion of a command in the middle of a word:
+
+----
+(test) completion core.weechat 5 /quernick
+----
+
+Response:
+
+[source,python]
+----
+id: 'test'
+hda:
+  keys: {'context': 'str', 'base_word': 'str', 'pos_start': 'int', 'pos_end': 'int', 'add_space': 'int', 'list': 'arr'}
+  path: ['completion']
+  item 1:
+    __path: ['0x55d0ccc88470']
+    context: 'command'
+    base_word: 'quer'
+    pos_start: 1
+    pos_end: 4
+    add_space: 1
+    list: ['query']
+----
+
+Example: nothing to complete:
+
+----
+(test) completion core.weechat -1 abcdefghijkl
+----
+
+Response:
+
+[source,python]
+----
+id: 'test'
+hda:
+  keys: {'context': 'str', 'base_word': 'str', 'pos_start': 'int', 'pos_end': 'int', 'add_space': 'int', 'list': 'arr'}
+  path: ['completion']
+  item 1:
+    __path: ['0x55d0ccc88470']
+    context: 'auto'
+    base_word: 'abcdefghijkl'
+    pos_start: 0
+    pos_end: 11
+    add_space: 1
+    list: []
+----
+
+Example: invalid buffer:
+
+----
+(test) completion buffer.does.not.exist -1 /help fi
+----
+
+Response:
+
+[source,python]
+----
+id: 'test'
+hda:
+  keys: {}
+  path: ['completion']
+----
+
 [[command_sync]]
 === sync