SUNiNET - Your Eggdrop & TCL resources site
[ Home Eggdrop TCL Links About ]

Guide to TCL scripting for Eggdrop 1.6

[ Previous ] [ Index ] [ Next ]
[ Text version ]

4. Binding events and creating procedures

In this chapter you will learn what I consider the two most important commands in TCL, bind and proc.
These two commands allow you to make the bot perform the actions you tell it do to when a certain event is triggered.

4.1 Binding events

With the bind command you can make the bot react on an event like a command, a message or a ctcp.
The syntax of the bind command is bind <type> <flags> <command> <procedure>.
I'll go through this now step-by-step.

The <type> is what event you want to make the bot react on.
For example, ctcp would bind a ctcp or msg would bind a message.
You can find all the available types in eggdrop/doc/tcl-commands.doc.

The <flags> refer to the flags you give users in your Eggdrop.
This goes in the form of <global flag>|<channel flag>.
Here are a few examples to explain it faster and easier:

#Bind to everyone (including users who are not in the userlist)
bind <type> - <command> <procedure>

#Bind to everyone (including users who are not in the userlist)
bind <type> * <command> <procedure>

#Bind to global owners
bind <type> n <command> <procedure>

#Bind to global operators
bind <type> o <command> <procedure>

#Bind to channel masters (NOT global masters)
bind <type> -|m <command> <procedure>

#Bind to global masters and channel masters
bind <type> m|m <command> <procedure>

#Bind to global operators and channel owners
bind <type> o|n <command> <procedure>

The <command> is on what parameter the bind is triggered. If you would use the bind type msg, the parameter would be the first word of the message or if you were to use the bind type dcc it would be the new partyline command you want to create.
For example, bind dcc <flags> test <procedure> would create a partyline command called test or bind msg <flags> hello <procedure> would make the bot react when it receives a message with "hello" as its first word.

The <procedure> is simply what procedure the bot must run when the bind is triggered.

4.2 Calling upon procedures

A procedure is nothing more than a set of commands that you can call upon anywhere in your TCL script. You call upon a procedure by placing somewhere in your script <procedure> [parameters] (i.e. in an other procedure, somewhere between brackets or just in your main script).
These procedures perform a set of commands which, for example, can return a value after checking a few factors or can send something to the IRC server immediantly.

4.3 Creating a procedure

With the proc command you can create procedures.
The syntax of the proc command is proc <name> { <parameters> } { <body> }.

The <name> is how you want to call the procedure you are creating.
This can be anything you want and you will have to use this name when you want to call upon it.
In this guide I will start every procedures name with <bind type>:. This isn't required, but it's (in my opinion) handy to do so, because this way you immediantly know what a proc is for which is especially handy when you are working with large scripts.

The <parameters> are the variables the procedure must put its received parameters in.
You need to specify a variable for each parameter here that will be sent to the procedure. All the variables you give have to be seperated by spaces.
For example, if you would have the line proc test { nick channel } { <body> } and somewhere else in your script test MyNick #test, the procedure would put "MyNick" in the variable "$nick" and "#test" in the variable "$channel".
The procedure also always wants to know the exact amount of parameters it is given. If you give the procedure 4 variables for example and you call upon it with 5 parameters, Eggdrop will give an error similar to 'proc called with too many arguments' or if you call upon it with 3 parameters and have given it 4 variables, it will give an error similar to "no argument given for ...".

There is one exception to this rule though. If you call the last variable of <parameters> "args" than you may call upon the procedure with more parameters than you have defined in <parameters>.
In this case all of the parameters you give to the procedure up from the point where the argument "args" start is put in $args. They are put into $args as if the list command was used to make $args. You'll learn what the list command is later on, but you should already know about the difference between "args" and any other name.
For example if you would call upon proc test { nick channel args } { <body> } with test $nick $channel $handle $host, it would put the passed on $nick in $nick, $channel in $channel and both $handle and $host in $args, but I strongly discourage using the "args" parameter until you understand what lists are and what the list command does.

The <body> is basicly the commands that you want the procedure to execute.
The body doesn't have to be on one line, that's why the proc starts with an open-brace. You can put a new command on each new line and it'll still be part of the procedure until you close the body up with a close-brace.

Besides calling upon procedures yourself, you will most likely want to use bind aswell. The bind command runs a procedure when a certain event is triggered. Besides information about the bind, tcl-commands.doc also gives you information about with what parameters the procedure will be called upon when the bind is triggered and what information the parameters will contain.

Lets take a look at the bind msg explanation from tcl-commands.doc:

  (1)  MSG
       bind msg <flags> <command> <proc>
       procname <nick> <user@host> <handle> <arg>

Everything behind procname are the parameters that will be sent to the procedure. Most procedures for bind msg will thus look like proc msg:test { nick host hand arg } { <body> }.

4.4 Ending a procedure

Next to of course just ending the body of your procedure with a close-brace, you can use the command return to let the procedure end anywhere within the body. How the procedure will end depends on how you use the return command.
The basic syntax of the return command is return <message>.

The <message> is what the procedure must output. In general you end the proc with either 0 or 1 as <message>.
In most cases using 0 as <message> will result in a quiet return where the bot goes it's normal way as it would do if the bind didn't exist, meaning that it won't log anything and won't override built-in features like flood protection for example either.
When you are returning with 1 the bot usually either logs the command that has been performed by i.e. a bind dcc or it doesn't react itself on the event (when you are using bind flud for example, returning 1 will make the bot not react on the flood but let the TCL script handle it entirely).
You can find more in tcl-commands.doc about how the different binds react on which return value.

Besides 0 or 1 you can also have the procedure return text if you want.
That would make the procedure roughly said an interactive variable. You would still have to call upon it like proc [parameters], but it would return information like a variable would.
For example, proc test { nick } { return "Hello $nick." } would be the same as set test "Hello $nick.", only you would call upon them differently and you could let the procedure check things and possibly output something different than the input, but still having the output like it's a variable.

[ Text version ]
[ Previous ] [ Index ] [ Next ]

Design & Graphics by Shawn Borton
Copyright © 2000-2005 Marijn van Zon