Data Containers

This tutorial will walk you through the 3 main containers available through the bot: Array and Map.

• Array
• Map
• Contains

Array

The array works almost the same as in other languages including 0-indexing. It is capable of being dynamically added to up to 1000 elements to prevent bot abuse.

Creating an array is done as follows:

{{$a := Array 1 2 "hello" false}} // Array with 4 elements
{{$a = Array}} // Empty array

It’s also possible to iterate over them using range.

{{$a := Array "a" "b" "c" "d" "e" "f"}}
{{range $elem := $a}} // stores each element of $a in $elem
    {{respond $elem}}
{{end}}

Since arrays are dynamic, it’s also possible to append one or more values to an existing array. An important thing to keep in mind is that while an array will try to use existing space to append new elements, if it runs out of space it will perform a resize+copy and return a new array, leaving the original array unchanged. For this reason, it’s important to capture the return value of append. Here is an example of some code that appends multiple values to the array and then prints the array and its length.

{{$a := Array}}
{{$a = append $a 1 2 3 "true"}}
{{$a = append $a 4 5 false 6 7}}

// len gets the size of strings, maps, arrays
{{respond (printf "%s %d" $a (len $a))}}

With an existing array, it’s possible to create a slice of the array. When created, a slice is a view into the original array with a modified start and/or end.

{{$a := Array 1 2 3 4 5 6 7 8 9 10}}

// Prints the array starting at index 4
{{respond (slice $a 4)}}

// Prints the array starting at element 4 and ending at element 6 (7 not included)
{{respond (slice $a 4 7)}}

It’s also possible to overwrite existing values in an array with insert. Here is an example:

{{$a := Array 1 2 3 4 5 6 7 8 9 10}}
// overwrites index 1 with "hello"
{{$a = insert $a 1 "hello"}}
// array is now [1 "hello" 3 4 ...]

With the above example, you could verify the change by using the index keyword. It takes a container and a key (index) and returns the value at that key (index).

{{$a := Array 1 2 3 4 5 6 7 8 9 10}}

{{$before := index $a 1}}
{{$a = insert $a 1 "hello"}}
{{$after := index $a 1}}

{{respond (print "before: " $before ", after: " $after)}}

Map

A map is a general-purpose associative container. It allows for key-value pairs to be stored together for fast lookup, insert/overwrite and removal. This is similar to an array since they map integer indices to a value, except with a general map you can use any comparable type (bool, int, float, string, pointer, etc.). Like arrays, they are limited to 1000 elements to prevent bot abuse.

Creating a map is done as follows:

{{$sm := Map "hello" 1 "world" 2 "!" 3}}

Iterating over the map/smap can be done with range, only this time it returns both the key and value.

{{$sm := Map "hello" 1 "world" 2 "!" 3}}
{{$msg := ""}}
{{range $k, $v := $sm}}
    {{$msg = printf "%s: %d\n" $k $v}}
{{end}}
{{respond $msg}}

Adding and removing elements can be done with insert and remove.

{{$sm := Map "hello" 1 "world" 2 "!" 3}}
{{$sm = insert $sm "earth" true}}
{{respond $sm}}

{{$sm = remove $sm "hello"}}
{{respond $sm}}

Notice that the result of insert and remove is used to overwrite the value of variable $sm. Most of the time the existing map will be used and modified, but there is one notable case where the bot will create a new map and return it instead. This is if you try to modify one of the builtin bot runtime maps that are given to your code as an input. Those are immutable, so the bot first needs to make a full copy of the map so you can modify it.

For keys that are strings and only use alphanumeric characters (where the first character is alphabetical), you have access to special . syntax for lookup as follows:

{{$sm := Map "hello" 1 "world" 2 "earth" true 1024 "ten twenty four"}}
{{respond $sm.hello}}  // shows 1
{{respond $sm.earth}}  // shows true
{{respond $sm.planet}} // shows empty (nil) since planet is not a string key in the map

{{respond (index $sm "hello")}}  // Same as $sm.hello
{{respond (index $sm "earth")}}  // same as $sm.earth
{{respond (index $sm "planet")}} // same as $sm.planet
{{respond (index $sm 1024)}} // not possible to do $sm.1024, but index works fine with it

It should be noted that index is more versatile in this case since it can be used with all key types, where as . syntax only works with certain very specific key situations.

Contains

Arrays, maps and strings can all be searched using the contains function. In the case of strings it works as a substring search.

{{$sm := Map "hello" 1 "world" 2 "!" 3}}
{{respond (contains $sm "world")}} // true
{{respond (contains $sm "earth")}} // false

{{$a := Array 1 2 3 4 5}}
{{respond (contains $a 1)}} // true
{{respond (contains $a 7)}} // false

{{respond (contains "hello world" "world")}} // true
{{respond (contains "hello world" "earth")}} // false

Next <- Tutorial 4: Triggers