Guide to TCL scripting for Eggdrop 1.6

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


8. Working with lists

In this chapter you will learn what lists are and how to break them apart.

8.1 What lists are

A list is simply said a set of objects, unlike a string which is a set of characters. The object on itself can be a string again or another list with a new set of objects.
These objects are usually seperated by spaces, but they can contain spaces themselves too. Where an object in a list starts and stops can be defined with open and close braces.

The commands that will be discussed in the paragraphs 8.3, 8.4, 8.5 and 8.6 treat what they receive as input as lists.
This means that if you input something into it that has braces in it, it will see this as the start and end of an object within the list, so be carefull with these commands when you are processing nicknames for example.

It will also add braces if required, like for instance when you have brackets in what you input into the command, in that case braces are added to mark the start and end of an object.

A small example:
If you were to have the list "test {foo bar} temp", than the first object of this list would be "test", the second "foo bar" (not "{foo" and "bar}", because the braces mark the start and end of the object) and the third "temp".

Like said above, an object can also contain a new list with new objects. This might seem strange but I'll give an example.
If you were to have the list "test {foo {foo bar}} temp" than "foo {foo bar}" would be the second object.
If you were to break that apart again than the first object would be "foo" and the second "foo bar" and so on. Just think of it like having a large box, with a smaller box inside that one and an even smaller box inside that one again. Pretty much the principle of a Russian Matryoshka doll if you know what that is :-).

Lists can be contained within strings, but they can also be the output of a command.
The most important thing is to watch out with the commands you're using and know whether they are processing what you put into them as a list or a string and whether they output it as a list or a string, because if they process it as a list you will have to make sure the objects in it are the way you want them and not have unforseen braces, brackets or spaces that mess the whole thing up.

8.2 Creating lists

You can create lists with the list command.
The syntax of a list command is list [object(s)].

The [object(s)] are the objects that you want in the list. You must seperate each object with a space and you can define specifically where an object starts and stops with braces like said above like said in the previous paragraph.

The list command outputs a list compiled of the objects that it was given.
For example list "test" {foo bar} "temp" would return a list in which the first object is "test", the second "foo bar" and the third "temp".

8.3 Retrieving an object from a list

Gettings object from lists is fairly easy. The command for this is lindex.
The syntax of a lindex command is lindex <list> <number>.

The <list> is the list from where the object must be retrieved.
This can be anything from a string containing a list ($test can contain a list for example by putting the output of a list command in it with set) to a command, just as long as it's a valid list and not a plain string.

The <number> is the number of the object you want to retrieve.
Each object in the list has its own number, starting at 0. The first object is 0, the second 1, the third 2, and so on. It's a bit confusing, but if you're used to programming this will seem familiar.

A small example: lindex $test 5 returns the 6th object from the list that is in $test.

The lindex command outputs a string containing only the object itself without the open and close braces that mark the start and stop of the object if those are present in the list.

8.4 Retrieving multiple objects from a list

When you want to get more than one object we just change the command a bit. For this we use the command lrange.
The syntax of a lrange command is lrange <list> <start number> <end number>.

The <list> is the list from which the objects must be retrieved just like with the lindex command.

The <start number> is the number of the object from which the command should start cutting the list.
The numbering of the objects works in the same way as they do in the lindex command.

The <end number> is the number of the object at which the command should stop cutting the list.
Instead of a number you can also use the word end. This makes the command cut from the given start object until the end of the list.

A small example: lrange $test 3 7 returns the objects 4 through 8 from the list that is in $test or lrange $test 4 end would return the objects 5 and up until the end of the list in $test.

The lrange command outputs a newly compiled list of the objects you choose, leaving any open and close braces to mark the start and stop of an object which were already in the list intact and adds new ones if neccesary.

8.5 Determining how many objects a list has

This can be done with the llength command.
The syntax of a llength command is llength <list>.

The <list> is the list from which the objects must be retrieved just like with the lindex command.

This command outputs a string containing a number which equals the objects the list you specified holds, starting at 1 for one object and 0 if the list is empty.

8.6 Replacing objects in a list

You can also replace objects in a list. For this we use the command lreplace.
The syntax of a lreplace command is lreplace <list> <start number> <end number> [object(s)].

The <list> is the list from which the objects must be retrieved just like with the lindex command.

The <start number> is the number of the object from where the command should start replacing objects in the list.
The numbering of the objects works in the same way as they do in the lindex command.

The <end number> is the number of the object at which the command should stop replacing objects in the list.
Instead of a number you can also use the word end. This makes the command replace the objects from the given start object until the end of the list.

The [object(s)] is with what you want the command to replace the above given objects.
If you don't specify anything to replace the above objects with, they are removed from the list.
Note that this also has to be a valid list on its own.

A small example: lreplace $test 3 7 "foo" "bar" returns the list with the objects 4 through 8 replaced with the objects "foo" and "bar" or lreplace $test 4 end would return the list with the objects 5 and up until the end of the list removed from it.

The lreplace command outputs a newly compiled list with the replaced objects you choose, leaving the open and close braces that mark the start and stop of an object which were already in the list intact and adds new ones if neccesary.

8.7 Converting strings into lists

You can convert a string into a list with the split command.
The syntax of a split command is split <string> [character].

The <string> is the string you want to convert, which can be a string or a command that outputs a string.

The [character] is the character that will be used for splitting the string into objects.
Whenever split encounters the given character it will see it as a marker for the end of an object and the start of a new one.
If no character is provided a space is used to split the string.

The split command returns a newly compiled list in which the first object is everything in the <string> up to the [character], the second object everything between the second and third [character] and so on.
Any braces that are in the <string> will be considered a part of the object and new braces or backslashes will be added to enforce that the brace is a part of the object if neccesary.

A small example: split "test {foo bar} temp" would result in a list where the first object would be "test", the second "{foo", the third "bar}" and the fourth "temp". Also split "test.{foo.bar}.temp" . would result in the same thing.

8.8 Writing your own script

Now lets expand the auto-voice scripts again and make it a small greeting script aswell.
Make it so that both channels are in the same list and that you can set a different greeting for two nicks that can support up to 2 lines, where the nick with its greeting is in the same list (this isn't very practical but it makes you use more of the commands you've learned so far). Also show the greeting on all the channels, not only the ones where the bot doesn't voice.
This is already a bit harder than the previous scripts, but not too difficult yet. You can find an example here: example-ch8.tcl.
Also don't forget that this is an example, your script could do the very same thing and be completely different.


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


Design & Graphics by Shawn Borton of CalcioStar.com