TinTin++ Mud Client Manual
Get TinTin++ Mud Client at SourceForge.net. Fast, secure and Free Open Source software downloads
Lists
space
There are several different types of lists in tintin which behave in a fairly universal manner. To properly explain lists it's easiest to explain the most basic variable type first before discussing more complex types.
space
  • Basic variable: The standard key = value variable.
  • Simple list: A string that contains semicolon delimited fields. {a;b;c}. Can be saved as a variable.
  • Brace list: A string in which fields are delimited with braces. {a}{b}{c}. Brace lists cannot be stored as a variable because tables use braces as well, they must be stored as a simple list instead.
  • Table: Think of this as variables nested within another variable. Or as variables contained within another variable.
  • List: A table that uses integers for its indexes. Also known as an array. The #list command is a utility command for using tables as arrays.
space
Simple Variables
space
Example:
#variable {simple} {Hello World!}
#showme $simple
space
To see if the 'simple' variable exists you can use &simple which will display 0 if the variable does not exist, or the variable's index if it exists.
space
If you have multiple variables they are sorted alphabetically and numerically. While it's not all that relevant for simple variables, the first variable has index 1, the second variable index 2, and so on.
space
Variable names need to exist of letters, numbers, and underscores. If you need to use a non standard variable name this is possible using braces.
space
Example: #variable {:)} {Happy Happy!};#showme ${:)}
space
Variables can be accessed using their index. While primarily useful for tables it is possible to do this for simple variables. Use +1 for the first variable, +2 for the second variable, etc. Use -1 for the last variable, -2 for the second last variable, etc.
space
Example: #showme The first variable is: ${+1}
space
Removing Variables
space
To remove a variable, use #unvariable or #unvar (every command can be abbreviated). It's possible to remove multiple variables at once using #unvar {var 1} {var 2} {etc}
space
Variables are unique to each session, so if you have multiple sessions, removing a variable from one session won't remove it from other sessions.
space
If you remove a table variable, all variables contained within that table are removed as well.
space
Simple Lists
space
A simple list is a string that contains semicolon delimited fields. Commands can be entered as simple lists, for example: #showme {a};#showme {b} will execute a single line as two commands.
space
Several commands take a simple list as their input, these are: #foreach, #line substitute, #path load, #list create, and #highlight.
space
Brace Lists
space
A brace list is a string in which fields are delimited with braces. Most commands take a brace list for their arguments, for example: #session {x} {mud.com} {1234} {mud.tin}. The session command takes 4 arguments, the 4th argument (command file) is optional.
space
Commands that take a simple list as their input will also accept a brace list, keep in mind you'll have to embed the brace list in an extra set of braces, for example: #path load {{n}{s}{w}{w}}, which is identical to: #path load {n;s;w;w}.
space
Brace lists cannot be stored as variables because TinTin++ will confuse them with tables. You can convert a brace list to a table variable using: #list {bracelist} {create} {{a}{b}{c}} this will look internally as: {{1}{a}{2}{b}{3}{c}}. You can then convert this table to a simple list using: #list {bracelist} {simplify} {simplelist} which will store {a;b;c} in the $simplelist variable.
space
Braces cannot easily be escaped in TinTin++. Using \{ or \} will not work. The reason for this is due to several factors, but primarily backward compatibility. To escape braces you must define them using hexadecimal notation using \x7B and \x7D. See #help escape for a list of escape options, and the help file will also remind you of how to escape braces.
space
Tables
space
Tables are key/value pairs stored within a variable. There are several ways to create and access tables.
space
Example: #variable {friendlist} {{bob}{bob@hotmail.com} {bubba}{sunset@gmail.com}}
space
This will create a friendlist with two entries, the key is the name of the friend, the value is the email address of the friend. You can see the email address of bob using: #showme {$friendlist[bob]}. You can also define this table as following:
space
Example:
#variable {friendlist[bob]} {bob@hotmail.com}
#variable {friendlist[bubba]} {sunset@gmail.com}
space
This would create the exact same table as the single line declaration used previously. To see the first key in the table use: *friendlist[+1], to see the first value in the table use: $friendlist[+1]. To see the size of the table use &friendlist[]. To print a bracelist of all friends use *friendlist[%*], to print a bracelist of all friends whose name starts with the letter 'a' you would use: *friendlist[a%*]. Similarly to see the number of friends you have whose name ends with the letter 'b' you would use &friendlist[%*b].
space
See #help regexp for a brief overview of regular expression options. While TinTin++ supports PCRE (perl-compatible regular expressions), it embeds them within its own regular expression syntax that is simpler and less invasive, while still allowing the full power of PCRE for those who need it.
space
Example: #unvariable {friendlist[bubba]}
space
This would remove {bubba} from the friendlist. To remove the entire friendlist you would use: #unvariable {friendlist}.
space
Example: #variable {friendlist} {{bob} {{email}{bob@hotmail.com} {phone}{123456789}}}
space
There is no limit to the number of nests, simply add more braces. To see Bob's email in this example you would use: #showme {$friendlist[bob][email]}.
space
Lists
space
Tables are sorted alphabetically with the exception of numbers which are sorted numerically. If you want to determine the sorting order yourself you can use use the #list command which helps you to use tables as arrays.
space
Example: #action {%1 chats %2} {#list chats add {%0}}
space
Each time a chat is received it's added to the end of the 'chats' list variable. Internally this will look something like #variable {chats}={{1}{Bubba chats Hi}{2}{Bob chats Hi bub}{3}{Bubba chats Bye}{4}{Bob chats bub bye}}.
space
The #list command was written before the implementation of tables, as a result the get, set, and size options are redundant.
space
The list command
space
Syntax: #list {<variable>} {<option>} {<arguments>}
space
Lists in TinTin++ are tables (aka associative arrays) with a numeric index. The list command makes it easier to emulate array behavior by automatically renumbering items whenever one is removed or inserted.
space
When the list command requires an index a value between 1 and the list's length should be provided. A negative value can be given as well, in which case -1 equals the last item in the list, -2 the second last, etc.
space
You can directly display items in a list by using the index, for example: $var[1], $var[2], $var[-1], etc.
space
To loop through all items in a list using the foreach command use $<list>[%*].
space
#list {<list>} {add} {<argument1>} {<argument2>} {...}
space
#list add will add an item to the given list for each argument provided.
space
#list {<list>} {clear}
space
#list clear will empty the given list variable. The command is equivalent to: #variable {<variable>} {}
space
#list {<list>} {create} {<argument1>} {<argument2>} {...}
space
#list create will clear the given list and will add an item for each argument provided.
space
#list {<list>} {delete} {<index>} {[number]
space
#list delete will remove the item at the given index. The number argument is the number of items to delete, if omitted 1 item will be deleted.
space
#list {<list>} {find} {<argument>} {<variable>}
space
#list find allows searching for an item that matches the provided argument. If no match is found the destination variable is set to 0, otherwise the variable is set to contain the index of the matched item.
space
#list {<list>} {get} {<indext>} {<variable>}
space
#list get will retrieve the list's item at the provided index. If the index doesn't exist the destination variable is set to 0, otherwise the destination variable is set to contain the value of the found index. Alternatively you can use $list[<index>>] to retrieve the value using the interface for tables.
space
#list {<list>} {insert} {<index>} {<argument>}
space
#list insert will insert the item at the given index. If the index is a positive number the item is created at the given index. If the index is a negative number the item is created at the next index. Hence using -1 will append a new item to the end of the list, and using 1 will prepend a new item to the beginning of the list.
space
#list {<list>} {set} {<index>} {<argument>}
space
#list set will change the value of the provided index to the given argument. Alternatively you can use: #variable {<list>[<index>]} {<argument>} to change the value using the interface for tables.
space
#list {<list>} {simplify} {<variable>}
space
#list simplify will save the table as a simple semi-colon separated list.
space
#list {<list>} {size} {<variable>}
space
#list size will retrieve the number of items in the list and store it in the provided destination variable. Alternatively you can use: &list[] to retrieve the number of items in a list using the interface for tables.
space
#list {<list>} {sort} {<argument>}
space
#list sort will insert the provided argument in alphabetical order.
space
#list {<list>} {tokenize} {<argument>}
space
#list tokenize will turn the given argument into a list of characters. {haha} would become {{1}{h}{2}{a}{3}{h}{4}{a}}. It's useful if you want to perform low level text processing.
space
space
Parsing
space
There are various ways to parse lists and tables, using either #loop, #foreach, #while, or #<number>.
space
#loop takes two numeric arguments, incrementing or decrementing the first number until it matches the second number. The value of the loop counter is stored in the provided variable.
space
#foreach takes either a simple list or a brace list as its first argument. Foreach will go through each item in the list and store the value in the provided variable.
space
#while will perform an if check on the first argument, if the result is true it will execute the commands in the second argument. Then it performs an if check on the first argument again. It will continue to repeat until the if check returns 0 or the loop is interrupted with a control flow command.
space
#<number> will execute the provided argument 'number' times. For example: #4 #showme beep! \a
space
Here are some examples.
space
Example: #list friends create {bob;bubba;zorro}
space
Internally this looks like {{1}{bob}{2}{bubba}{3}{zorro}} and the list can be parsed in various ways.
space
Example: #foreach {$friends[%*]} {name} {#showme $name}
space
Example: #foreach {*friends[%*]} {index} {#showme $friends[$index]}
space
Example: #loop {1} {&friends[]} {index} {#showme $friends[+$index]}
space
Example: #math index 1;#while {&friends[+$index]} {#showme $friends[+$index];#math index $index + 1}
space
Example: #math index 1;#&friends[] {#showme $friends[+$index];#math index $index + 1}
space
Each of the five examples above performs the same task; printing the three names in the friends list.
space
If you want to get a better look at what goes on behind the scenes while executing scripts you can use '#debug all on'. To stop seeing debug information use '#debug all off'.
space