api: add split of string and shell arguments in evaluation of expressions

Split of string: ${split:number,separators,flags,xxx}
Split of shell arguments: ${split_shell:number,xxx}

1 files changed, 148 insertions, 138 deletions

diff --git a/doc/de/includes/autogen_user_commands.de.adoc b/doc/de/includes/autogen_user_commands.de.adoc
index dfc396e08..17c1ee283 100644
--- a/doc/de/includes/autogen_user_commands.de.adoc
+++ b/doc/de/includes/autogen_user_commands.de.adoc
@@ -1337,83 +1337,85 @@ infolists: zeigt Information über die Infolists an
 /eval  [-n|-s] [-d] <expression>
        [-n] [-d [-d]] -c <expression1> <operator> <expression2>
 
-        -n: gibt das Ergebnis aus, ohne dass dieses in den Buffer gesendet wird (debug Modus)
-        -s: teilt Ausdrücke, bevor sie evaluiert werden (mehrere Befehle können durch Semikolon getrennt werden)
-        -d: eine Debug-Ausgabe nach Auswertung anzeigen (Nutzung von zwei -d: ausführliche Debug-Ausgabe)
-        -c: Auswertung als Bedingung: nutzt Operatoren und runde Klammern, Rückgabewert als Boolean-Wert ("0" oder "1")
-expression: Ausdruck welcher verarbeitet werden soll. Variablen im Format ${variable} werden ersetzt (siehe unten); mehrere Befehle werden durch ein Semikolon voneinander getrennt
-  operator: ein logischer oder vergleichender Operand:
-            - logische Operanden:
-                &&  boolean "und"
-                ||  boolean "oder"
-            - vergleichende Operanden:
-                ==  gleich
-                !=  ungleich
-                <=  kleiner oder gleich
-                <   kleiner
-                >=  größer oder gleich
-                >   größer
-                =~  stimmt mit regulärem POSIX Ausdruck überein
-                !~  stimmt NICHT mit regulärem POSIX Ausdruck überein
-                ==*  stimmt mit Maske überein (Platzhalter "*" ist erlaubt)
-                !!*  stimmt mit Maske NICHT überein (Platzhalter "*" ist erlaubt)
-                =*   stimmt mit Maske überein, Groß- und Kleinschreibung wird nicht beachtet (Platzhalter "*" ist erlaubt)
-                !*   stimmt mit Maske NICHT überein, Groß- und Kleinschreibung wird nicht beachtet (Platzhalter "*" ist erlaubt)
-                ==-  ist enthalten, Groß- und Kleinschreibung wird beachtet
-                !!-  ist NICHT enthalten, Groß- und Kleinschreibung wird beachtet
-                =-   ist enthalten, Groß- und Kleinschreibung wird nicht beachtet
-                !-   ist NICHT enthalten, Groß- und Kleinschreibung wird nicht beachtet
-
-Ein Ausdruck gilt als "wahr" sofern das Ergebnis weder NULL, nicht leer und von "0" abweichend ist.
-Für einen Vergleich werden Fließkommazahlen genutzt, insofern es sich bei beiden Ausdrücken um gültige Zahlen handelt, folgende Formate werden unterstützt:
-  - Integer (Beispiele: 5, -7)
-  - Fließkommazahl (Beispiele: 5.2, -7.5, 2.83e-2)
-  - hexadezimale Zahl (Beispiele: 0xA3, -0xA3)
-Um einen Vergleich zwischen zwei Zeichenketten zu erzwingen, müssen die Ausdrücke in Anführungszeichen gesetzt werden, zum Beispiel:
+        -n: display result without sending it to buffer (debug mode)
+        -s: split expression before evaluating it (many commands can be separated by semicolons)
+        -d: display debug output after evaluation (with two -d: more verbose debug)
+        -c: evaluate as condition: use operators and parentheses, return a boolean value ("0" or "1")
+expression: expression to evaluate, variables with format ${variable} are replaced (see below); many commands can be separated by semicolons
+  operator: a logical or comparison operator:
+            - logical operators:
+                &&   boolean "and"
+                ||   boolean "or"
+            - comparison operators:
+                ==   equal
+                !=   not equal
+                <=   less or equal
+                <    less
+                >=   greater or equal
+                >    greater
+                =~   is matching POSIX extended regex
+                !~   is NOT matching POSIX extended regex
+                ==*  is matching mask, case sensitive (wildcard "*" is allowed)
+                !!*  is NOT matching mask, case sensitive (wildcard "*" is allowed)
+                =*   is matching mask, case insensitive (wildcard "*" is allowed)
+                !*   is NOT matching mask, case insensitive (wildcard "*" is allowed)
+                ==-  is included, case sensitive
+                !!-  is NOT included, case sensitive
+                =-   is included, case insensitive
+                !-   is NOT included, case insensitive
+
+An expression is considered as "true" if it is not NULL, not empty, and different from "0".
+The comparison is made using floating point numbers if the two expressions are valid numbers, with one of the following formats:
+  - integer (examples: 5, -7)
+  - floating point number (examples: 5.2, -7.5, 2.83e-2)
+  - hexadecimal number (examples: 0xA3, -0xA3)
+To force a string comparison, you can add double quotes around each expression, for example:
   50 > 100      ==> 0
   "50" > "100"  ==> 1
 
-Einige Variablen werden im Ausdruck mittels der Formatierung ${variable} ersetzt. Mögliche Variablen sind, nach Reihenfolge ihrer Priorität:
-  1. die Zeichenfolge selbst ohne Auswertung (Format: "raw:xxx")\n
-  2. eine evaluierte Teilzeichenkette (Format: "eval:xxx")
-  3. eine evaluierte Bedingung (Format: "eval_cond:xxx")
-  4. eine Zeichenkette mit Escapesequenzen (Format: "esc:xxx" oder "\xxx")
-  5. Zeichen, die in einer Zeichenkette nicht dargestellt werden sollen (Format: "hide:Zeichen,Zeichenkette")
-  6. eine Zeichenkette mit einer maximalen Anzahl an Zeichen (Format: "cut:max,suffix,string" oder "cut:+max,suffix,string")
-     oder maximale Anzahl an Zeichen die auf dem Bildschirm angezeigt werden sollen (Format: "cutscr:Max,Suffix,Zeichenkette oder "cutscr:+Max,Suffix,Zeichenkette")
-  7. eine Zeichenkette umkehren (Format: "rev:xxx" oder "revscr:xxx")
-  8. eine Zeichenkette wiederholen (Format: "repeat:Anzahl,Zeichenkette")
-  9. Länge einer Zeichenkette (Format: "length:xxx" oder "lengthscr:xxx")
-  10. eine Farbe (Format: "color:xxx", siehe "Anleitung für API Erweiterung", Funktion "color")
-  11. zum modifizieren (Format: "modifier:name,data,string")
-  12. eine Info (Format: "Info:Name,Argumente", Argumente sind optional)
-  13. eine Basis 16/32/64 kodierte / dekodierte Zeichenfolge (Format: "base_encode:base,xxx" oder "base_decode:base,xxx")
-  14. aktuelles Datum/Uhrzeit (Format: "date" oder "date:format")
-  15. eine Umgebungsvariable (Format: "env:XXX")
-  16. ein Dreifachoperand (Format: "if:Bedingung?Wert_falls_wahr:Wert_falls_unwahr")
-  17. Ergebnis eines Ausdrucks mit Klammern und Operatoren + - * / // % ** (Format: "calc:xxx")
-  19. eine übersetzte Zeichenkette (Format: "translate:xxx")
-  18. eine zufällige ganze Zahl (Format: "random:min,max")
-  20. eine Option (Format: "file.section.option")
-  21. eine lokale Variable eines Buffers
-  22. ein(e) hdata - Name/Variable (der Wert wird automatisch in eine Zeichenkette konvertiert), standardmäßig wird für "window" und "buffer" das aktuelle Fenster/Buffer verwendet.
-Das Format für hdata kann wie folgt aufgebaut sein:
-  hdata.var1.var2...: startet mit hdata (der Pointer muss bekannt sein) und fragt eine Variable nach der anderen ab (weitere hdata können folgen)
-  hdata[list].var1.var2...: startet hdata mittels einer Liste, zum Beispiel:
-    ${buffer[gui_buffers].full_name}: der vollständige Name des ersten Buffers, in der verknüpften Liste aller Buffer
-    ${plugin[weechat_plugins].name}: Name der ersten Erweiterung, in der verknüpften Liste aller Erweiterungen
-  hdata[pointer].var1.var2...: startet hdata mittels einem Pointer, zum Beispiel:
-    ${buffer[0x1234abcd].full_name}: vollständiger Name eines Buffers und des dazugehörigen Pointers (kann in triggern benutzt werden)
-    ${buffer[my_pointer].full_name}: vollständiger Name des Buffers mit dem entsprechenden Pointernamen (kann in Triggern verwendet werden)
-Die vorhandenen Namen für hdata und Variablen sind in der "Anleitung für API Erweiterung", Bereich "weechat_hdata_get". beschrieben
-
-Beispiele (einfache Zeichenketten):
+Some variables are replaced in expression, using the format ${variable}, variable can be, by order of priority:
+  1. the string itself without evaluation (format: "raw:xxx")
+  2. an evaluated sub-string (format: "eval:xxx")
+  3. an evaluated condition (format: "eval_cond:xxx")
+  4. a string with escaped chars (format: "esc:xxx" or "\xxx")
+  5. a string with chars to hide (format: "hide:char,string")
+  6. a string with max chars (format: "cut:max,suffix,string" or "cut:+max,suffix,string")
+     or max chars displayed on screen (format: "cutscr:max,suffix,string" or "cutscr:+max,suffix,string")
+  7. a reversed string (format: "rev:xxx" or "revscr:xxx")
+  8. a repeated string (format: "repeat:count,string")
+  9. length of a string (format: "length:xxx" or "lengthscr:xxx")
+  10. split of a string (format: "split:number,separators,flags,xxx")
+  11. split of shell argmuents (format: "split_shell:number,xxx")
+  12. a color (format: "color:xxx", see "Plugin API reference", function "color")
+  13. a modifier (format: "modifier:name,data,string")
+  14. an info (format: "info:name,arguments", arguments are optional)
+  15. a base 16/32/64 encoded/decoded string (format: "base_encode:base,xxx" or "base_decode:base,xxx")
+  16. current date/time (format: "date" or "date:format")
+  17. an environment variable (format: "env:XXX")
+  18. a ternary operator (format: "if:condition?value_if_true:value_if_false")
+  19. result of an expression with parentheses and operators + - * / // % ** (format: "calc:xxx")
+  20. a random integer number (format: "random:min,max")
+  21. a translated string (format: "translate:xxx")
+  22. an option (format: "file.section.option")
+  23. a local variable in buffer
+  24. a hdata name/variable (the value is automatically converted to string), by default "window" and "buffer" point to current window/buffer.
+Format for hdata can be one of following:
+  hdata.var1.var2...: start with a hdata (pointer must be known), and ask variables one after one (other hdata can be followed)
+  hdata[list].var1.var2...: start with a hdata using a list/pointer/pointer name, for example:
+    ${buffer[gui_buffers].full_name}: full name of first buffer in linked list of buffers
+    ${plugin[weechat_plugins].name}: name of first plugin in linked list of plugins
+  hdata[pointer].var1.var2...: start with a hdata using a pointer, for example:
+    ${buffer[0x1234abcd].full_name}: full name of the buffer with this pointer (can be used in triggers)
+    ${buffer[my_pointer].full_name}: full name of the buffer with this pointer name (can be used in triggers)
+For name of hdata and variables, please look at "Plugin API reference", function "weechat_hdata_get".
+
+Examples (simple strings):
   /eval -n ${raw:${info:version}}                ==> ${info:version}
   /eval -n ${eval_cond:${window.win_width}>100}  ==> 1
   /eval -n ${info:version}                       ==> 0.4.3
   /eval -n ${env:HOME}                           ==> /home/user
   /eval -n ${weechat.look.scroll_amount}         ==> 3
-  /eval -n ${sec.data.password}                  ==> geheim
+  /eval -n ${sec.data.password}                  ==> secret
   /eval -n ${window}                             ==> 0x2549aa0
   /eval -n ${window.buffer}                      ==> 0x2549320
   /eval -n ${window.buffer.full_name}            ==> core.weechat
@@ -1427,23 +1429,31 @@ Beispiele (einfache Zeichenketten):
   /eval -n ${rev:Hello}                          ==> olleH
   /eval -n ${repeat:5,-}                         ==> -----
   /eval -n ${length:test}                        ==> 4
+  /eval -n ${split:1,,,abc,def,ghi}              ==> abc
+  /eval -n ${split:-1,,,abc,def,ghi}             ==> ghi
+  /eval -n ${split:count,,,abc,def,ghi}          ==> 3
+  /eval -n ${split:random,,,abc,def,ghi}         ==> def
+  /eval -n ${split_shell:1,"arg 1" arg2}       ==> arg 1
+  /eval -n ${split_shell:-1,"arg 1" arg2}      ==> arg2
+  /eval -n ${split_shell:count,"arg 1" arg2}   ==> 2
+  /eval -n ${split_shell:random,"arg 1" arg2}  ==> arg2
   /eval -n ${calc:(5+2)*3}                       ==> 21
   /eval -n ${random:0,10}                        ==> 3
   /eval -n ${base_encode:64,test}                ==> dGVzdA==
   /eval -n ${base_decode:64,dGVzdA==}            ==> test
-  /eval -n ${translate:Plugin}                   ==> Erweiterung
+  /eval -n ${translate:Plugin}                   ==> Extension
 
-Beispiele (Bedingungen):
-  /eval -n -c ${window.buffer.number} > 2  ==> 0
-  /eval -n -c ${window.win_width} > 100    ==> 1
-  /eval -n -c (8 > 12) || (5 > 2)          ==> 1
-  /eval -n -c (8 > 12) && (5 > 2)          ==> 0
-  /eval -n -c abcd =~ ^ABC                 ==> 1
-  /eval -n -c abcd =~ (?-i)^ABC            ==> 0
-  /eval -n -c abcd =~ (?-i)^abc            ==> 1
-  /eval -n -c abcd !~ abc                  ==> 0
-  /eval -n -c abcd =* a*d                  ==> 1
-  /eval -n -c abcd =- bc                   ==> 1
+Examples (conditions):
+  /eval -n -c ${window.buffer.number} > 2 ==> 0
+  /eval -n -c ${window.win_width} > 100   ==> 1
+  /eval -n -c (8 > 12) || (5 > 2)         ==> 1
+  /eval -n -c (8 > 12) && (5 > 2)         ==> 0
+  /eval -n -c abcd =~ ^ABC                ==> 1
+  /eval -n -c abcd =~ (?-i)^ABC           ==> 0
+  /eval -n -c abcd =~ (?-i)^abc           ==> 1
+  /eval -n -c abcd !~ abc                 ==> 0
+  /eval -n -c abcd =* a*d                 ==> 1
+  /eval -n -c abcd =- bc                  ==> 1
 ----
 
 [[command_weechat_filter]]
@@ -1545,63 +1555,63 @@ value: Anzahl der gewünschten Einträgen im Befehlsverlauf anzeigen
 ----
 /input  <action> [<arguments>]
 
-list of actions:
-  return: simulate key "enter"
-  complete_next: complete word with next completion
-  complete_previous: complete word with previous completion
-  search_text_here: search text in buffer at current position
-  search_text: search text in buffer
-  search_switch_case: switch exact case for search
-  search_switch_regex: switch search type: string/regular expression
-  search_switch_where: switch search in messages/prefixes
-  search_previous: search previous line
-  search_next: search next line
-  search_stop_here: stop search at current position
-  search_stop: stop search
-  delete_previous_char: delete previous char
-  delete_next_char: delete next char
-  delete_previous_word: delete previous word
-  delete_next_word: delete next word
-  delete_beginning_of_line: delete from beginning of line until cursor
-  delete_end_of_line: delete from cursor until end of line
-  delete_line: delete entire line
-  clipboard_paste: paste from the internal clipboard
-  transpose_chars: transpose two chars
-  undo: undo last command line action
-  redo: redo last command line action
-  move_beginning_of_line: move cursor to beginning of line
-  move_end_of_line: move cursor to end of line
-  move_previous_char: move cursor to previous char
-  move_next_char: move cursor to next char
-  move_previous_word: move cursor to previous word
-  move_next_word: move cursor to next word
-  history_previous: recall previous command in current buffer history
-  history_next: recall next command in current buffer history
-  history_global_previous: recall previous command in global history
-  history_global_next: recall next command in global history
-  jump_smart: jump to next buffer with activity
-  jump_last_buffer_displayed: jump to last buffer displayed (before last jump to a buffer)
-  jump_previously_visited_buffer: jump to previously visited buffer
-  jump_next_visited_buffer: jump to next visited buffer
-  hotlist_clear: clear hotlist (optional argument: "lowest" to clear only lowest level in hotlist, "highest" to clear only highest level in hotlist, or level mask: integer which is a combination of 1=join/part, 2=message, 4=private, 8=highlight)
-  hotlist_remove_buffer: remove current buffer from hotlist
-  hotlist_restore_buffer: restore latest hotlist removed in the current buffer
-  hotlist_restore_all: restore latest hotlist removed in all buffers
-  grab_key: grab a key (optional argument: delay for end of grab, default is 500 milliseconds)
-  grab_key_command: grab a key with its associated command (optional argument: delay for end of grab, default is 500 milliseconds)
-  grab_mouse: grab mouse event code
-  grab_mouse_area: grab mouse event code with area
-  set_unread: set unread marker for all buffers
-  set_unread_current_buffer: set unread marker for current buffer
-  switch_active_buffer: switch to next merged buffer
-  switch_active_buffer_previous: switch to previous merged buffer
-  zoom_merged_buffer: zoom on merged buffer
-  insert: insert text in command line (escaped chars are allowed, see /help print)
-  send: send text to the buffer
-  paste_start: start paste (bracketed paste mode)
-  paste_stop: stop paste (bracketed paste mode)
-
-This command is used by key bindings or plugins.
+Auflistung der möglichen Aktionen:
+  return: simuliert die "enter" Taste
+  complete_next: vervollständigt Wort mit nächster Komplettierung
+  complete_previous: vervollständigt Word mit vorheriger Komplettierung
+  search_text_here: Textsuche ab aktueller Position
+  search_text: Textsuche im Buffer
+  search_switch_case: schaltet Groß-/Kleinschreibung ein und aus
+  search_switch_regex: Wechsel des Suchmodus: einfache Textsuche/reguläre Ausdrücke
+  search_switch_where: wechselt Suche in Nachricht/Präfix
+  search_previous: sucht vorheriger Zeile
+  search_next: sucht nächste Zeile
+  search_stop_here: beendet Suche ab aktueller Position
+  search_stop: suche beenden
+  delete_previous_char: entfernt vorheriges Zeichen
+  delete_next_char: entfernt nächstes Zeichen
+  delete_previous_word: entfernt vorheriges Wort
+  delete_next_word: entfernt nächstes Wort
+  delete_beginning_of_line: entfernt alle Zeichen ab Zeilenanfang bis zum Cursor
+  delete_end_of_line: entfernt alle Zeichen ab Cursor bis zum Ende der Zeile
+  delete_line: löscht die komplette Eingabezeile
+  clipboard_paste: fügt Zeichenkette aus der internen Zwischenablage ein
+  transpose_chars: Zeichen austauschen
+  undo: letzten Befehl in der Eingabezeile rückgängig machen
+  redo: letzten Befehl in der Eingabezeile wiederherstellen
+  move_beginning_of_line: springt an den Anfang der Eingabezeile
+  move_end_of_line: springt ans Ende der Eingabezeile
+  move_previous_char: setzt den Cursor eine Position nach links
+  move_next_char: setzt den Cursor eine Position nach rechts
+  move_previous_word: springt zum Anfang des vorherigen Wortes, in der Eingabezeile
+  move_next_word: springt zum Anfang des nächsten Wortes, in der Eingabezeile
+  history_previous: ruft vorherigen Befehl oder Nachricht aus dem Befehlsspeicher auf (im Such-Modus: rückwärts suchen)
+  history_next: ruft nächsten Befehl oder Nachricht aus dem Befehlsspeicher auf (im Such-Modus: vorwärts suchen)
+  history_global_previous: ruft vorherigen Befehl/Nachricht aus dem globalen Befehlsspeicher auf (für alle Buffer)
+  history_global_next: ruft nächsten Befehl/Nachricht aus dem globalen Befehlsspeicher auf (für alle Buffer)
+  jump_smart: wechselt zum nächsten Buffer mit Aktivität (nach Priorität: highlight, Nachricht, …)
+  jump_last_buffer_displayed: wechselt zum jeweils zuletzt angezeigten Buffer
+  jump_previously_visited_buffer: springt zum letzten besuchten Buffer
+  jump_next_visited_buffer: springt zum nächsten besuchten Buffer
+  hotlist_clear: löscht Hotlist (Aktivitätsanzeige für die Buffer), (optionales Argument: "lowest" löscht den niedrigsten Eintrag der Hotlist, "highest" löscht den höchsten Eintrag der Hotlist, oder eine integer Maske: eine Kombination aus 1=join/part, 2=Nachricht,4=privat,8=highlight)
+  hotlist_remove_buffer: entferne aktuellen Buffer von der Hotlist
+  hotlist_restore_buffer: Wiederherstellen der neuesten Hotlist, die im aktuellen Buffer entfernt wurde
+  hotlist_restore_all: Wiederherstellen der neuesten Hotlist, die in allen Buffern entfernt wurde
+  grab_key: fängt eine Taste (optionales Argument: Verzögerung um eine Taste einzufangen. Standard sind 500 Millisekunden)
+  grab_key_command: zeigt den Tastencode (inklusive des eingebundenen Befehls) einer Tastenkombination an und fügt ihn in die Befehlszeile ein (optionales Argument: Verzögerung um eine Taste einzufangen. Standard sind 500 Millisekunden)
+  grab_mouse: fängt den Code einer Maus Aktivität
+  grab_mouse_area: fängt den Code einer Maus Aktivität mit entsprechendem Bereich
+  set_unread: setzt für alle Buffer die Markierung der ungelesen Nachrichten
+  set_unread_current_buffer: setzt nur für den aktuellen Buffer eine Markierung der ungelesen Nachrichten
+  switch_active_buffer: springt zum nächsten zusammengefügten Buffer
+  switch_active_buffer_previous: springt zum vorherigen zusammengefügten Buffer
+  zoom_merged_buffer: zoomt in zusammengefügte Buffer
+  insert: fügt einen Text in die Eingabezeile ein (Escapesequenzen sind möglich, siehe /help print)
+  send: schickt Text an einen Buffer
+  paste_start: Einfügen wird gestartet (bracketed paste mode)
+  paste_stop: Einfügen wird beendet (bracketed paste mode)
+
+Dieser Befehl wird sinnvollerweise mittels Tastenbelegungen oder Erweiterungen genutzt.
 ----
 
 [[command_weechat_key]]