summaryrefslogtreecommitdiff
path: root/doc/en/weechat_plugin_api.en.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/en/weechat_plugin_api.en.adoc')
-rw-r--r--doc/en/weechat_plugin_api.en.adoc34
1 files changed, 29 insertions, 5 deletions
diff --git a/doc/en/weechat_plugin_api.en.adoc b/doc/en/weechat_plugin_api.en.adoc
index d6ff39a3c..ea953ffd7 100644
--- a/doc/en/weechat_plugin_api.en.adoc
+++ b/doc/en/weechat_plugin_api.en.adoc
@@ -17135,7 +17135,7 @@ if buffer:
==== hdata_search
-_WeeChat ≥ 0.4.1._
+_WeeChat ≥ 0.4.1, updated in 3.4._
Search element in a list: the expression _search_ is evaluated for each element
in list, until element is found (or end of list).
@@ -17144,7 +17144,9 @@ Prototype:
[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);
----
Arguments:
@@ -17155,9 +17157,20 @@ Arguments:
hdata (and this pointer changes for each element in list); for help on
expression, see the
link:weechat_user.en.html#command_weechat_eval[WeeChat user's guide / Command /eval]
+* _pointers_: hashtable for call to function
+ <<_string_eval_expression,string_eval_expression>>
+* _extra_vars_: hashtable for call to function
+ <<_string_eval_expression,string_eval_expression>>
+* _options_: hashtable for call to function
+ <<_string_eval_expression,string_eval_expression>>
* _move_: number of jump(s) to execute after unsuccessful search (negative or
positive integer, different from 0)
+[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).
+
Return value:
* pointer to element found, NULL if not found
@@ -17168,13 +17181,21 @@ C example:
----
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):
@@ -17182,14 +17203,17 @@ Script (Python):
[source,python]
----
# prototype
-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: ...
# example
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:
# ...
----