Eggdrop Documentation - 11. Bind
30-12-2010 10:50
11. Bind
You can use the 'bind' command to attach Tcl procedures to certain events. For example, you can write a Tcl procedure that gets called every time a user says "danger" on the channel.
Some bind types are marked as "stackable". That means that you can bind multiple commands to the same trigger. Normally, for example, a bind such as 'bind msg - stop msg:stop' (which makes a msg-command "stop" call the Tcl proc "msg:stop") will overwrite any previous binding you had for then msg command "stop". With stackable bindings, like 'msgm' for example, you can bind the same command to multiple procs. When the bind is triggered, ALL of the Tcl procs that are bound to it will be called.
To remove a bind, use the 'unbind' command. For example, to remove the bind for the "stop" msg command, use 'unbind msg - stop msg:stop'.
MSG
bind msg <flags> <command> <proc>
procname <nick> <user@host> <handle> <text>Description: used for /msg commands. The first word of the user's msg is the command, and everything else becomes the text argument.
Module: server
DCC
bind dcc <flags> <command> <proc>
procname <handle> <idx> <text>Description: used for partyline commands; the command is the first word and everything else becomes the text argument. The idx is valid until the user disconnects. After that, it may be reused, so be careful about storing an idx for long periods of time.
Module: core
FIL
bind fil <flags> <command> <proc>
procname <handle> <idx> <text>Description: the same as DCC, except this is triggered if the user is in the file area instead of the party line
Module: filesys
PUB
bind pub <flags> <command> <proc>
procname <nick> <user@host> <handle> <channel> <text>Description: used for commands given on a channel. The first word becomes the command and everything else is the text argument.
Module: irc
MSGM (stackable)
bind msgm <flags> <mask> <proc>
procname <nick> <user@host> <handle> <text>Description: matches the entire line of text from a /msg with the mask. This is useful for binding Tcl procs to words or phrases spoken anywhere within a line of text. If the proc returns 1, Eggdrop will not log the message that triggered this bind. MSGM binds are processed before MSG binds. If the exclusive-binds setting is enabled, MSG binds will not be trigged by text that a MSGM bind has already handled.
Module: server
PUBM (stackable)
bind pubm <flags> <mask> <proc>
procname <nick> <user@host> <handle> <channel> <text>Description: just like MSGM, except it's triggered by things said on a channel instead of things /msg'd to the bot. The mask is matched against the channel name followed by the text and can contain wildcards. If the proc returns 1, Eggdrop will not log the message that triggered this bind. PUBM binds are processed before PUB binds. If the exclusive-binds setting is enabled, PUB binds will not be trigged by text that a PUBM bind has already handled.
Module: irc
NOTC (stackable)
bind notc <flags> <mask> <proc>
procname <nick> <user@host> <handle> <text> <dest>Description: dest will be a nickname (the bot's nickname, obviously) or a channel name. mask is matched against the entire notice and can contain wildcards. It is considered a breach of protocol to respond to a /notice on IRC, so this is intended for internal use (logging, etc.) only. Note that server notices do not trigger the NOTC bind. If the proc returns 1, Eggdrop will not log the message that triggered this bind.
New Tcl procs should be declared as
proc notcproc {nick uhost hand text {dest ""}} { global botnick; if {$dest == ""} {set dest $botnick} ... }for compatibility.
Module: server
JOIN (stackable)
bind join <flags> <mask> <proc>
procname <nick> <user@host> <handle> <channel>Description: triggered by someone joining the channel. The mask in the bind is matched against "#channel nick!user@host" and can contain wildcards.
Module: irc
PART (stackable)
bind part <flags> <mask> <proc>
procname <nick> <user@host> <handle> <channel> <msg>Description: triggered by someone leaving the channel. The mask is matched against "#channel nick!user@host" and can contain wildcards. If no part message is specified, msg will be set to "".
New Tcl procs should be declared as
proc partproc {nick uhost hand chan {msg ""}} { ... }for compatibility.
Module: irc
SIGN (stackable)
bind sign <flags> <mask> <proc>
procname <nick> <user@host> <handle> <channel> <reason>Description: triggered by a signoff, or possibly by someone who got netsplit and never returned. The signoff message is the last argument to the proc. Wildcards can be used in the mask, which is matched against '#channel nick!user@host'.
Module: irc
TOPC (stackable)
bind topc <flags> <mask> <proc>
procname <nick> <user@host> <handle> <channel> <topic>Description: triggered by a topic change. mask can contain wildcards and is matched against '#channel <new topic>'.
Module: irc
KICK (stackable)
bind kick <flags> <mask> <proc>
procname <nick> <user@host> <handle> <channel> <target> <reason>Description: triggered when someone is kicked off the channel. The mask is matched against '#channel target reason' where the target is the nickname of the person who got kicked (can contain wildcards). The proc is called with the nick, user@host, and handle of the kicker, plus the channel, the nickname of the person who was kicked, and the reason.
Module: irc
NICK (stackable)
bind nick <flags> <mask> <proc>
procname <nick> <user@host> <handle> <channel> <newnick>Description: triggered when someone changes nicknames. The mask is matched against '#channel newnick' and can contain wildcards. Channel is "*" if the user isn't on a channel (usually the bot not yet in a channel).
Module: irc
MODE (stackable)
bind mode <flags> <mask> <proc>
proc-name <nick> <user@host> <handle> <channel> <mode-change> <target>Description: mode changes are broken down into their component parts before being sent here, so the <mode-change> will always be a single mode, such as "+m" or "-o". target will show the argument of the mode change (for o/v/b/e/I) or "" if the set mode does not take an argument. The bot's automatic response to a mode change will happen AFTER all matching Tcl procs are called. The mask will be matched against '#channel +/-modes' and can contain wildcards.
If it is a server mode, nick will be "", user@host is the server name, and handle is *.
Note that "target" was added in 1.3.17 and that this will break Tcl scripts that were written for pre-1.3.17 Eggdrop that use the mode binding. Also, due to a typo, mode binds were broken completely in 1.3.17 but were fixed in 1.3.18. Mode bindings are not triggered at all in 1.3.17.
One easy example (from guppy) of how to support the "target" parameter in 1.3.18 and later and still remain compatible with older Eggdrop versions is:
Old script looks as follows:
bind mode - * mode_proc proc mode_proc {nick uhost hand chan mode} { ... }To make it work with 1.3.18+ and stay compatible with older bots, do:
bind mode - * mode_proc_fix proc mode_proc_fix {nick uhost hand chan mode {target ""}} { if {$target != ""} {append mode " $target"} mode_proc $nick $uhost $hand $chan $mode } proc mode_proc {nick uhost hand chan mode} { ... }Module: irc
CTCP (stackable)
bind ctcp <flags> <keyword> <proc>
proc-name <nick> <user@host> <handle> <dest> <keyword> <text>Description: dest will be a nickname (the bot's nickname, obviously) or channel name. keyword is the ctcp command (which can contain wildcards), and text may be empty. If the proc returns 0, the bot will attempt its own processing of the ctcp command.
Module: server
CTCR (stackable)
bind ctcr <flags> <keyword> <proc>
proc-name <nick> <user@host> <handle> <dest> <keyword> <text>Description: just like ctcp, but this is triggered for a ctcp-reply (ctcp embedded in a notice instead of a privmsg)
Module: server
RAW (stackable)
bind raw <flags> <keyword-mask> <proc>
procname <from> <keyword> <text>Description: previous versions of Eggdrop required a special compile option to enable this binding, but it's now standard. The keyword is either a numeric, like "368", or a keyword, such as "PRIVMSG". from will be the server name or the source user (depending on the keyword); flags are ignored. The order of the arguments is identical to the order that the IRC server sends to the bot. The pre-processing only splits it apart enough to determine the keyword. If the proc returns 1, Eggdrop will not process the line any further (this could cause unexpected behavior in some cases).
Module: server
BOT
bind bot <flags> <command> <proc>
proc-name <from-bot> <command> <text>Description: triggered by a message coming from another bot in the botnet. The first word is the command and the rest becomes the text argument; flags are ignored.
Module: core
CHON (stackable)
bind chon <flags> <mask> <proc>
proc-name <handle> <idx>Description: when someone first enters the party-line area of the bot via dcc chat or telnet, this is triggered before they are connected to a chat channel (so, yes, you can change the channel in a 'chon' proc). mask is matched against the handle and supports wildcards. This is NOT triggered when someone returns from the file area, etc.
Module: core
CHOF (stackable)
bind chof <flags> <mask> <proc>
proc-name <handle> <idx>Description: triggered when someone leaves the party line to disconnect from the bot. mask is matched against the handle and can contain wildcards. Note that the connection may have already been dropped by the user, so don't send output to the idx.
Module: core
SENT (stackable)
bind sent <flags> <mask> <proc>
proc-name <handle> <nick> <path/to/file>Description: after a user has successfully downloaded a file from the bot, this binding is triggered. mask is matched against the handle of the user that initiated the transfer and supports wildcards. nick is the actual recipient (on IRC) of the file. The path is relative to the dcc directory (unless the file transfer was started by a script call to 'dccsend', in which case the path is the exact path given in the call to 'dccsend').
Module: transfer
RCVD (stackable)
bind rcvd <flags> <mask> <proc>
proc-name <handle> <nick> <path/to/file>Description: triggered after a user uploads a file successfully. mask is matched against the user's handle. nick is the IRC nickname that the file transfer originated from. The path is where the file ended up, relative to the dcc directory (usually this is your incoming dir).
Module: transfer
CHAT (stackable)
bind chat <flags> <mask> <proc>
proc-name <handle> <channel#> <text>Description: when a user says something on the botnet, it invokes this binding. Flags are ignored; handle could be a user on this bot ("DronePup") or on another bot ("Eden@Wilde") and therefore you can't rely on a local user record. The mask is checked against the entire line of text and supports wildcards.
NOTE: If a BOT says something on the botnet, the BCST bind is invoked instead.
Module: core
LINK (stackable)
bind link <flags> <mask> <proc>
proc-name <botname> <via>Description: triggered when a bot links into the botnet. botname is the botnetnick of the bot that just linked in; via is the bot it linked through. The mask is checked against the botnetnick of the bot that linked and supports wildcards. flags are ignored.
Module: core
DISC (stackable)
bind disc <flags> <mask> <proc>
proc-name <botname>Description: triggered when a bot disconnects from the botnet for whatever reason. Just like the link bind, flags are ignored; mask is matched against the botnetnick of the bot that unlinked. Wildcards are supported in mask.
Module: core
SPLT (stackable)
bind splt <flags> <mask> <proc>
procname <nick> <user@host> <handle> <channel>Description: triggered when someone gets netsplit on the channel. Be aware that this may be a false alarm (it's easy to fake a netsplit signoff message on some networks); mask may contain wildcards and is matched against '#channel nick!user@host'. Anyone who is SPLT will trigger a REJN or SIGN within the next wait-split (defined in the config file) minutes.
Module: irc
REJN (stackable)
bind rejn <flags> <mask> <proc>
procname <nick> <user@host> <handle> <channel>Description: someone who was split has rejoined. mask can contain wildcards, and is matched against '#channel nick!user@host'.
Module: irc
FILT (stackable)
bind filt <flags> <mask> <proc>
procname <idx> <text>Description: party line and file system users have their text sent through filt before being processed. If the proc returns a blank string, the text is considered parsed. Otherwise, the bot will use the text returned from the proc and continue parsing that.
Module: core
NEED (stackable)
bind need <flags> <mask> <proc>
procname <channel> <type>Description: this bind is triggered on certain events, like when the bot needs operator status or the key for a channel. The types are: op, unban, invite, limit, and key; the mask is matched against '#channel type' and can contain wildcards. flags are ignored.
Example:
bind need - "% op" needop < handles only need op
bind need - "*" needall < handles all needsModule: irc
FLUD (stackable)
bind flud <flags> <type> <proc>
procname <nick> <user@host> <handle> <type> <channel>Description: any floods detected through the flood control settings (like 'flood-ctcp') are sent here before processing. If the proc returns 1, no further action is taken on the flood; if the proc returns 0, the bot will do its normal "punishment" for the flood. The flood types are: pub, msg, join, or ctcp (and can be masked to "*" for the bind); flags are ignored.
Module: server
NOTE (stackable)
bind note <flags> <mask> <proc>
procname <from> <to> <text>Description: incoming notes (either from the party line, someone on IRC, or someone on another bot on the botnet) are checked against these binds before being processed. The mask is matched against the receiving handle and supports wildcards. If the proc returns 1, Eggdrop will not process the note any further. Flags are ignored.
Module: core
ACT (stackable)
bind act <flags> <mask> <proc>
proc-name <handle> <channel#> <action>Description: when someone does an action on the botnet, it invokes this binding. flags are ignored; the mask is matched against the text of the action and can support wildcards.
Module: core
WALL (stackable)
bind wall <flags> <mask> <proc>
proc-name <handle> <msg>Description: when the bot receives a wallops, it invokes this binding. flags are ignored; the mask is matched against the text of the wallops msg. Note that RFC shows the server name as a source of the message, whereas many IRCds send the nick!user@host of the actual sender, thus, Eggdrop will not parse it at all, but simply pass it to bind in its original form. If the proc returns 1, Eggdrop will not log the message that triggered this bind.
Module: server
BCST (stackable)
bind bcst <flags> <mask> <proc>
proc-name <botname> <channel#> <text>Description: when a bot broadcasts something on the botnet (see 'dccbroadcast' above), it invokes this binding. flags are ignored; the mask is matched against the message text and can contain wildcards. 'channel' argument will always be '-1' since broadcasts are not directed to any partyline channel.
It is also invoked when a BOT (not a person, as with the CHAT bind) 'says' something on a channel. In this case, the 'channel' argument will be a valid channel, and not '-1'.
Module: core
CHJN (stackable)
bind chjn <flags> <mask> <proc>
proc-name <botname> <handle> <channel#> <flag> <idx> <user@host>Description: when someone joins a botnet channel, it invokes this binding. The mask is matched against the channel and can contain wildcards. flag is one of: * (owner), + (master), @ (op), or % (botnet master). Flags are ignored.
Module: core
CHPT (stackable)
bind chpt <flags> <mask> <proc>
proc-name <botname> <handle> <idx> <channel#>Description: when someone parts a botnet channel, it invokes this binding. The mask is matched against the channel and can contain wildcards. Flags are ignored.
Module: core
TIME (stackable)
bind time <flags> <mask> <proc>
proc-name <minute> <hour> <day> <month> <year>Description: allows you to schedule procedure calls at certain times. mask matches 5 space separated integers of the form: "minute hour day month year". minute, hour, day, month have a zero padding so they are exactly two characters long; year is four characters. Flags are ignored.
Module: core
AWAY (stackable)
bind away <flags> <mask> <proc>
proc-name <botname> <idx> <text>Description: triggers when a user goes away or comes back on the botnet. text is the reason than has been specified (text is "" when returning). mask is matched against the botnet-nick of the bot the user is connected to and supports wildcards. flags are ignored.
Module: core
LOAD (stackable)
bind load <flags> <mask> <proc>
proc-name <module>Description: triggers when a module is loaded. mask is matched against the name of the loaded module and supports wildcards; flags are ignored.
Module: core
UNLD (stackable)
bind unld <flags> <mask> <proc>
proc-name <module>Description: triggers when a module is unloaded. mask is matched against the name of the unloaded module and supports wildcards; flags are ignored.
Module: core
NKCH (stackable)
bind nkch <flags> <mask> <proc>
proc-name <oldhandle> <newhandle>Description: triggered whenever a local user's handle is changed (in the userfile). mask is matched against the user's old handle and can contain wildcards; flags are ignored.
Module: core
EVNT (stackable)
bind evnt <flags> <type> <proc>
proc-name <type>Description: Description: triggered whenever one of these events happen; flags are ignored; valid events are:
sighup
called on a kill -HUP <pid>
sigterm
called on a kill -TERM <pid>
sigill
called on a kill -ILL <pid>
sigquit
called on a kill -QUIT <pid>
save
called when the userfile is saved
rehash
called just after a rehash
prerehash
called just before a rehash
prerestart
called just before a restart
logfile
called when the logs are switched daily
loaded
called when the bot is done loading
userfile-loaded
called after userfile has been loaded
connect-server
called just before we connect to an IRC server
init-server
called when we actually get on our IRC server
disconnect-server
called when we disconnect from our IRC server
Module: core
LOST (stackable)
bind lost <flags> <mask> <proc>
proc-name <handle> <nick> <path> <bytes-transferred> <length-of-file>Description: triggered when a DCC SEND transfer gets lost, such as when the connection is terminated before all data was successfully sent/received. This is typically caused by a user abort.
Module: transfer
TOUT (stackable)
bind tout <flags> <mask> <proc>
proc-name <handle> <nick> <path> <bytes-transferred> <length-of-file>Description: triggered when a DCC SEND transfer times out. This may either happen because the dcc connection was not accepted or because the data transfer stalled for some reason.
Module: transfer
Several bindings pay attention to the value you return from the proc (using 'return <value>'). Usually, they expect a 0 or 1, and returning an empty return is interpreted as a 0. Be aware if you omit the return statement, the result of the last Tcl command executed will be returned by the proc. This will not likely produce the results you intended (this is a "feature" of Tcl).
Here's a list of the bindings that use the return value from procs they trigger:
MSG
Return 1 to make Eggdrop log the command as:
(nick!user@host) !handle! command
DCC
Return 1 to make Eggdrop log the command as:
#handle# command
FIL
Return 1 to make Eggdrop log the command as:
#handle# files: command
PUB
Return 1 to make Eggdrop log the command as:
<<nick>> !handle! command
CTCP
Return 1 to ask the bot not to process the CTCP command on its own. Otherwise, it would send its own response to the CTCP (possibly an error message if it doesn't know how to deal with it).
FILT
Return "" to indicate the text has been processed, and the bot should just ignore it. Otherwise, it will treat the text like any other.
FLUD
Return 1 to ask the bot not to take action on the flood. Otherwise it will do its normal punishment.
RAW
Return 1 to ask the bot not to process the server text. This can affect the bot's performance by causing it to miss things that it would normally act on -- you have been warned.
CHON
Return 1 to ask the bot not to process the partyline join event.
CHOF
Return 1 to ask the bot not to process the partyline part event.
WALL
Return 1 to make Eggdrop not log the message that triggered this bind.
NOTE
Return 1 to make Eggdrop not process the note any further. This includes stacked note bindings that would be processed after this one, as well as the built-in eggdrop note handling routines.
MSGM
Return 1 to make Eggdrop not log the message that triggered this bind.
PUBM
Return 1 to make Eggdrop not log the message that triggered this bind.
NOTC
Return 1 to make Eggdrop not log the message that triggered this bind.
