api: add regex replace feature in function string_eval_expression

doc/en/weechat_plugin_api.en.asciidoc

@@ -1826,11 +1826,10 @@ str3 = weechat.string_input_for_buffer("//test")  # "/test"
 
 ==== weechat_string_eval_expression
 
-_WeeChat ≥ 0.4.0, updated in 0.4.2._
+_WeeChat ≥ 0.4.0, updated in 0.4.2 and 1.1._
 
 Evaluate an expression and return result as a string.
-Special variables with format `${variable}` are expanded (see command `/eval` in
-'WeeChat User's guide').
+Special variables with format `${variable}` are expanded (see table below).
 
 [NOTE]
 Since version 1.0, nested variables are supported, for example:
@@ -1848,10 +1847,14 @@ char *weechat_string_eval_expression (const char *expr,
 
 Arguments:
 
-* 'expr': the expression to evaluate
+* 'expr': the expression to evaluate (see table below)
 * 'pointers': hashtable with pointers (keys must be string, values must be
   pointer); pointers "window" and "buffer" are automatically added if they are
-  not in hashtable (with pointer to current window/buffer) (can be NULL)
+  not in hashtable (with pointer to current window/buffer) (can be NULL):
+** 'regex': pointer to a regular expression ('regex_t' structure) compiled with
+   WeeChat function <<_weechat_string_regcomp,weechat_string_regcomp>> or
+   regcomp (see `man regcomp`); this option is similar to 'regex' in hashtable
+   'options' (below), but is used for better performance
 * 'extra_vars': extra variables that will be expanded (can be NULL)
 * 'options': a hashtable with some options (keys and values must be string)
   (can be NULL):
@@ -1861,26 +1864,118 @@ Arguments:
     parentheses are used, result is a boolean ("0" or "1")
 ** 'prefix': prefix before variables to replace (default: "${")
 ** 'suffix': suffix after variables to replace (default: "}")
+** 'regex': a regex used to replace text in 'expr' (which is then not
+   evaluated)
+** 'regex_replace': the replacement text to use with 'regex', to replace
+   text in 'expr' (the 'regex_replace' is evaluated on each match of 'regex'
+   against 'expr', until no match is found)
 
 Return value:
 
 * evaluated expression (must be freed by calling "free" after use), or NULL
   if problem (invalid expression or not enough memory)
 
+List of variables expanded in expression (by order of priority, from first
+expanded to last):
+
+[width="100%",cols="2,8,3,3",options="header"]
+|===
+| Format | Description | Examples | Results
+
+| `${name}` | Variable `name` from hashtable 'extra_vars' |
+  `${name}` | `value`
+
+| `${esc:xxx}` +
+  `${\xxx}` | String with escaped chars |
+  `${esc:prefix\tmessage}` +
+  `${\ua9}` |
+  `prefix<TAB>message` +
+  `©`
+
+| `${hide:x,value}` |
+  String with hidden chars (all chars in `value` replaced `x`) |
+  `${hide:*,password}` |
+ `********`
+
+| `${re:N}` |
+  Regex captured group: 0 = whole string matching, 1 to 99 = group captured,
+  `+` = last group captured |
+  `${re:1}` |
+  `test`
+
+| `${color:name}` |
+  WeeChat color code (the name of color has optional attributes) |
+  `${color:red}red text` +
+  `${color:*214}bold orange text` |
+  `red text` (in red) +
+  `bold orange text` (in bold orange)
+
+| `${info:name}` +
+  `${indo:name,arguments}` |
+  Info from WeeChat or a plugin, see function
+  <<_weechat_info_get,weechat_info_get>> |
+  `${info:version}` +
+  `${info:irc_nick_color_name,foo}` |
+  `1.0` +
+  `lightblue`
+
+| `${sec.data.name}` |
+  Value of the secured data `name` |
+  `${sec.data.freenode_pass}` |
+  `my_password`
+
+| `${file.section.option}` |
+  Value of the option |
+  `${weechat.look.buffer_time_format}` |
+  `%H:%M:%S`
+
+| `${name}` |
+  Value of local variable `name` in buffer |
+  `${nick}` |
+  `FlashCode`
+
+| `${hdata.var1.var2...}` +
+  `${hdata[list].var1.var2...}` |
+  Hdata value (pointers `window` and `buffer` are set by default with current
+  window/buffer) |
+  `${buffer[gui_buffers].full_name}` +
+  `${window.buffer.number}` |
+  `core.weechat` +
+  `1`
+|===
+
 C examples:
 
 [source,C]
 ----
-struct t_hashtable *options = weechat_hashtable_new (8,
-                                                     WEECHAT_HASHTABLE_STRING,
-                                                     WEECHAT_HASHTABLE_STRING,
-                                                     NULL,
-                                                     NULL);
-if (options)
-    weechat_hashtable_set (options, "type", "condition");
-char *str1 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);           /* "core.weechat" */
-char *str2 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options);  /* "1" */
-char *str3 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options);                 /* "0" */
+/* conditions */
+struct t_hashtable *options1 = weechat_hashtable_new (8,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      NULL,
+                                                      NULL);
+weechat_hashtable_set (options1, "type", "condition");
+char *str1 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options1);  /* "1" */
+char *str2 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options1);                 /* "0" */
+
+/* simple expression */
+char *str3 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);  /* "core.weechat" */
+
+/* replace with regex */
+struct t_hashtable *options2 = weechat_hashtable_new (8,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      NULL,
+                                                      NULL);
+/* add brackets around URLs */
+weechat_hashtable_set (options2, "regex", "\\w+://\\S+");
+weechat_hashtable_set (options2, "regex_replace", "[ ${re:0} ]");
+char *str4 = weechat_string_eval_expression ("test: http://weechat.org", NULL, NULL, NULL);  /* "test: [ http://weechat.org ]" */
+
+/* hide passwords */
+weechat_hashtable_set (options2, "regex", "(password=)(\\S+)");
+weechat_hashtable_set (options2, "regex_replace", "${re:1}${hide:*,${re:2}}");
+char *str5 = weechat_string_eval_expression ("password=abc password=def", NULL, NULL, NULL);  /* "password=*** password=***" */
 ----
 
 Script (Python):
@@ -1891,9 +1986,27 @@ Script (Python):
 str = weechat.string_eval_expression(expr, pointers, extra_vars, options)
 
 # examples
-str1 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {})                           # "core.weechat"
-str2 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
-str3 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"
+
+# conditions
+str1 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
+str2 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"
+
+# simple expression
+str3 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {}) # "core.weechat"
+
+# replace with regex: add brackets around URLs
+options = {
+    "regex": "\\w+://\\S+",
+    "regex_replace": "[ ${re:0} ]",
+}
+str4 = weechat.string_eval_expression("test: http://weechat.org", {}, {}, options)  # "test: [ http://weechat.org ]"
+
+# replace with regex: hide passwords
+options = {
+    "regex": "(password=)(\\S+)",
+    "regex_replace": "${re:1}${hide:*,${re:2}}",
+}
+str5 = weechat.string_eval_expression("password=abc password=def", {}, {}, options)  # "password=*** password=***"
 ----
 
 [[utf-8]]

doc/fr/weechat_plugin_api.fr.asciidoc

@@ -1858,11 +1858,11 @@ str3 = weechat.string_input_for_buffer("//test")  # "/test"
 
 ==== weechat_string_eval_expression
 
-_WeeChat ≥ 0.4.0, mis à jour dans la 0.4.2._
+_WeeChat ≥ 0.4.0, mis à jour dans la 0.4.2 et 1.1._
 
 Évaluer l'expression et retourner le résultat sous forme de chaîne.
-Les variables spéciales avec le format `${variable}` sont étendues (voir la
-commande `/eval` dans le 'Guide utilisateur WeeChat').
+Les variables spéciales avec le format `${variable}` sont étendues (voir le
+tableau ci-dessous).
 
 [NOTE]
 Depuis la version 1.0, les variables imbriquées sont supportées, par exemple :
@@ -1880,11 +1880,17 @@ char *weechat_string_eval_expression (const char *expr,
 
 Paramètres :
 
-* 'expr' : l'expression à évaluer
+* 'expr' : l'expression à évaluer (voir le tableau ci-dessous)
 * 'pointers' : table de hachage avec les pointeurs (les clés doivent être des
   chaînes, les valeurs doivent être des pointeurs); les pointeurs "window" et
   "buffer" sont automatiquement ajoutés s'ils ne sont pas dans la table de
-  hachage (avec le pointer vers fenêtre/tampon courants) (peut être NULL)
+  hachage (avec le pointer vers fenêtre/tampon courants) (peut être NULL) :
+** 'regex' : pointeur vers une expression régulière (structure 'regex_t')
+   compilée avec la fonction WeeChat
+   <<_weechat_string_regcomp,weechat_string_regcomp>> ou regcomp (voir
+   `man regcomp`) ; cette option est similaire à 'regex' dans la table de
+   hachage 'options' (ci-dessous), mais est utilisée pour de meilleures
+   performances
 * 'extra_vars' : variables additionnelles qui seront étendues (peut être NULL)
 * 'options' : table de hachage avec des options (les clés et valeurs doivent
   être des chaînes) (peut être NULL) :
@@ -1894,6 +1900,12 @@ Paramètres :
     et parenthèses sont utilisés, le résultat est un booléen ("0" ou "1")
 ** 'prefix' : préfixe avant les variables à remplacer (par défaut : "${")
 ** 'suffix' : suffixe après les variables à remplacer (par défaut : "}")
+** 'regex' : une expression regulière pour remplacer du texte dans 'expr' (qui
+   n'est alors pas évalué)
+** 'regex_replace' : le texte de remplacement à utiliser avec 'regex', pour
+   remplacer du texte dans 'expr' ('regex_replace' est évalué sur chaque
+   correspondance de 'regex' sur 'expr', jusqu'à ce que plus aucune
+   correspondance ne soit trouvée)
 
 Valeur de retour :
 
@@ -1901,20 +1913,108 @@ Valeur de retour :
   utilisation), ou NULL si problème (expression invalide ou pas assez de
   mémoire)
 
+Liste des variables étendues dans l'expression (par ordre de priorité, de la
+première étendue à la dernière) :
+
+[width="100%",cols="2,8,3,3",options="header"]
+|===
+| Format | Description | Exemples | Résultats
+
+| `${nom}` | Variable `nom` de la table de hachage 'extra_vars' |
+  `${nom}` | `valeur`
+
+| `${esc:xxx}` +
+  `${\xxx}` | Chaîne avec caractères échappés |
+  `${esc:préfixe\tmessage}` +
+  `${\ua9}` |
+  `préfixe<TAB>message` +
+  `©`
+
+| `${hide:x,valeur}` |
+  Chaîne avec les caractères masqués (tous les caractères dans `valeur`
+  remplacés par `x` |
+  `${hide:*,mot_de_passe}` |
+ `************`
+
+| `${re:N}` |
+  Groupe regex capturé : 0 = toute la chaîne correspondante, 1 à 99 = groupe
+  capturé, `+` = dernier groupe capturé |
+  `${re:1}` |
+  `test`
+
+| `${color:nom}` |
+  Code couleur WeeChat (le nom de couleur a des attributs facultatifs) |
+  `${color:red}texte rouge` +
+  `${color:*214}texte orange gras` |
+  `texte rouge` (en rouge) +
+  `texte orange gras` (en orange gras)
+
+| `${info:name}` +
+  `${indo:name,arguments}` |
+  Info de WeeChat ou d'une extension, voir la fonction
+  <<_weechat_info_get,weechat_info_get>> |
+  `${info:version}` +
+  `${info:irc_nick_color_name,foo}` |
+  `1.0` +
+  `lightblue`
+
+| `${sec.data.nom}` |
+  Valeur de la donnée sécurisée `nom` |
+  `${sec.data.freenode_pass}` |
+  `mon_mot_de_passe`
+
+| `${file.section.option}` |
+  Valeur de l'option |
+  `${weechat.look.buffer_time_format}` |
+  `%H:%M:%S`
+
+| `${nom}` |
+  Valeur de la variable locale `nom` dans le tampon |
+  `${nick}` |
+  `FlashCode`
+
+| `${hdata.var1.var2...}` +
+  `${hdata[list].var1.var2...}` |
+  Valeur d'un hdata (les pointeurs `window` et `buffer` sont définis par défaut
+  avec la fenêtre et tampon courants) |
+  `${buffer[gui_buffers].full_name}` +
+  `${window.buffer.number}` |
+  `core.weechat` +
+  `1`
+|===
+
 Exemples en C :
 
 [source,C]
 ----
-struct t_hashtable *options = weechat_hashtable_new (8,
-                                                     WEECHAT_HASHTABLE_STRING,
-                                                     WEECHAT_HASHTABLE_STRING,
-                                                     NULL,
-                                                     NULL);
-if (options)
-    weechat_hashtable_set (options, "type", "condition");
-char *str1 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);           /* "core.weechat" */
-char *str2 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options);  /* "1" */
-char *str3 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options);                 /* "0" */
+/* conditions */
+struct t_hashtable *options1 = weechat_hashtable_new (8,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      NULL,
+                                                      NULL);
+weechat_hashtable_set (options1, "type", "condition");
+char *str1 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options1);  /* "1" */
+char *str2 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options1);                 /* "0" */
+
+/* expression simple */
+char *str3 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);  /* "core.weechat" */
+
+/* remplacement avec regex */
+struct t_hashtable *options2 = weechat_hashtable_new (8,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      NULL,
+                                                      NULL);
+/* ajout de crochets autour des URLs */
+weechat_hashtable_set (options2, "regex", "\\w+://\\S+");
+weechat_hashtable_set (options2, "regex_replace", "[ ${re:0} ]");
+char *str4 = weechat_string_eval_expression ("test: http://weechat.org", NULL, NULL, NULL);  /* "test: [ http://weechat.org ]" */
+
+/* masquage des mots de passe */
+weechat_hashtable_set (options2, "regex", "(password=)(\\S+)");
+weechat_hashtable_set (options2, "regex_replace", "${re:1}${hide:*,${re:2}}");
+char *str5 = weechat_string_eval_expression ("password=abc password=def", NULL, NULL, NULL);  /* "password=*** password=***" */
 ----
 
 Script (Python) :
@@ -1925,9 +2025,27 @@ Script (Python) :
 str = weechat.string_eval_expression(expr, pointers, extra_vars, options)
 
 # exemples
-str1 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {})                           # "core.weechat"
-str2 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
-str3 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"
+
+# conditions
+str1 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
+str2 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"
+
+# expression simple
+str3 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {}) # "core.weechat"
+
+# remplacement avec regex : ajout de crochets autour des URLs
+options = {
+    "regex": "\\w+://\\S+",
+    "regex_replace": "[ ${re:0} ]",
+}
+str4 = weechat.string_eval_expression("test: http://weechat.org", {}, {}, options)  # "test: [ http://weechat.org ]"
+
+# replace with regex : masquage des mots de passe
+options = {
+    "regex": "(password=)(\\S+)",
+    "regex_replace": "${re:1}${hide:*,${re:2}}",
+}
+str5 = weechat.string_eval_expression("password=abc password=def", {}, {}, options)  # "password=*** password=***"
 ----
 
 [[utf-8]]

doc/it/weechat_plugin_api.it.asciidoc

@@ -1879,12 +1879,11 @@ str3 = weechat.string_input_for_buffer("//test")  # "/test"
 ==== weechat_string_eval_expression
 
 // TRANSLATION MISSING
-_WeeChat ≥ 0.4.0, updated in 0.4.2._
+_WeeChat ≥ 0.4.0, updated in 0.4.2 and 1.1._
 
 // TRANSLATION MISSING
 Evaluate an expression and return result as a string.
-Special variables with format `${variable}` are expanded (see command `/eval` in
-'WeeChat User's guide').
+Special variables with format `${variable}` are expanded (see table below).
 
 // TRANSLATION MISSING
 [NOTE]
@@ -1904,10 +1903,14 @@ char *weechat_string_eval_expression (const char *expr,
 Argomenti:
 
 // TRANSLATION MISSING
-* 'expr': the expression to evaluate
+* 'expr': the expression to evaluate (see table below)
 * 'pointers': hashtable with pointers (keys must be string, values must be
   pointer); pointers "window" and "buffer" are automatically added if they are
-  not in hashtable (with pointer to current window/buffer) (can be NULL)
+  not in hashtable (with pointer to current window/buffer) (can be NULL):
+** 'regex': pointer to a regular expression ('regex_t' structure) compiled with
+   WeeChat function <<_weechat_string_regcomp,weechat_string_regcomp>> or
+   regcomp (see `man regcomp`); this option is similar to 'regex' in hashtable
+   'options' (below), but is used for better performance
 * 'extra_vars': extra variables that will be expanded (can be NULL)
 * 'options': a hashtable with some options (keys and values must be string)
   (can be NULL):
@@ -1917,6 +1920,11 @@ Argomenti:
     parentheses are used, result is a boolean ("0" or "1")
 ** 'prefix': prefix before variables to replace (default: "${")
 ** 'suffix': suffix after variables to replace (default: "}")
+** 'regex': a regex used to replace text in 'expr' (which is then not
+   evaluated)
+** 'regex_replace': the replacement text to use with 'regex', to replace
+   text in 'expr' (the 'regex_replace' is evaluated on each match of 'regex'
+   against 'expr', until no match is found)
 
 Valore restituito:
 
@@ -1924,20 +1932,109 @@ Valore restituito:
 * evaluated expression (must be freed by calling "free" after use), or NULL
   if problem (invalid expression or not enough memory)
 
+// TRANSLATION MISSING
+List of variables expanded in expression (by order of priority, from first
+expanded to last):
+
+// TRANSLATION MISSING
+[width="100%",cols="2,8,3,3",options="header"]
+|===
+| Format | Description | Examples | Results
+
+| `${name}` | Variable `name` from hashtable 'extra_vars' |
+  `${name}` | `value`
+
+| `${esc:xxx}` +
+  `${\xxx}` | String with escaped chars |
+  `${esc:prefix\tmessage}` +
+  `${\ua9}` |
+  `prefix<TAB>message` +
+  `©`
+
+| `${hide:x,value}` |
+  String with hidden chars (all chars in `value` replaced `x`) |
+  `${hide:*,password}` |
+ `********`
+
+| `${re:N}` |
+  Regex captured group: 0 = whole string matching, 1 to 99 = group captured,
+  `+` = last group captured |
+  `${re:1}` |
+  `test`
+
+| `${color:name}` |
+  WeeChat color code (the name of color has optional attributes) |
+  `${color:red}red text` +
+  `${color:*214}bold orange text` |
+  `red text` (in red) +
+  `bold orange text` (in bold orange)
+
+| `${info:name}` +
+  `${indo:name,arguments}` |
+  Info from WeeChat or a plugin, see function
+  <<_weechat_info_get,weechat_info_get>> |
+  `${info:version}` +
+  `${info:irc_nick_color_name,foo}` |
+  `1.0` +
+  `lightblue`
+
+| `${sec.data.name}` |
+  Value of the secured data `name` |
+  `${sec.data.freenode_pass}` |
+  `my_password`
+
+| `${file.section.option}` |
+  Value of the option |
+  `${weechat.look.buffer_time_format}` |
+  `%H:%M:%S`
+
+| `${name}` |
+  Value of local variable `name` in buffer |
+  `${nick}` |
+  `FlashCode`
+
+| `${hdata.var1.var2...}` +
+  `${hdata[list].var1.var2...}` |
+  Hdata value (pointers `window` and `buffer` are set by default with current
+  window/buffer) |
+  `${buffer[gui_buffers].full_name}` +
+  `${window.buffer.number}` |
+  `core.weechat` +
+  `1`
+|===
+
 Esempi in C:
 
 [source,C]
 ----
-struct t_hashtable *options = weechat_hashtable_new (8,
-                                                     WEECHAT_HASHTABLE_STRING,
-                                                     WEECHAT_HASHTABLE_STRING,
-                                                     NULL,
-                                                     NULL);
-if (options)
-    weechat_hashtable_set (options, "type", "condition");
-char *str1 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);           /* "core.weechat" */
-char *str2 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options);  /* "1" */
-char *str3 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options);                 /* "0" */
+/* conditions */
+struct t_hashtable *options1 = weechat_hashtable_new (8,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      NULL,
+                                                      NULL);
+weechat_hashtable_set (options1, "type", "condition");
+char *str1 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options1);  /* "1" */
+char *str2 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options1);                 /* "0" */
+
+/* simple expression */
+char *str3 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);  /* "core.weechat" */
+
+/* replace with regex */
+struct t_hashtable *options2 = weechat_hashtable_new (8,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      NULL,
+                                                      NULL);
+/* add brackets around URLs */
+weechat_hashtable_set (options2, "regex", "\\w+://\\S+");
+weechat_hashtable_set (options2, "regex_replace", "[ ${re:0} ]");
+char *str4 = weechat_string_eval_expression ("test: http://weechat.org", NULL, NULL, NULL);  /* "test: [ http://weechat.org ]" */
+
+/* hide passwords */
+weechat_hashtable_set (options2, "regex", "(password=)(\\S+)");
+weechat_hashtable_set (options2, "regex_replace", "${re:1}${hide:*,${re:2}}");
+char *str5 = weechat_string_eval_expression ("password=abc password=def", NULL, NULL, NULL);  /* "password=*** password=***" */
 ----
 
 Script (Python):
@@ -1948,9 +2045,27 @@ Script (Python):
 str = weechat.string_eval_expression(expr, pointers, extra_vars, options)
 
 # esempi
-str1 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {})                           # "core.weechat"
-str2 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
-str3 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"
+
+# conditions
+str1 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
+str2 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"
+
+# simple expression
+str3 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {}) # "core.weechat"
+
+# replace with regex: add brackets around URLs
+options = {
+    "regex": "\\w+://\\S+",
+    "regex_replace": "[ ${re:0} ]",
+}
+str4 = weechat.string_eval_expression("test: http://weechat.org", {}, {}, options)  # "test: [ http://weechat.org ]"
+
+# replace with regex: hide passwords
+options = {
+    "regex": "(password=)(\\S+)",
+    "regex_replace": "${re:1}${hide:*,${re:2}}",
+}
+str5 = weechat.string_eval_expression("password=abc password=def", {}, {}, options)  # "password=*** password=***"
 ----
 
 [[utf-8]]

doc/ja/weechat_plugin_api.ja.asciidoc

@@ -1822,11 +1822,12 @@ str3 = weechat.string_input_for_buffer("//test")  # "/test"
 
 ==== weechat_string_eval_expression
 
-_WeeChat バージョン 0.4.0 以上で利用可、バージョン 0.4.2 で更新。_
+// TRANSLATION MISSING
+_WeeChat ≥ 0.4.0, updated in 0.4.2 and 1.1._
 
-式を評価して文字列として返す。`${variable}`
-という書式で書かれた特殊変数は展開される
-('WeeChat ユーザガイド' のコマンド `/eval` を参照)。
+// TRANSLATION MISSING
+Evaluate an expression and return result as a string.
+Special variables with format `${variable}` are expanded (see table below).
 
 [NOTE]
 バージョン 1.0 以降、入れ子変数を使えるようになりました、例:
@@ -1844,10 +1845,16 @@ char *weechat_string_eval_expression (const char *expr,
 
 引数:
 
-* 'expr': 評価する式
+// TRANSLATION MISSING
+* 'expr': 評価する式 (see table below)
 * 'pointers': ポインタを含むハッシュテーブル (キーは文字列、値はポインタ);
   (現在のウィンドウやバッファへのポインタを持つ) ハッシュテーブルが "window" と
-  "buffer" ポインタを持たない場合はこれらは自動的に追加される (NULL でも可)
+  "buffer" ポインタを持たない場合はこれらは自動的に追加される (NULL でも可):
+// TRANSLATION MISSING
+** 'regex': pointer to a regular expression ('regex_t' structure) compiled with
+   WeeChat function <<_weechat_string_regcomp,weechat_string_regcomp>> or
+   regcomp (see `man regcomp`); this option is similar to 'regex' in hashtable
+   'options' (below), but is used for better performance
 * 'extra_vars': 展開される追加変数 (NULL でも可)
 * 'options': いくつかのオプションを含むハッシュテーブル (キーと値は必ず文字列)
   (NULL でも可):
@@ -1857,39 +1864,155 @@ char *weechat_string_eval_expression (const char *expr,
     演算子と括弧が使われます、結果はブール値 ("0" または "1") です
 ** 'prefix': 置換する変数のプレフィックス (デフォルト: "${")
 ** 'suffix': 置換する変数のサフィックス (デフォルト: "}")
+// TRANSLATION MISSING
+** 'regex': a regex used to replace text in 'expr' (which is then not
+   evaluated)
+// TRANSLATION MISSING
+** 'regex_replace': the replacement text to use with 'regex', to replace
+   text in 'expr' (the 'regex_replace' is evaluated on each match of 'regex'
+   against 'expr', until no match is found)
 
 戻り値:
 
 * 評価された式 (使用後には必ず "free" を呼び出して領域を開放してください)、失敗した場合は
   NULL (式が不正な場合やメモリが不足している場合)
 
+// TRANSLATION MISSING
+List of variables expanded in expression (by order of priority, from first
+expanded to last):
+
+// TRANSLATION MISSING
+[width="100%",cols="2,8,3,3",options="header"]
+|===
+| Format | Description | Examples | Results
+
+| `${name}` | Variable `name` from hashtable 'extra_vars' |
+  `${name}` | `value`
+
+| `${esc:xxx}` +
+  `${\xxx}` | String with escaped chars |
+  `${esc:prefix\tmessage}` +
+  `${\ua9}` |
+  `prefix<TAB>message` +
+  `©`
+
+| `${hide:x,value}` |
+  String with hidden chars (all chars in `value` replaced `x`) |
+  `${hide:*,password}` |
+ `********`
+
+| `${re:N}` |
+  Regex captured group: 0 = whole string matching, 1 to 99 = group captured,
+  `+` = last group captured |
+  `${re:1}` |
+  `test`
+
+| `${color:name}` |
+  WeeChat color code (the name of color has optional attributes) |
+  `${color:red}red text` +
+  `${color:*214}bold orange text` |
+  `red text` (in red) +
+  `bold orange text` (in bold orange)
+
+| `${info:name}` +
+  `${indo:name,arguments}` |
+  Info from WeeChat or a plugin, see function
+  <<_weechat_info_get,weechat_info_get>> |
+  `${info:version}` +
+  `${info:irc_nick_color_name,foo}` |
+  `1.0` +
+  `lightblue`
+
+| `${sec.data.name}` |
+  Value of the secured data `name` |
+  `${sec.data.freenode_pass}` |
+  `my_password`
+
+| `${file.section.option}` |
+  Value of the option |
+  `${weechat.look.buffer_time_format}` |
+  `%H:%M:%S`
+
+| `${name}` |
+  Value of local variable `name` in buffer |
+  `${nick}` |
+  `FlashCode`
+
+| `${hdata.var1.var2...}` +
+  `${hdata[list].var1.var2...}` |
+  Hdata value (pointers `window` and `buffer` are set by default with current
+  window/buffer) |
+  `${buffer[gui_buffers].full_name}` +
+  `${window.buffer.number}` |
+  `core.weechat` +
+  `1`
+|===
+
 C 言語での使用例:
 
+// TRANSLATION MISSING
 [source,C]
 ----
-struct t_hashtable *options = weechat_hashtable_new (8,
-                                                     WEECHAT_HASHTABLE_STRING,
-                                                     WEECHAT_HASHTABLE_STRING,
-                                                     NULL,
-                                                     NULL);
-if (options)
-    weechat_hashtable_set (options, "type", "condition");
-char *str1 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);           /* "core.weechat" */
-char *str2 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options);  /* "1" */
-char *str3 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options);                 /* "0" */
+/* conditions */
+struct t_hashtable *options1 = weechat_hashtable_new (8,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      NULL,
+                                                      NULL);
+weechat_hashtable_set (options1, "type", "condition");
+char *str1 = weechat_string_eval_expression ("${window.win_width} > 100", NULL, NULL, options1);  /* "1" */
+char *str2 = weechat_string_eval_expression ("abc =~ def", NULL, NULL, options1);                 /* "0" */
+
+/* simple expression */
+char *str3 = weechat_string_eval_expression ("${buffer.full_name}", NULL, NULL, NULL);  /* "core.weechat" */
+
+/* replace with regex */
+struct t_hashtable *options2 = weechat_hashtable_new (8,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      WEECHAT_HASHTABLE_STRING,
+                                                      NULL,
+                                                      NULL);
+/* add brackets around URLs */
+weechat_hashtable_set (options2, "regex", "\\w+://\\S+");
+weechat_hashtable_set (options2, "regex_replace", "[ ${re:0} ]");
+char *str4 = weechat_string_eval_expression ("test: http://weechat.org", NULL, NULL, NULL);  /* "test: [ http://weechat.org ]" */
+
+/* hide passwords */
+weechat_hashtable_set (options2, "regex", "(password=)(\\S+)");
+weechat_hashtable_set (options2, "regex_replace", "${re:1}${hide:*,${re:2}}");
+char *str5 = weechat_string_eval_expression ("password=abc password=def", NULL, NULL, NULL);  /* "password=*** password=***" */
 ----
 
 スクリプト (Python) での使用例:
 
+// TRANSLATION MISSING
 [source,python]
 ----
 # プロトタイプ
 str = weechat.string_eval_expression(expr, pointers, extra_vars, options)
 
 # 例s
-str1 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {})                           # "core.weechat"
-str2 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
-str3 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"
+
+# conditions
+str1 = weechat.string_eval_expression("${window.win_width} > 100", {}, {}, {"type": "condition"})  # "1"
+str2 = weechat.string_eval_expression("abc =~ def", {}, {}, {"type": "condition"})                 # "0"
+
+# simple expression
+str3 = weechat.string_eval_expression("${buffer.full_name}", {}, {}, {}) # "core.weechat"
+
+# replace with regex: add brackets around URLs
+options = {
+    "regex": "\\w+://\\S+",
+    "regex_replace": "[ ${re:0} ]",
+}
+str4 = weechat.string_eval_expression("test: http://weechat.org", {}, {}, options)  # "test: [ http://weechat.org ]"
+
+# replace with regex: hide passwords
+options = {
+    "regex": "(password=)(\\S+)",
+    "regex_replace": "${re:1}${hide:*,${re:2}}",
+}
+str5 = weechat.string_eval_expression("password=abc password=def", {}, {}, options)  # "password=*** password=***"
 ----
 
 [[utf-8]]