doc: add trigger doc in user's guide
Sebastien Helleu
parent
cc5ab76186
commit
0329cb65f3
|
|
@ -2916,6 +2916,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"]
|
||||
|===
|
||||
| Section | Control command | Beschreibung
|
||||
| look | /set trigger.look.* | Erscheinungsbild
|
||||
| color | /set trigger.color.* | Farben
|
||||
| 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]]
|
||||
=== Xfer Erweiterung
|
||||
|
||||
|
|
|
|||
|
|
@ -2857,6 +2857,508 @@ include::autogen/user/tcl_commands.txt[]
|
|||
|
||||
include::autogen/user/guile_commands.txt[]
|
||||
|
||||
[[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"]
|
||||
|===
|
||||
| Section | Control command | Description
|
||||
| look | /set trigger.look.* | Look and feel
|
||||
| color | /set trigger.color.* | Colors
|
||||
| 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]]
|
||||
=== Xfer plugin
|
||||
|
||||
|
|
|
|||
|
|
@ -2956,6 +2956,522 @@ include::autogen/user/tcl_commands.txt[]
|
|||
|
||||
include::autogen/user/guile_commands.txt[]
|
||||
|
||||
[[trigger_plugin]]
|
||||
=== Extension Trigger
|
||||
|
||||
Trigger est le couteau suisse de WeeChat : il peut accrocher différentes choses
|
||||
(signal, modificateur, print, ...), changer le contenu des données, et exécuter
|
||||
une ou plusieurs commandes. Une condition peut être utilisée pour empêcher le
|
||||
trigger de s'exécuter dans certaines circonstances.
|
||||
|
||||
Utiliser les triggers nécessite de connaître le fonctionnement des signaux,
|
||||
modificateurs, etc... Il peut être utile de lire le chapitre sur les 'Hooks'
|
||||
dans la 'Référence API Extension WeeChat'.
|
||||
|
||||
[[trigger_options]]
|
||||
==== Options (trigger.conf)
|
||||
|
||||
Sections:
|
||||
|
||||
[width="100%",cols="3m,6m,16",options="header"]
|
||||
|===
|
||||
| Section | Commande de contrôle | Description
|
||||
| look | /set trigger.look.* | Aspect/présentation
|
||||
| color | /set trigger.color.* | Couleurs
|
||||
| trigger | <<command_trigger_trigger,/trigger add>> +
|
||||
<<command_trigger_trigger,/trigger set>> +
|
||||
/set trigger.trigger.* | Options des triggers
|
||||
|===
|
||||
|
||||
Options:
|
||||
|
||||
include::autogen/user/trigger_options.txt[]
|
||||
|
||||
[[trigger_commands]]
|
||||
==== Commandes
|
||||
|
||||
include::autogen/user/trigger_commands.txt[]
|
||||
|
||||
[[trigger_anatomy]]
|
||||
==== Anatomie d'un trigger
|
||||
|
||||
Un trigger a les options suivantes (les noms sont
|
||||
`trigger.trigger.<nom>.<option>`):
|
||||
|
||||
[width="100%",cols="2m,2,10",options="header"]
|
||||
|===
|
||||
| Option | Valeurs | Description
|
||||
|
||||
| enabled | `on`, `off` |
|
||||
Lorsque l'option est `off`, le trigger est désactivé et les actions ne sont
|
||||
plus exécutées.
|
||||
|
||||
| hook | `signal`, `hsignal`, `modifier`, `print`, `command`, `command_run`,
|
||||
`timer`, `config`, `focus` |
|
||||
Le "hook" utilisé dans le trigger. Pour plus d'information, voir le chapitre
|
||||
'Hooks' dans la 'Référence API Extension WeeChat'.
|
||||
|
||||
| arguments | chaîne |
|
||||
Les paramètres pour le "hook", ils dépendent du type de hook utilisé.
|
||||
|
||||
| conditions | chaîne |
|
||||
Conditions pour exécuter le trigger : elles sont évaluées (voir la commande
|
||||
<<command_weechat_eval,/eval>>).
|
||||
|
||||
| regex | chaîne |
|
||||
Une ou plusieurs expressions régulières POSIX étendues, pour modifier les
|
||||
données reçues dans le callback du "hook" (et d'autres choses ajoutées par
|
||||
l'extension trigger), voir <<trigger_regex,expression régulière>>.
|
||||
|
||||
| command | chaîne |
|
||||
Commande à exécuter (plusieurs commandes peuvent être séparées par des
|
||||
points-virgules); elle est évaluée (voir la commande
|
||||
<<command_weechat_eval,/eval>>).
|
||||
|
||||
| return_code | `ok`, `ok_eat`, `error` |
|
||||
Le code retour du callback (`ok` par défaut, qui devrait être utilisé dans
|
||||
quasiment tous les triggers, les autres valeurs sont rarement utilisées).
|
||||
|===
|
||||
|
||||
Par exemple, le trigger 'beep' par défaut a les options suivantes :
|
||||
|
||||
----
|
||||
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]]
|
||||
==== Exécution
|
||||
|
||||
Lorsque le callback d'un trigger est appelé, les actions suivantes sont
|
||||
exécutées, dans cet ordre :
|
||||
|
||||
. vérifier si les triggers sont globalement activés: si non, sortir
|
||||
. vérifier si le trigger est activé: si non, sortir
|
||||
. vérifier les conditions du trigger: si faux, sortir
|
||||
. remplacer du texte dans le trigger en utilisant des expressions régulières
|
||||
. exécuter la/les commande(s)
|
||||
. sortir avec un code retour (sauf pour les "hooks" 'modifier' et 'focus').
|
||||
|
||||
[[trigger_hook_arguments]]
|
||||
==== Paramètres du hook
|
||||
|
||||
Les paramètres dépendent du type de "hook" utilisé. Ils sont séparés par des
|
||||
points-virgules.
|
||||
|
||||
[width="100%",cols="2,6,7",options="header"]
|
||||
|===
|
||||
| Hook | Paramètres | Exemples
|
||||
|
||||
| signal |
|
||||
1. nom de signal (priorité autorisée) (obligatoire) +
|
||||
2. nom de signal (priorité autorisée) +
|
||||
3. ... |
|
||||
`*,irc_in_privmsg` +
|
||||
`*,irc_in_privmsg;*,irc_in_notice` +
|
||||
`signal_sigwinch`
|
||||
|
||||
| hsignal |
|
||||
1. nom de signal (priorité autorisée) (obligatoire) +
|
||||
2. nom de signal (priorité autorisée) +
|
||||
3. ... |
|
||||
`nicklist_nick_added`
|
||||
|
||||
| modifier |
|
||||
1. nom de modificateur (priorité autorisée) (obligatoire) +
|
||||
2. nom de modificateur (priorité autorisée) +
|
||||
3. ... |
|
||||
`weechat_print` +
|
||||
`5000\|input_text_display;5000\|history_add`
|
||||
|
||||
| print |
|
||||
1. nom de tampon +
|
||||
2. étiquettes +
|
||||
3. message +
|
||||
4. suppression des couleurs (0/1) |
|
||||
`irc.freenode.*` +
|
||||
`irc.freenode.#weechat` +
|
||||
`irc.freenode.#weechat;irc_notice` +
|
||||
`*;;;1`
|
||||
|
||||
| command |
|
||||
1. nom de commande (priorité autorisée) (obligatoire) +
|
||||
2. description +
|
||||
3. paramètres +
|
||||
4. description des paramètres +
|
||||
5. complétion |
|
||||
`test` +
|
||||
`5000\|test`
|
||||
|
||||
| command_run |
|
||||
1. commande (priorité autorisée) (obligatoire) +
|
||||
2. commande (priorité autorisée) +
|
||||
3. ... |
|
||||
`/cmd paramètres`
|
||||
|
||||
| timer |
|
||||
1. intervalle, en millisecondes (obligatoire) +
|
||||
2. alignement sur la seconde (par défaut : 0) +
|
||||
3. nombre maximum d'appels (par défaut : 0, qui signifie "sans fin") |
|
||||
`3600000` +
|
||||
`60000;0;5`
|
||||
|
||||
| config |
|
||||
1. nom d'option (priorité autorisée) (obligatoire) +
|
||||
2. nom d'option (priorité autorisée) +
|
||||
3. ... |
|
||||
`weechat.look.*`
|
||||
|
||||
| focus |
|
||||
1. nom d'aire (priorité autorisée) (obligatoire) +
|
||||
2. nom d'aire (priorité autorisée) +
|
||||
3. ... |
|
||||
`buffer_nicklist`
|
||||
|===
|
||||
|
||||
[[trigger_conditions]]
|
||||
==== Conditions
|
||||
|
||||
Les conditions sont utilisées pour continuer l'exécution du trigger, ou tout
|
||||
stopper.
|
||||
|
||||
Elles sont évaluées, et les données disponibles dans le callback peuvent être
|
||||
utilisées (voir <<trigger_callback_data,données dans les callbacks>> et la
|
||||
commande <<command_weechat_eval,/eval>>).
|
||||
|
||||
Exemple : le trigger 'beep' par défaut utilise cette condition pour faire un
|
||||
beep seulement sur un highlight ou un message privé :
|
||||
|
||||
----
|
||||
${tg_highlight} || ${tg_msg_pv}
|
||||
----
|
||||
|
||||
[[trigger_regex]]
|
||||
==== Expression régulière
|
||||
|
||||
L'expression régulière est utilisée pour modifier des variables dans la table de
|
||||
hachage du callback.
|
||||
|
||||
Le format est : "/regex/remplacement" ou "/regex/remplacement/var" (où 'var' est
|
||||
une variable de la table de hachage). +
|
||||
Si 'var' n'est pas spécifiée, la variable par défaut est utilisée, elle dépend
|
||||
du type de hook :
|
||||
|
||||
[width="50%",cols="4,5m",options="header"]
|
||||
|===
|
||||
| Hook | Variable par défaut
|
||||
| signal | tg_signal_data
|
||||
| hsignal |
|
||||
| modifier | tg_string
|
||||
| print | tg_message
|
||||
| command | tg_argv_eol1
|
||||
| command_run | tg_command
|
||||
| timer |
|
||||
| config | tg_value
|
||||
| focus |
|
||||
|===
|
||||
|
||||
Plusieurs expressions régulières peuvent être séparées par un espace, par
|
||||
exemple : "/regex1/remplacement1/var1 /regex2/remplacement2/var2".
|
||||
|
||||
Le caractère "/" peut être remplacé par tout caractère (un ou plusieurs
|
||||
caractères identiques).
|
||||
|
||||
Les groupes de correspondance peuvent être utilisés dans le "remplacement" :
|
||||
|
||||
* `$0` à `$99` : `$0` est la correspondance complète, `$1` à `$99` sont les
|
||||
groupes capturés
|
||||
* `$+` : la dernière correspondance (avec le numéro le plus élevé)
|
||||
* `$.cN` : la correspondance "N" avec tous les caractères remplacés par "c"
|
||||
(exemple : `$.*2` est le groupe n°2 avec tous les caractères remplacés par
|
||||
`*`).
|
||||
|
||||
Exemple : utiliser du gras pour les mots entre "*" :
|
||||
|
||||
----
|
||||
/\*(\S+)\*/*${color:bold}$1${color:-bold}*/
|
||||
----
|
||||
|
||||
Exemple : le trigger par défaut 'server_pass' utilise cette expression régulière
|
||||
pour cacher le mot de passe dans les commandes `/server` et `/connect` (les
|
||||
caractères des mots de passe sont remplacés par `*`) :
|
||||
|
||||
----
|
||||
==^(/(server|connect) .*-(sasl_)?password=)(\S+)(.*)==$1$.*4$5
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
Dans cet exemple, le séparateur utilisé est "==" car il y a "/" dans
|
||||
l'expression régulière.
|
||||
|
||||
[[trigger_command]]
|
||||
==== Commande
|
||||
|
||||
La commande est exécutée après le remplacement du texte avec l'expression
|
||||
régulière.
|
||||
Plusieurs commandes peuvent être séparées par des points-virgules.
|
||||
|
||||
Elle est évaluée (voir la commande <<command_weechat_eval,/eval>>) et le texte
|
||||
remplacé avec l'expression régulière peut être utilisé dans la commande.
|
||||
|
||||
Exemple : le trigger par défaut 'beep' utilise cette commande pour produire un
|
||||
beep (BEL) :
|
||||
|
||||
----
|
||||
/print -beep
|
||||
----
|
||||
|
||||
[[trigger_callback_data]]
|
||||
==== Données dans les callbacks
|
||||
|
||||
Les données reçues dans les callbacks sont stockées dans des tables de hachage
|
||||
(pointeurs et chaînes) et peuvent être utilisées dans les options suivantes :
|
||||
|
||||
* 'conditions'
|
||||
* 'regex'
|
||||
* 'command'
|
||||
|
||||
Le contenu des tables de hachage dépend du type de hook.
|
||||
|
||||
Une manière pratique de voir les données dans le trigger est d'ouvrir le tampon
|
||||
moniteur des triggers :
|
||||
|
||||
----
|
||||
/trigger monitor
|
||||
----
|
||||
|
||||
[[trigger_data_signal]]
|
||||
===== Signal
|
||||
|
||||
Le callback "signal" définit les variables suivantes dans la table de hachage :
|
||||
|
||||
[width="100%",cols="3m,2,14",options="header"]
|
||||
|===
|
||||
| Variable | Type | Description
|
||||
| tg_signal | chaîne | Nom du signal
|
||||
| tg_signal_data | chaîne | Données envoyées avec le signal
|
||||
|===
|
||||
|
||||
Si le signal contient un message IRC, le message est analysé et les données
|
||||
suivantes sont ajoutées dans la table de hachage :
|
||||
|
||||
[width="100%",cols="3m,2,14",options="header"]
|
||||
|===
|
||||
| Variable | Type | Description
|
||||
| server | chaîne | Nom du serveur (exemple : "freenode")
|
||||
| tags | chaîne | Étiquettes dans le message (rarement utilisées)
|
||||
| message_without_tags | chaîne | Message sans les étiquettes
|
||||
| nick | chaîne | Pseudo
|
||||
| host | chaîne | Nom d'hôte
|
||||
| command | chaîne | Commane IRC (exemple : "PRIVMSG", "NOTICE", ...)
|
||||
| channel | chaîne | Canal IRC
|
||||
| arguments | chaîne | Paramètres de la commande (inclut la valeur de 'channel')
|
||||
|===
|
||||
|
||||
[[trigger_data_hsignal]]
|
||||
===== Hsignal
|
||||
|
||||
Le callback "hsignal" définit les variables suivantes dans la table de hachage :
|
||||
|
||||
[width="100%",cols="3m,2,14",options="header"]
|
||||
|===
|
||||
| Variable | Type | Description
|
||||
| tg_signal | chaîne | Nom du signal
|
||||
|===
|
||||
|
||||
La table de hachage contient toutes les clés/valeurs de la table de hachage
|
||||
reçue (type : chaîne/chaîne).
|
||||
|
||||
[[trigger_data_modifier]]
|
||||
===== Modifier
|
||||
|
||||
Le callback "modifier" définit les variables suivantes dans la table de hachage :
|
||||
|
||||
[width="100%",cols="3m,2,14",options="header"]
|
||||
|===
|
||||
| Variable | Type | Description
|
||||
| tg_modifier | chaîne | Nom du modificateur
|
||||
| tg_modifier_data | chaîne | Données envoyées avec le modificateur
|
||||
| tg_string | chaîne | La chaîne qui peut être modifiée
|
||||
| tg_string_nocolor | chaîne | La chaîne sans les codes couleur
|
||||
|===
|
||||
|
||||
Pour le modificateur 'weechat_print', les variables en utilisant les étiquettes
|
||||
du message sont ajoutées (voir le <<trigger_data_print,hook print>> ci-dessous),
|
||||
ainsi que les variables suivantes :
|
||||
|
||||
[width="100%",cols="3m,2,14",options="header"]
|
||||
|===
|
||||
| Variable | Type | Description
|
||||
| buffer | pointeur | Tampon où le message est affiché
|
||||
| tg_plugin | chaîne | Extension du tampon où le message est affiché
|
||||
| tg_buffer | chaîne | Nom complet du tampon où le message est affiché
|
||||
| tg_prefix | chaîne | Préfixe du message affiché
|
||||
| tg_prefix_nocolor | chaîne | Préfixe sans les codes couleur
|
||||
| tg_message | chaîne | Message affiché
|
||||
| tg_message_nocolor | chaîne | Message sans les codes couleur
|
||||
|===
|
||||
|
||||
Si le modificateur contient un message IRC, le message est analysé et des
|
||||
données supplémentaires sont ajoutées dans la table de hachage (voir le
|
||||
<<trigger_data_signal,"hook" signal>>).
|
||||
|
||||
[[trigger_data_print]]
|
||||
===== Print
|
||||
|
||||
Le callback "print" définit les variables suivantes dans la table de hachage :
|
||||
|
||||
[width="100%",cols="3m,2,14",options="header"]
|
||||
|===
|
||||
| Variable | Type | Description
|
||||
| buffer | pointeur | Buffer
|
||||
| tg_date | chaîne | Date/heure du message (format : `YYYY-MM-DD hh:mm:ss`)
|
||||
| tg_displayed | chaîne | "1" si affiché, "0" si ligne filtrée
|
||||
| tg_highlight | chaîne | "1" si highlight, sinon "0"
|
||||
| tg_prefix | chaîne | Préfixe
|
||||
| tg_prefix_nocolor | chaîne | Préfixe sans les codes couleur
|
||||
| tg_message | chaîne | Message
|
||||
| tg_message_nocolor | chaîne | Message sans les codes couleur
|
||||
|===
|
||||
|
||||
Variables définies avec les étiquettes du message (elles sont définies aussi
|
||||
pour le modificateur 'weechat_print') :
|
||||
|
||||
[width="100%",cols="3m,2,14",options="header"]
|
||||
|===
|
||||
| Variable | Type | Description
|
||||
| tg_tags | chaîne | Étiquettes du message (avec une virgule en début/fin de chaîne)
|
||||
| tg_tags_count | chaîne | Nombre d'étiquettes dans le message
|
||||
| tg_tag_notify | chaîne | Niveau de notification ('none', 'message', 'private', 'highlight')
|
||||
| tg_tag_nick | chaîne | Pseudo (depuis l'étiquette "nick_xxx")
|
||||
| tg_tag_prefix_nick | chaîne | Couleur du pseudo dans le préfixe (depuis l'étiquette "prefix_nick_ccc")
|
||||
| tg_msg_pv | chaîne | "1" pour un message privé, sinon "0"
|
||||
|===
|
||||
|
||||
[[trigger_data_command]]
|
||||
===== Command
|
||||
|
||||
Le callback "command" définit les variables suivantes dans la table de hachage :
|
||||
|
||||
[width="100%",cols="3m,2,14",options="header"]
|
||||
|===
|
||||
| Variable | Type | Description
|
||||
| buffer | pointeur | Tampon
|
||||
| tg_argvN | chaîne | Paramètre n°N
|
||||
| tg_argv_eolN | chaîne | Depuis le paramètre n°N jusqu'à la fin des paramètres
|
||||
|===
|
||||
|
||||
[[trigger_data_command_run]]
|
||||
===== Command_run
|
||||
|
||||
Le callback "command_run" définit les variables suivantes dans la table de
|
||||
hachage :
|
||||
|
||||
[width="100%",cols="3m,2,14",options="header"]
|
||||
|===
|
||||
| Variable | Type | Description
|
||||
| buffer | pointeur | Tampon
|
||||
| tg_command | chaîne | Commande exécutée
|
||||
|===
|
||||
|
||||
[[trigger_data_timer]]
|
||||
===== Timer
|
||||
|
||||
Le callback "timer" définit les variables suivantes dans la table de hachage :
|
||||
|
||||
[width="100%",cols="3m,2,14",options="header"]
|
||||
|===
|
||||
| Variable | Type | Description
|
||||
| tg_remaining_calls | chaîne | Nombre d'appels restants
|
||||
| tg_date | chaîne | Date/heure courante (format : `YYYY-MM-DD hh:mm:ss`)
|
||||
|===
|
||||
|
||||
[[trigger_data_config]]
|
||||
===== Config
|
||||
|
||||
Le callback "config" définit les variables suivantes dans la table de hachage :
|
||||
|
||||
[width="100%",cols="3m,2,14",options="header"]
|
||||
|===
|
||||
| Variable | Type | Description
|
||||
| tg_option | chaîne | Option
|
||||
| tg_value | chaîne | Valeur
|
||||
|===
|
||||
|
||||
[[trigger_data_focus]]
|
||||
===== Focus
|
||||
|
||||
Le callback "focus" définit les variables suivantes dans la table de hachage :
|
||||
|
||||
[width="100%",cols="3m,2,14",options="header"]
|
||||
|===
|
||||
| Variable | Type | Description
|
||||
| window | pointeur | Fenêtre
|
||||
| buffer | pointeur | Tampon
|
||||
|===
|
||||
|
||||
La table de hachage contient toutes les clés/valeurs de la table de hachage
|
||||
reçue (type : chaîne/chaîne).
|
||||
|
||||
[[trigger_examples]]
|
||||
==== Exemples
|
||||
|
||||
[[trigger_example_auto_pong]]
|
||||
===== Pong auto sur les requêtes ping
|
||||
|
||||
Lorsque quelqu'un envoie un "ping" dans un tampon privé, le trigger répondra
|
||||
automatiquement avec un `pong` :
|
||||
|
||||
----
|
||||
/trigger add pong print "" "${type} == private && ${tg_message} == ping" "" "pong"
|
||||
----
|
||||
|
||||
[[trigger_example_responsive_layout]]
|
||||
===== Disposition réceptive
|
||||
|
||||
Les triggers suivants peuvent être utilisées pour personnaliser l'affichage
|
||||
lorsque la taille du terminal change :
|
||||
|
||||
----
|
||||
/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"
|
||||
----
|
||||
|
||||
Les triggers attrapent le signal "signal_sigwinch", qui et envoyé par WeeChat
|
||||
lorsque le signal SIGWINCH est reçu (lorsque la taille du terminal a changé).
|
||||
|
||||
La condition avec `${info:term_width}` vérifie la largeur du terminal (vous
|
||||
pouvez aussi utiliser `${info:term_height}` si besoin).
|
||||
|
||||
Dans l'exemple, si le terminal devient petit, la liste de pseudos est cachée.
|
||||
Et la barre est restaurée lorsque la largeur du terminal est supérieure ou
|
||||
égale à 100 caractères.
|
||||
|
||||
[[trigger_example_config_save]]
|
||||
===== Sauvegarde automatique de la configuration
|
||||
|
||||
Vous pouvez sauvegarder automatiquement les fichiers de configuration
|
||||
(`*.conf`), par example chaque heure :
|
||||
|
||||
----
|
||||
/trigger add cfgsave timer 3600000;0;0 "" "" "/mute /save"
|
||||
----
|
||||
|
||||
Les paramètres pour le minuteur sont :
|
||||
|
||||
* '3600000' : 3600 * 1000 millisecondes, le callback est appelé toutes les
|
||||
heures
|
||||
* '0' : alignement sur la seconde (pas d'alignement ici)
|
||||
* '0' : nombre maximum d'appels (0 = pas de fin pour le minuteur)
|
||||
|
||||
La commande `/mute /save` sauvegarde silencieusement les fichiers de
|
||||
configuration (rien n'est affiché sur le tampon "core").
|
||||
|
||||
[[xfer_plugin]]
|
||||
=== Extension Xfer
|
||||
|
||||
|
|
|
|||
|
|
@ -2989,6 +2989,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"]
|
||||
|===
|
||||
| Section | Control command | Description
|
||||
| look | /set trigger.look.* | Look and feel
|
||||
| color | /set trigger.color.* | Colors
|
||||
| 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]]
|
||||
=== Plugin Xfer
|
||||
|
||||
|
|
|
|||
|
|
@ -2860,6 +2860,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"]
|
||||
|===
|
||||
| セクション | 操作コマンド | 説明
|
||||
| look | /set trigger.look.* | 外観
|
||||
| color | /set trigger.color.* | 色
|
||||
| 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]]
|
||||
=== Xfer プラグイン
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue