# A beginners guide to TCL with focus on Eggdrop.
# Please note this document was optimized for eggdrop 1.1.x
# MBTI [Made by The |mmortaL] - [email protected] (see section X for more credits)
# Date Completed: xx/xx/97

This document is made to help explain how to make TCL scripts for the eggdrop. It covers BASIC concepts, and programming.  I suggest that you have a copy of tcl-commands.doc handy, for this document will refer to it many a time.  I hope this helps in learning TCL and good luck!

## I - Triggers for code (Events/Binds) ##

Eggdrop operates on an event based system.  If I type 'hello' to the channel, the eggdrop matches that text against a list of events (referred to as binds) for channel commands.  The eggdrop contains many events: pubm (public text matching), mode (channel mode changes), nick (nick changes), join (joins to the channel), part (parts of the channel), and many others; they may be found in tcl-commands.doc.

Syntax for bind:

Example:

The type of bind is triggered when some one joins a channel, the '-' stands for any flag (you could have put an 'o' to signify to only execute the procedure when he has Op Access) and the match matches the address/nick/channel (This accepts wild cards, explain further in section IV). The procedure 'join:join' is the part of code which it executes if the bind is matched up correctly.

Another Example:

If someone in DCC chat party line, with channel op access (and console is to that channel), or global op access types '.sayhi' it will execute the procedure 'dcc:sayhi'.  In Eggdrop 1.1.x the default binds are prefixed with the type of bind then a ':' then the name; in this document I will also follow that form.

A list of flags may be obtained via .help whois in DCC chat

  (back to top)

## II - Procedures Explained ##

A procedure is a section of code which may be called by anything in a program. For Eggdrop's use, this where all the code goes for on events.  When an action takes place and a bind is triggered it calls a procedure to take action.  For example if you wanted to write your own auto-op script, when ever a person with op access joins the channel it would call a procedure and then the procedure would send the command to give ops.

syntax for procedures:

When a bind is triggered it gives certain information to the procedure that is required to do any thing, information such as nicks, hosts, handles, and any other arguments needed.  This was taken from tcl-commands.doc from the info of the bind pubm.

What this says is when ever a pubm bind is triggered you need variablesto put these 5 pieces of information.  You can call the variables any thing you choose, it could be a, b, c, d and e. I suggest using something short, and to the point; such as nick, host, hand, chan, and text.
Example of a bind, and a procedure:

# The Bind #
    public match (pubm)
    flags needed to trigger: None (- means none)
    triggered by: hello
    procedure to be called: pubm:hello

# The Procedure #
    putserv is a command which sends text to the server.
    PRIVMSG is a server command for sending private msgs.
    $chan is the variable that will contain the channel which it occurred on
    $nick is the variable that will contain the nickname of who said "hello"

!!!PLEASE NOTE!!!: When using RAW IRC commands you need to put a ':' in front of text that has more than one word, such as the message of a msg.

The same thing can also be accomplished with this

The bind is basically the same I just changed the name of the procedure.  In the procedure I changed the name of the variables, I used 'n' instead of 'nick' and so on.  However I did use a different command.  Puthelp is a Eggdrop command which queues the text so as not to flood the bot.  I HIGHLY SUGGEST USING THIS!  =)

syntax for puthelp:

Example:

same syntax applies for putserv and putmode as well

If you notice <message> is only one space, that's why you need the ""'s (quotes).  If you do not put the quotes there you get the error msg: TCL error: called "puthelp" with too many arguments.  So you put the quotes to show that it belongs only in one spot.

Procedures can also call themselves, without the need for a bind.  For instance if there is one particular thing you must have done in ALL of your procedures; and don't feel like writing it.  In this example you have to send a msg too the person every time he does a command, here is
some sample code:

noaccess is accessable by any procedure in the bot, so any time you want to say some one doesn't have access, just call noaccess.

!!!PLEASE NOTE!!!: I've seen this question about 100 times, and even asked it my self once.  Never use 'args' as a variable in procedures it does strange things.  It puts brackets ({}'s) around the variables and causes big problems if one does not know how to use it.

  (back to top)

## III - Variables, If statements ###

Variables

A variable is where you assign a symbol, or word (such as $nick) a value. This value can be a string (words, or sentences) or a numeral.  In TCL there are 2 main types of variables: global, and private.  A global variable is when you want to store information in it, and wish other procedures to use.  A private variable could be a variable that you use in a procedure, which does not need to be used outside of that procedure.

syntax for setting a variable:

Example:

To unset a variable, simply use the command unset.

syntax for unsetting a variable:

Example:

When using the variable, put a '$' infront of it so the procedure understands it is a variable.  So the variable 'name' would be used in the code as '$name'.

Additional Notes: To distinguish between a global, and private variable simply use a 'global' command at the top of the proc.  When setting the variable, or using a global statement the '$' is not needed.

syntax for global:

Example:

Eggdrop has some pre-set global variables, such as the bot's nick ($botnick). They are (taken from tcl-commands.doc):

  botnick
    current nickname the bot is using, ie 'Valis' or 'Valis0', etc

  botname
    current nick!user@host that the server sees, ie '[email protected]'

  server
    current server the bot is using, ie 'irc.math.ufl.edu:6667'

  version
    current bot version (ie: "1.1.2+pl1 1010201 pl1");
      first item is the text version, second item is a numerical version,
      and any following items are the names of patches that have been added

  uptime
    unixtime value for when the bot was started

To use them inside a proc, you must declare them as global at the beginning of your proc (e.g 'global botnick').  You'll see better uses for variables in the section IV


If Statement:

One of the most important aspects of a programming language is an 'if' statement.  It will return a TRUE, or FALSE statement and execute the commands with such association.  If statement use a logic type of approach; like:

syntax for if:

or

notice the omission of else in the second example, both formats will perform the same function.

These are some of the operators avaliable:

Example:

This says if the value of $nick is the same as the value of $botnick then it sends a msg to the chan saying "I am $nick", and if not saying "I am not $nick".

!!!PLEASE NOTE!!!: IT IS CASE SENSITIVE
!!!PLEASE NOTE!!!: IT IS CASE SENSITIVE
!!!PLEASE NOTE!!!: IT IS CASE SENSITIVE
!!!PLEASE NOTE!!!: IT IS CASE SENSITIVE
Did you get that? Maybe once more
!!!PLEASE NOTE!!!: IT IS CASE SENSITIVE

Case Sensitive Defined: Where the CaPs MaTtErs.  Such as 'HELLO' is not the same as 'hello'.

Now this is where TCL starts to differ from other programming languages that I've encountered.  Lets say you want to write a check to see if $nick is an op on $chan.  Well some languages could use an operator like if $nick isop $chan. Not TCL...

There is a procedure called 'isop'.
This was taken from tcl-commands.doc

syntax for isop:

     returns: "1" if someone by that nickname is on the channel and has chop;
              "0" otherwise

How do you use this in a if statement? This is how

Example:

Now the same can also be written like this:

and so on.

Or like this:

or

As you can see you have many choices here, I suggest, since an else statement is optional, you use the if statement where the statement is true or false and execute the code, and don't use an else statement.  What I mean by this is lets say you want the following: if the bot isn't an op then msg the chan and ask for ops.

You can do this 2 ways, here is the harder way:

As you can see I didn't want anything to happen if he does have ops, so you could change the first line to some thing like:

or

TCL will interpert

the same as

If the statement is true it executes the {}. So there is no need for a == 1

As will

! is the negate of whats in the []

Either one would suit you fine.

There are 100's more commands like this for anything from checking flags, to doing ANY THING with the eggdrop.  Again all in tcl-commands.doc (it almost sounds like I'm doing a commercial for tcl-command.doc dosn't it?).

  (back to top)

## IV - String Manipulation Commands (string and l commands) ##

You want to make a public kick program, so ops can type !kick <nick> <reason>. One problem, how do you extract those arguments from $text (or equivalent variable)?  lindex, and lrange.

These are core tcl commands so they won't be found in tcl-commands.doc here is there descriptions: (from the TCL help file).

NAME
lindex - Retrieve an element from a list

SYNOPSIS
lindex list index 

DESCRIPTION
This command treats list as a Tcl list and returns the index'th element from it (0 refers to the first element of the list).  In extracting the element, lindex observes the same rules concerning braces and quotes and backslashes as the Tcl command interpreter; however, variable substitution and command substitution do not occur.  If index is negative or greater than or equal to the number of elements in value, then an empty string is returned.  If index has the value end, it refers to the last element in the list.

Example:

would return 5

would return c (0 is the first parameter in the string!)

Now here is the public kick program:

# The Bind #
    public command (pub)
    flags needed to trigger: Channel Specific/Global Operator
    command to trigger: !kick <person>
    procedure to be called: pub:kick

# The Procedure #
    whom is a private variable and will be erased when the proc is finished.
    The lindex takes the first parameter in $text (which is the person) and
    sets it to whom the putserv kicks the person.

What if you wanted to add a definable kick msg?  Make the program a little more fancy.  The command is lrange, it takes the parameters from N'th index to N'th index.  Here it is from the TCL help file:

NAME
lrange - Return one or more adjacent elements from a list

SYNOPSIS
lrange list first last

DESCRIPTION
List must be a valid Tcl list.  This command will return a new list consisting of elements first through last, inclusive.  First or last may be end (or any abbreviation of it) to refer to the last element of the list.  If first is less than zero, it is treated as if it were zero.  If last is greater than or equal to the number of elements in the list, then it is treated as if it were end.  If first is greater than last then an empty string is returned.  Note: "lrangelist first first" does not always produce the same result as "lindexlist first" (although it often does for simple fields that aren't enclosed in braces); it does, however, produce exactly the same results as "list [lindexlist first]"

So you would need to take parameter 1 for text, and to the end...

This is how you would do it:

Lets make it even more spoofy, what about if $nick isn't on the channel?  Well we need an if statement don't we?  Look in tcl-commands.doc for the command.

Here is the program:

This is from the TCL help file, I'll give examples for a few, but I'm sure you can figure it out

NAME
string - Manipulate strings

SYNOPSIS
string option arg ?arg ...? 

DESCRIPTION
Performs one of several string operations, depending on option.  The legal options (which may be abbreviated) are:

string compare string1 string2
    Perform a character-by-character comparison of strings string1 and string2
    in the same way as the C strcmp procedure.  Return -1, 0, or 1, depending
    on whether string1 is lexicographically less than, equal to, or greater
    than string2.

string first string1 string2
    Search string2 for a sequence of characters that exactly match the
    characters in string1.  If found, return the index of the first character
    in the first such match within string2.  If not found, return -1.

string index string charIndex
    Returns the charIndex'th character of the string argument.  A charIndex of
    0 corresponds to the first character of the string.  If charIndex is less
    than 0 or greater than or equal to the length of the string then an empty
    string is returned.

string last string1 string2
    Search string2 for a sequence of characters that exactly match the
    characters in string1.  If found, return the index of the first character
    in the last such match within string2.  If there is no match, then return
    -1.

string length string
    Returns a decimal string giving the number of characters in string.

string match pattern string
    See if pattern matches string; return 1 if it does, 0 if it doesn't.
    Matching is done in a fashion similar to that used by the C-shell.  For
    the two strings to match, their contents must be identical except that the
    following special sequences may appear in pattern:

    *     Matches any sequence of characters in string, including a null
            string.
   
    ?       Matches any single character in string.
   
    [chars] Matches any character in the set given by chars.  If a sequence of
            the form x-y appears in chars, then any character between x and y,
            inclusive, will match.
   
    \x     Matches the single character x. This provides a way of avoiding the
            special interpretation of the characters *?[]\ in pattern.

string range string first last
    Returns a range of consecutive characters from string, starting with the
    character whose index is first and ending with the character whose index
    is last.  An index of 0 refers to the first character of the string.  An
    index of end (or any abbreviation of it) refers to the last character of
    the string.  If first is less than zero then it is treated as if it were
    zero, and if last is greater than or equal to the length of the string
    then it is treated as if it were end.  If first is greater than last then
    an empty string is returned.

string tolower string
    Returns a value equal to string except that all upper case letters have
    been converted to lower case.

string toupper string
    Returns a value equal to string except that all lower case letters have
    been converted to upper case.

string trim string ?chars?
    Returns a value equal to string except that any leading or trailing
    characters from the set given by chars are removed.  If chars is not
    specified then white space is removed (spaces, tabs, newlines, and
    carriage returns).

string trimleft string ?chars?
    Returns a value equal to string except that any leading characters from
    the set given by chars are removed.  If chars is not specified then white
    space is removed (spaces, tabs, newlines, and carriage returns).

    This is usefull for creating bans!!!
    Here is a sample kick ban script I wrote...

    Notice I had to extract the person who is getting KB'd from text.  I then
    had to get his host from the command getchanhost (tcl-commands.doc), and
    then make it a usable mask host for bans.  However maskhost returns it's
    value in *!user@*.machine.end I need a *!*, so I used 'trimleft' and it
    did my job.

string trimright string ?chars?
    Returns a value equal to string except that any trailing characters from
    the set given by chars are removed.  If chars is not specified then white
    space is removed (spaces, tabs, newlines, and carriage returns).

string wordend string index
    Returns the index of the character just after the last one in the word
    containing character index of string.  A word is considered to be any
    contiguous range of alphanumeric or underscore characters, or any single
    character other than these.

string wordstart string index
    Returns the index of the first character in the word containing character
    index of string.  A word is considered to be any contiguous range of
    alphanumeric or underscore characters, or any single character other than
    these.

  (back to top)

## V - Loops ##

This section follows the following loops: foreach, for, and while (thanxs for the help from the people on the Doc Project List).

Foreach a list of items, and goes through each setting it as a var then executing commands, and goes to the next.

This proc will deop any one on the chan who doesn't have +o.

syntax for foreach:

chanlist gives a list of people on the chan.

# The Procedure #
    It first checks to make sure he's an op
    Then checks to see if he's a global op
    Then checks to see if he's a chan op
    If all work out, he is deoped, if not nothing happens

syntax for while:

That will flood the bot off but you get the idea?

It will execute body until the operator changes value

syntax for for:

First of all this script will count from 1 to 6

The first set of {}'s happens only when U execute the for statement the second {}'s is the stopper.  When that is true it will stop the body the third {} is every time you complete body, do it, then do body again


## VI - User-get/User-set ##

Each user on eggdrop has a special field called "xtra" which lets you store whatever you like about users.  The field size is limited so don't get too excited.  :)

It is a line where you (and your scripts) can store things the way you want to, just like the "comment" line each user has.  But to improve it's functionality, there are two procedures which come with the "toolkit.tcl" (comes in eggdrops scripts dir) to access this field in a more organized way.

The best thing is to *only* access the xtra field using these two procedures. Make sure no other script is accessing it another way (simple way to check this is to 'grep setxtra *' and 'grep getxtra *' in your scripts directory).

The procs to use:

You can have any fieldname you like, like 'url' to store the users homepage, 'birthday', etc (check out 'set whois-fields' in eggdrops config file, which makes use of exactly these fields!).

You name the field, set the value with user-set and don't have to worry anymore.  And retore the value with user-get afterwards, as in:

  (back to top)

## VII - Return command ##

The return command has two uses.  The first is to stop the current proc.  The second, and most usefull is the the abiity to return a number, or text.

Heres an example:

chkaccess would return a 0, or 1 and then it would op them based on the return.

This is from tcl-commands.doc:

    Several bindings pay attention to the value you return from the proc
    (using "return $value").  Usually they expect a 0 or 1, and failing
    to return any value is interpreted as a 0.

    Here's a list of the bindings that use the return value from procs
    they trigger:

    MSG   Return 1 to make the command get logged like so:
          (nick!user@host) !handle! command

    DCC   Return 1 to make the command get logged like so:
          #handle# command

    FIL   Return 1 to make the command get logged like so:
          #handle# files: command

    PUB   Return 1 to make the command get logged like so:
          <<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 1 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.

    WALL  Return 1 to make the command get logged liked so:
          !nick! msg

syntax for return:
    return <numeric>

Example:
    return 0

  (back to top)

## VIII - Good Programming habits ##

Many people load tons of scripts at once, and they don't want conflicts! There are a few ways to help avoid conflicts.  USE RETURN 0 AS LITTLE AS POSSIBLE or else it will stop all bind searching after your proc..  Here are some other ideas

(1) Label your procs sensable.  Such as in my scripts I some times use
        proc mbti:antiidle {} {}
    Not some thing like
        proc script {} {}

(2) Same with your variables.  If you use '-'s in your variables when calling
    them you must ${mbti-antiidle} some thing like that

(3) If your script uses timers make it compatable so you don't don't have too
    many of them (see examples in IX)

If you've noticed in all my procecdures I've used an indentation system, I suggest you also use one. Most common methods consist of either a TAB or Double Spacing.

<N> where N is the number of spaces

Example

    proc bla {} {
    <1> globlal testchan
    <1> if {[botisop $testchan]} {
    <1> <2> puthelp "PRIVMSG $testchan :I'm oped!
    <1> }
    }

  (back to top)

## IX - Program Examples, then explained. ##

I've taken some of these from programs I've written, or I just made them up =) (Many thanxs to the people on the Doc Project Listserv for suggestions!)

###

# The Bind #
    Public Match
    Op Access on that Channel, or Global Op Access
    Trigger: !rules
    Proc Name: pubm:ab_rules

# The Procedure #
    If the first parameter in $text is valid it will be set to who; if it doesn't exists
    whom will be "".  Now it says, if who has no value msg the channel the rules
    of the channel But if there is a a nick put a msg to $nick

####


###

# This is fairly simple, put a global statement for each of the global variables, because
# you need to access them.  Send the msg to the channel, and then re-set the timer.

# The Bind #
    This script does not function with a bind.
    Trigger: "if {!info exists antiidleloaded}" checks to see if script is running
    Proc Name: proc:antiidle

# The Procedure #
    If info does not exist for $antiidleloaded, timer for proc:antiidle begins, if it
    does exists, proc:antiidle continues running.
    When timer fires, put $antiidlemsg to $antiidlechan and start another timer

###


###

This is a fairly easy script, the only new thing is the newflags.  Eggdrop lets you add as many new flags as there aren't used.
Set newflag[num] z
where [num] is a number that doesn't exists...

set newchanflag[num]
Ditto :P

# The Bind #
    Join on channel
    AutoOp and AutoVoice Access on that Channel
    Trigger: users with +i or +v joining the channel
    Proc Name: join:mbti_autoop
                        join:mbti_autovoice
                        join:mbti_cautoop
                        join:mbti_cautovoice

# The Procedure #
    When join bind is triggered by specified users, pushmode $nick flag $chan
    or matchchanattr $hand flag $chan is true pushmode $nick flag $chan

###


###

foreach nick [chanlist $chan] basicly says to do this for every one in the chan.

One check to see if he has ops, if he dosn't and he has OP access then op him!!

Then If he has ops, and he's supposed to be deoped them deop him!
###

  (back to top)



Advertise.zip
Long Text Protection.zip
MassJoin.zip
Newshoutcast.tcl
action.fix.tcl
activechatter.tcl
activeusers.tar.gz
advertise.tcl
allprotection.zip
autogreet.zip
autolimit.tcl
autolimit.zip
autoreop.tcl
autovoice.tcl
away.tcl
badnick.tcl
badnickident.tcl
badwords.tcl
bestweather1.6.2.tar.gz
blacklist1.3.zip
bogushtml.zip
bogustrivia.zip
bottalk.tcl



bottalk.tcl.gz
chanpro.tcl
chanstats.tcl
chanstats.zip
cloneflood.tcl
control.tcl
count.tcl
counter.tcl
cute.tcl
dns.tcl
dwhois.tcl
eggdrop.php
eggdrop1.6.20.tar.bz2
eggdrop1.6.21.tar.gz
eggshout-0.2.tar.gz
flood.tcl
geoip.zip
google.tcl
greet.tcl
greetd.tcl
guard.tcl
guard102.tcl.gz
guardian.tcl
horoscope.tcl
incith-google-1.8.8g.tar.gz
ip-hide.tcl
ip.tcl
ipinfo.tcl
ipinfo5.zip
joinflood.tcl
longtext.tcl
meteo.tar.gz
newsvr.tcl
next.tcl
nickdetector.zip
notes2.tcl
pcc.tcl
ping.tcl
ping2.tcl
protect.tcl
protection.tcl
puisi.tcl
pv.tcl
ques5.tcl
quitban.tcl
quotes.tcl
radio_online.zip
randmsgtonick.zip
repeats.tcl
salam.tcl
sc_serv.conf
seen.tar.gz
seen.tcl
shiko.tcl
shoutcast.tar.gz
shoutcast.tcl
simple_advertise.tcl.gz
slaps.tcl
sms.tcl
spamkicker.zip
splitdetect.tcl
sqltell.tcl.gz
ssh.tcl
svrport.tcl
swearkick.tcl
swearkick.zip
sysinfo.tcl
tkbadword-0.9.tcl.bz2
translate.tcl
version.tcl
watak.tcl
weather.tar
weather3.4.1.tcl.gz
weather425.tcl.gz
yahoo.tcl
youtube.tcl