api: add parameters pointers, extra_vars and options in function hdata_search

1 files changed, 34 insertions, 5 deletions

diff --git a/doc/it/weechat_plugin_api.it.adoc b/doc/it/weechat_plugin_api.it.adoc
index a2273eac5..b1e224b42 100644
--- a/doc/it/weechat_plugin_api.it.adoc
+++ b/doc/it/weechat_plugin_api.it.adoc
@@ -17822,7 +17822,8 @@ if buffer:
 
 ==== hdata_search
 
-_WeeChat ≥ 0.4.1._
+// TRANSLATION MISSING
+_WeeChat ≥ 0.4.1, updated in 3.4._
 
 // TRANSLATION MISSING
 Search element in a list: the expression _search_ is evaluated for each element
@@ -17832,7 +17833,9 @@ Prototipo:
 
 [source,C]
 ----
-void *weechat_hdata_search (struct t_hdata *hdata, void *pointer, const char *search, int move);
+void *weechat_hdata_search (struct t_hdata *hdata, void *pointer, const char *search,
+                            struct t_hashtable *pointers, struct t_hashtable *extra_vars,
+                            struct t_hashtable *options, int move);
 ----
 
 Argomenti:
@@ -17845,9 +17848,24 @@ Argomenti:
   expression, see the
   link:weechat_user.it.html#command_weechat_eval[WeeChat user's guide / Command /eval]
 // TRANSLATION MISSING
+* _pointers_: hashtable for call to function
+  <<_string_eval_expression,string_eval_expression>>
+// TRANSLATION MISSING
+* _extra_vars_: hashtable for call to function
+  <<_string_eval_expression,string_eval_expression>>
+// TRANSLATION MISSING
+* _options_: hashtable for call to function
+  <<_string_eval_expression,string_eval_expression>>
+// TRANSLATION MISSING
 * _move_: number of jump(s) to execute after unsuccessful search (negative or
   positive integer, different from 0)
 
+// TRANSLATION MISSING
+[IMPORTANT]
+You must ensure the _search_ expression is safe and does not include any
+user data. Such unsafe data must be given in the hashtable _extra_vars_ and
+referenced by `${xxx}` in the _search_ expression (see the example below).
+
 Valore restituito:
 
 // TRANSLATION MISSING
@@ -17859,13 +17877,21 @@ Esempio in C:
 ----
 struct t_hdata *hdata = weechat_hdata_get ("irc_server");
 void *servers = weechat_hdata_get_list (hdata, "irc_servers");
+struct t_hashtable *extra_vars = weechat_hashtable_new (8,
+                                                        WEECHAT_HASHTABLE_STRING,
+                                                        WEECHAT_HASHTABLE_STRING,
+                                                        NULL,
+                                                        NULL);
 
 /* search irc server with name "libera" */
-void *server = weechat_hdata_search (hdata, servers, "${irc_server.name} == libera", 1);
+weechat_hashtable_set (extra_vars, "name", "libera");
+void *server = weechat_hdata_search (hdata, servers, "${irc_server.name} == ${name}",
+                                     NULL, extra_vars, NULL, 1);
 if (server)
 {
     /* ... */
 }
+weechat_hashtable_free (extra_vars);
 ----
 
 Script (Python):
@@ -17874,14 +17900,17 @@ Script (Python):
 [source,python]
 ----
 # prototipo
-def hdata_search(hdata: str, pointer: str, search: str, count: int) -> str: ...
+def hdata_search(hdata: str, pointer: str, search: str,
+                 pointers: Dict[str, str], extra_vars: Dict[str, str], options: Dict[str, str],
+                 count: int) -> str: ...
 
 # esempio
 hdata = weechat.hdata_get("irc_server")
 servers = weechat.hdata_get_list(hdata, "irc_servers")
 
 # search irc server with name "libera"
-server = weechat.hdata_search(hdata, servers, "${irc_server.name} == libera", 1)
+server = weechat.hdata_search(hdata, servers, "${irc_server.name} == ${name}",
+                              {}, {"name": "libera"}, {}, 1)
 if server:
     # ...
 ----