diff options
author | Sebastien Helleu <flashcode@flashtux.org> | 2014-03-02 09:29:14 +0100 |
---|---|---|
committer | Sebastien Helleu <flashcode@flashtux.org> | 2014-03-02 09:29:14 +0100 |
commit | 0329cb65f39735973257fdb99012546ac8d3fcee (patch) | |
tree | cc60b86b80505cc90490264fab3fd36ad3c50f02 /doc/pl/weechat_user.pl.txt | |
parent | cc5ab76186b6a1f842eb758a6997c54b1917c885 (diff) | |
download | weechat-0329cb65f39735973257fdb99012546ac8d3fcee.zip |
doc: add trigger doc in user's guide
Diffstat (limited to 'doc/pl/weechat_user.pl.txt')
-rw-r--r-- | doc/pl/weechat_user.pl.txt | 503 |
1 files changed, 503 insertions, 0 deletions
diff --git a/doc/pl/weechat_user.pl.txt b/doc/pl/weechat_user.pl.txt index 30a717669..79a221219 100644 --- a/doc/pl/weechat_user.pl.txt +++ b/doc/pl/weechat_user.pl.txt @@ -2881,6 +2881,509 @@ include::autogen/user/tcl_commands.txt[] include::autogen/user/guile_commands.txt[] +// TRANSLATION MISSING +[[trigger_plugin]] +=== Trigger plugin + +Trigger is the Swiss Army knife for WeeChat: it can hook many things (signal, +modifier, print, ...), change the content of data, and execute one or more +commands. A condition can be used to prevent the trigger to run in some +circumstances. + +Using triggers require you to know how the signals, modifiers, ... are working. +So you might consider reading the 'Hooks' chapter in the +'WeeChat Plugin API Reference'. + +[[trigger_options]] +==== Options (trigger.conf) + +Sections: + +[width="100%",cols="3m,6m,16",options="header"] +|=== +| Sekcja | Komenda | Opis +| look | /set trigger.look.* | Wygląd +| color | /set trigger.color.* | Kolory +| trigger | <<command_trigger_trigger,/trigger add>> + + <<command_trigger_trigger,/trigger set>> + + /set trigger.trigger.* | Trigger options +|=== + +Options: + +include::autogen/user/trigger_options.txt[] + +[[trigger_commands]] +==== Commands + +include::autogen/user/trigger_commands.txt[] + +[[trigger_anatomy]] +==== Anatomy of a trigger + +A trigger has the following options (names are +`trigger.trigger.<name>.<option>`): + +[width="100%",cols="2m,2,10",options="header"] +|=== +| Option | Values | Description + +| enabled | `on`, `off` | + When option is `off`, the trigger is disabled and actions are not executed + any more. + +| hook | `signal`, `hsignal`, `modifier`, `print`, `command`, `command_run`, + `timer`, `config`, `focus` | + The hook used in trigger. For more information, see + 'WeeChat Plugin API Reference', chapter 'Hooks'. + +| arguments | string | + The arguments for the hook, it depends on the hook type used. + +| conditions | string | + Conditions to execute the trigger; they are evaluated (see command + <<command_weechat_eval,/eval>>). + +| regex | string | + One or more POSIX extended regular expressions, to change data received in the + hook callback (and some stuff added by trigger plugin), see + <<trigger_regex,regular expression>>. + +| command | string | + Command to execute (many commands can be separated by semicolons); it is + evaluated (see command <<command_weechat_eval,/eval>>). + +| return_code | `ok`, `ok_eat`, `error` | + The return code of callback (default is `ok`, which should be used in almost + all triggers, the other values are rarely used). +|=== + +For example, the default 'beep' trigger has following options: + +---- +trigger.trigger.beep.enabled = on +trigger.trigger.beep.hook = print +trigger.trigger.beep.arguments = "" +trigger.trigger.beep.conditions = "${tg_highlight} || ${tg_msg_pv}" +trigger.trigger.beep.regex = "" +trigger.trigger.beep.command = "/print -beep" +trigger.trigger.beep.return_code = ok +---- + +[[trigger_execution]] +==== Execution + +When a trigger callback is called, following actions are executed, in this +order: + +. check if triggers are globally enabled: if not, exit +. check if trigger is enabled: if not, exit +. check trigger conditions: if false, exit +. replace text in trigger using regular expression(s) +. execute command(s) +. exit with a return code (except for hooks 'modifier' and 'focus'). + +[[trigger_hook_arguments]] +==== Hook arguments + +The arguments depend on the hook used. They are separated by semicolons. + +[width="100%",cols="2,6,7",options="header"] +|=== +| Hook | Arguments | Examples + +| signal | + 1. signal name (priority allowed) (required) + + 2. signal name (priority allowed) + + 3. ... | + `*,irc_in_privmsg` + + `*,irc_in_privmsg;*,irc_in_notice` + + `signal_sigwinch` + +| hsignal | + 1. signal name (priority allowed) (required) + + 2. signal name (priority allowed) + + 3. ... | + `nicklist_nick_added` + +| modifier | + 1. modifier name (priority allowed) (required) + + 2. modifier name (priority allowed) + + 3. ... | + `weechat_print` + + `5000\|input_text_display;5000\|history_add` + +| print | + 1. buffer name + + 2. tags + + 3. message + + 4. strip colors (0/1) | + `irc.freenode.*` + + `irc.freenode.#weechat` + + `irc.freenode.#weechat;irc_notice` + + `*;;;1` + +| command | + 1. command name (priority allowed) (required) + + 2. description + + 3. arguments + + 4. description of arguments + + 5. completion | + `test` + + `5000\|test` + +| command_run | + 1. command (priority allowed) (required) + + 2. command (priority allowed) + + 3. ... | + `/cmd arguments` + +| timer | + 1. interval in milliseconds (required) + + 2. alignment on second (default: 0) + + 3. max number of calls (default: 0, which means "no end") | + `3600000` + + `60000;0;5` + +| config | + 1. option name (priority allowed) (required) + + 2. option name (priority allowed) + + 3. ... | + `weechat.look.*` + +| focus | + 1. area name (priority allowed) (required) + + 2. area name (priority allowed) + + 3. ... | + `buffer_nicklist` +|=== + +[[trigger_conditions]] +==== Conditions + +The conditions are used to continue processing in trigger, or stop everything. + +They are evaluated, and data available in callback can be used +(see <<trigger_callback_data,data in callbacks>> and command +<<command_weechat_eval,/eval>>). + +Example: the default 'beep' trigger uses this condition to make a beep only on +highlight or private message: + +---- +${tg_highlight} || ${tg_msg_pv} +---- + +[[trigger_regex]] +==== Regular expression + +The regular expression is used to change variables in callback hashtable. + +The format is: "/regex/replace" or "/regex/replace/var" (where 'var' is a +variable of the hashtable). + +If 'var' is not specified, the default variable is used, it depends on hook +type: + +[width="50%",cols="4,5m",options="header"] +|=== +| Hook | Default variable +| signal | tg_signal_data +| hsignal | +| modifier | tg_string +| print | tg_message +| command | tg_argv_eol1 +| command_run | tg_command +| timer | +| config | tg_value +| focus | +|=== + +Many regular expressions can be separated by a space, for example: +"/regex1/replace1/var1 /regex2/replace2/var2". + +The char "/" can be replaced by any char (one or more identical chars). + +Matching groups can be used in "replace": + +* `$0` to `$99`: `$0` is the whole match, `$1` to `$99` are groups captured +* `$+`: the last match (with highest number) +* `$.cN`: match "N" with all chars replaced by "c" (example: `$.*2` is the group + #2 with all chars replaced by `*`). + +Example: use bold for words between "*": + +---- +/\*(\S+)\*/*${color:bold}$1${color:-bold}*/ +---- + +Example: default trigger 'server_pass' uses this regular expression to hide +password in commands `/server` and `/connect` (chars in passwords are replaced +by `*`): + +---- +==^(/(server|connect) .*-(sasl_)?password=)(\S+)(.*)==$1$.*4$5 +---- + +[NOTE] +In this example, the delimiter used is "==" because there is a "/" in the +regular expression. + +[[trigger_command]] +==== Command + +The command is executed after replacement of text with the regular expression. +Many commands can be separated by semicolons. + +It is evaluated (see command <<command_weechat_eval,/eval>>) and text replaced +with a regular expression can be used in the command. + +Example: default 'beep' trigger uses this command to make a beep (BEL): + +---- +/print -beep +---- + +[[trigger_callback_data]] +==== Data in callbacks + +Data received in callbacks are stored in hashtables (pointers and strings) and +can be used in following options: + +* 'conditions' +* 'regex' +* 'command' + +The content of hashtables depend on the hook type. + +A convenient way to see data in a trigger is to open trigger monitor buffer, +using the command: + +---- +/trigger monitor +---- + +[[trigger_data_signal]] +===== Signal + +The "signal" callback sets following variables in hashtable: + +[width="100%",cols="3m,2,14",options="header"] +|=== +| Variable | Type | Description +| tg_signal | string | Name of signal +| tg_signal_data | string | Data sent with the signal +|=== + +If the signal contains an IRC message, the message is parsed and following data +is added in hashtable: + +[width="100%",cols="3m,2,14",options="header"] +|=== +| Variable | Type | Description +| server | string | Name of server (example: "freenode") +| tags | string | Tags in message (rarely used) +| message_without_tags | string | Message without tags +| nick | string | Nick +| host | string | Hostname +| command | string | IRC command (example: "PRIVMSG", "NOTICE", ...) +| channel | string | IRC channel +| arguments | string | Arguments of command (includes value of 'channel') +|=== + +[[trigger_data_hsignal]] +===== Hsignal + +The "hsignal" callback sets following variables in hashtable: + +[width="100%",cols="3m,2,14",options="header"] +|=== +| Variable | Type | Description +| tg_signal | string | Name of signal +|=== + +The hashtable contains all keys/values from hashtable received (type: +string/string). + +[[trigger_data_modifier]] +===== Modifier + +The "modifier" callback sets following variables in hashtable: + +[width="100%",cols="3m,2,14",options="header"] +|=== +| Variable | Type | Description +| tg_modifier | string | Name of modifier +| tg_modifier_data | string | Data sent with modifier +| tg_string | string | The string that can be modified +| tg_string_nocolor | string | The string without color codes +|=== + +For the 'weechat_print' modifier, variables using message tags are added (see +<<trigger_data_print,hook print>> below), and following variables: + +[width="100%",cols="3m,2,14",options="header"] +|=== +| Variable | Type | Description +| buffer | pointer | Buffer where message is printed +| tg_plugin | string | Plugin of buffer where message is printed +| tg_buffer | string | Full name of buffer where message is printed +| tg_prefix | string | Prefix of message printed +| tg_prefix_nocolor | string | Prefix without color codes +| tg_message | string | Message printed +| tg_message_nocolor | string | Message without color codes +|=== + +If the modifier contains an IRC message, the message is parsed and extra data is +added in hashtable (see <<trigger_data_signal,hook signal>>). + +[[trigger_data_print]] +===== Print + +The "print" callback sets following variables in hashtable: + +[width="100%",cols="3m,2,14",options="header"] +|=== +| Variable | Type | Description +| buffer | pointer | Buffer +| tg_date | string | Message date/time (format: `YYYY-MM-DD hh:mm:ss`) +| tg_displayed | string | "1" if displayed, "0" if line filtered +| tg_highlight | string | "1" if highlight, otherwise "0" +| tg_prefix | string | Prefix +| tg_prefix_nocolor | string | Prefix without color codes +| tg_message | string | Message +| tg_message_nocolor | string | Message without color codes +|=== + +Variables set using tags in message (they are set in modifier 'weechat_print' +too): + +[width="100%",cols="3m,2,14",options="header"] +|=== +| Variable | Type | Description +| tg_tags | string | Tags of message (with comma added at beginning/end of string) +| tg_tags_count | string | Number of tags in message +| tg_tag_notify | string | Notify level ('none', 'message', 'private', 'highlight') +| tg_tag_nick | string | Nick (from tag "nick_xxx") +| tg_tag_prefix_nick | string | Color of nick in prefix (from tag "prefix_nick_ccc") +| tg_msg_pv | string | "1" for a private message, otherwise "0" +|=== + +[[trigger_data_command]] +===== Command + +The "command" callback sets following variables in hashtable: + +[width="100%",cols="3m,2,14",options="header"] +|=== +| Variable | Type | Description +| buffer | pointer | Buffer +| tg_argvN | string | Argument #N +| tg_argv_eolN | string | From argument #N until end of arguments +|=== + +[[trigger_data_command_run]] +===== Command_run + +The "command_run" callback sets following variables in hashtable: + +[width="100%",cols="3m,2,14",options="header"] +|=== +| Variable | Type | Description +| buffer | pointer | Buffer +| tg_command | string | Command executed +|=== + +[[trigger_data_timer]] +===== Timer + +The "timer" callback sets following variables in hashtable: + +[width="100%",cols="3m,2,14",options="header"] +|=== +| Variable | Type | Description +| tg_remaining_calls | string | Number of remaining calls +| tg_date | string | Current date/time (format: `YYYY-MM-DD hh:mm:ss`) +|=== + +[[trigger_data_config]] +===== Config + +The "config" callback sets following variables in hashtable: + +[width="100%",cols="3m,2,14",options="header"] +|=== +| Variable | Type | Description +| tg_option | string | Option +| tg_value | string | Value +|=== + +[[trigger_data_focus]] +===== Focus + +The "focus" callback sets following variables in hashtable: + +[width="100%",cols="3m,2,14",options="header"] +|=== +| Variable | Type | Description +| window | pointer | Window +| buffer | pointer | Buffer +|=== + +The hashtable contains all keys/values from hashtable received (type: +string/string). + +[[trigger_examples]] +==== Examples + +[[trigger_example_auto_pong]] +===== Auto pong on ping queries + +When someone sends a "ping" in a private buffer, this trigger will auto-reply +with `pong`: + +---- +/trigger add pong print "" "${type} == private && ${tg_message} == ping" "" "pong" +---- + +[[trigger_example_responsive_layout]] +===== Responsive layout + +Following triggers can be used to customize things displayed when the size of +terminal is changed: + +---- +/trigger add resize_small signal signal_sigwinch "${info:term_width} < 100" "" "/bar hide nicklist" +/trigger add resize_big signal signal_sigwinch "${info:term_width} >= 100" "" "/bar show nicklist" +---- + +The triggers catch the signal "signal_sigwinch", which is sent by WeeChat when +signal SIGWINCH is received (when terminal size is changed). + +The condition with `${info:term_width}` checks the width of terminal (you can +also use `${info:term_height}` if needed). + +In the example, when the terminal becomes small, the nicklist is hidden. And the +bar is restored when the width is greater or equal to 100 chars. + +[[trigger_example_config_save]] +===== Automatic save of configuration + +You can automatically save configuration files (`*.conf`), for example each +hour: + +---- +/trigger add cfgsave timer 3600000;0;0 "" "" "/mute /save" +---- + +Arguments for the timer hook are: + +* '3600000': 3600 * 1000 milliseconds, the callback is called each hour +* '0': alignment on second (not aligned here) +* '0': max number of calls (0 = no end for the timer) + +The command `/mute /save` will silently save configuration files (nothing +displayed on core buffer). + [[xfer_plugin]] === Wtyczka xfer |