On this page:

In the operation / expression block, you can specify an arbitrary number of operations for the bot to calculate. These operations are expressions written using a subset of the conversational bot programming language that is described below.

Structure of operations

All bot operations contained in one block represent one or multiple expressions in the bot programming language. Expressions are separated from each other by an optional character ";" or a newline character.

Every expression has a value. This means that expressions can be complex.

Comments

When you are writing expressions, you can use comments. Comments are sections of the program that do not participate in calculations but are meant for informational purposes only.

There are two types of comments:

• Single-line comments. Such comments begin with two slashes // and end at the end of the line.
• Multiline comments. Multiline comments start with /* and end with */.

// These are single-line comments
$x = time()

/**
 * And these are
 * multiline
 * comments
 */
say("Time is " + $x)

Variables

Variables are used to store data in bot scripts. A variable represents a named location in the bot's memory. It is created the first time it is used in a block of operations. Nil is the default value of all variables.

There are three types of variables. They are distinguished by the scope:

• Variables that are visible within the same module in one thread.
  These variables can be used for reading and writing values. Their names begin with the symbol $. Such variables are useful for storing values of intermediate operations and calculations.
• Variables that are visible within the same module in different threads.
  These variables can be used for reading and writing values. Their names begin with the symbol #. Since such variables are visible in all threads of the bot, they are useful for interaction between threads.
• Global variables or environment variables.
  These variables are defined automatically. They are visible in all threads of all bot modules. These variables are read-only and store information about the global context of the bot. Their names start with the symbol @.

// Variables $p and $r are only available in the thread where they are defined
$p = 2 * 3.14 * $r

// This variable is available in all threads within the current module
// (the module where the block of operations is located where the variable is defined).
#count = queue.size()

// @communicationType is a read-only global variable. It is available from everywhere. 
$isChat = @communicationType == "TEXT"

Variable names can contain only numbers, English and Russian letters, and underscores. I.e., you cannot name a variable with a word that contains a space or character other than in Russian or English. However, there is a way to specify any name you want. For this, enclose the variable name in parentheses:

$('日本') = 123         // Creates a variable with name 日本
$x = $('日本')          //  $x is now 123
$(math.rand(1, 2)) = 0 // Dynamically creates a variable with name 1 or 2 and assigns it value 0

Variable variables

The bot expression language allows you to dynamically calculate the name of a variable while the bot is running. This means that the name of one variable can be the value of another variable. Or a variable name can be any expression whose value is a string.

In the example below, we define three variables that contain color names. Then on the random basis we determine a number in the range from 1 to 3 and then create a name for one of these variables to find out the value of a random color.

// Create three variables with names x1, x2 and x3
$x1 = "red"
$x2 = "blue"
$x3 = "green"

// Random number in the range from 1 to 3 $n = math.rand(1, 3)

// Get the color dynamically generating the name for a variable with the color and using its value
$color = $("x" + $n)

You can also use variable values ​​of different types:

// $x contains the name of variable #y
$x = "y"

// #y contains the name of the global variable communicationType
#y = "communicationType"

// Calculated in the following way @#$x -> @#("y") -> @#y -> @("communicationType") -> @communicationType
$communicationType = @#$x

Data types

There are three primitive data types. One of them is the object type and another one is the special value nil.

Numbers

All numbers are treated as real signed numbers with a floating point. The minimum and maximum values ​​are determined by the computing environment where the interpreter of the expression language is functioning.

Strings

Strings represent an arbitrary sequence of characters enclosed in single or double quotes. Double quotes differ from single quotes so that the following special character sequences are recognized within them:

In single quotes all characters are treated as is except for the sequence \'  that means a single quote character.

// The following command displays a two-line phrase in the chat 
// Hello
// "Medved!"
say("Hello\n\"Medved!\"")

// Will display a phrase in the chat Hello\n'Medved!'
say('Hello\n\'Medved!\'')

Boolean (logical) values

Constants true and false are boolean, i.e. their values can have only one of the following states: true and false.

Boolean values ​​are useful in an expression of the conditional block.

$x = true  // $x contains TRUE
$y = !$x   // $y contains FALSE

Objects

In the standard library of the bot programming language there are functions (operations) whose values are so-called objects. An object is a special value that can have built-in properties and operations or methods. The combination of these properties and methods is determined by the type of the object. To access object properties or methods, the dot operator "." is used.

For example, below we receive the first message from the client that is a ClientMessage object. Then we use the message property (message text) of that object:

// $first contains the value of the ClientMessage object
$first = queue.first()

// Receive the value of the message property 
$firstMessage = $first.message

Object properties and methods as well as variable values can be calculated:

$n = rand(0, 1)                     // $n contains either 0 or 1
$method = ["first", "last"].get($n) // $method contains the string first or last (see getting a list element by index) 
$firstOrLast = queue.$method        // Receive the first or last client message
// Or even like this
$firstOrLast = queue.(["first", "last"].get($n))

There are three types of built-in objects that are collections of arbitrary elements.

Tuples

A tuple is an unchangeable ordered collection of arbitrary elements. You can create a tuple with parentheses:

$items = (1, 2, 2) // Tuple with one element
$items = ('a',)    // Tuple with one element. The comma is used to distinguish the creation of a tuple from parentheses. 
$items = ()        // Tuple without elements (empty tuple)

The following methods are used to work with tuples:

count()

(1, 2, 3).count()

first()

(1, 2, 3).first()

last()

(1, 2, 3).last()

has(index)

(1, 2, 3).has(0)
(1, 2, 3).has(3)

get(index)

(1, 2, 3).get(1)
(1, 2, 3).get(3)

(1, 2, 3).contains(3)
(1, 2, 3).contains(0)

(1, 2, 3).index(3)
(1, 2, 3).index(0)

equals(other)

('a', 'b').equals(('a', 'b'))
('a', 'b').equals(('b', 'a'))

hash()

('a', true).hash()

Lists

A list is a changeable ordered collection of arbitrary elements. You can create a list with square brackets:

$items = [1, 2, 2] // List with three elements
$items = ['a']     // List with one element
$items = []        // List without elements (empty list)

The following methods are used to work with lists:

count()

[1, 2, 3].count()

first()

[1, 2, 3].first()

last()

[1, 2, 3].last()

has(index)

[1, 2, 3].has(0)
[1, 2, 3].has(3)

get(index)

[1, 2, 3].get(1)
[1, 2, 3].get(3)

[1, 2, 3].contains(1)
[1, 2, 3].contains(0)

[1, 2, 3].index(1)
[1, 2, 3].index(0)

toTuple()

[1, 2, 3].toTuple()

clear()

$x = [1, 2, 3]
$x.clear()

reverse()

[1, 2, 3].reverse()

append(item)

[1, 2, 3].append(4)

prepend(item)

[1, 2, 3].prepend(0)

shift()

$x = [1, 2, 3]
$y = $x.shift()

pop()

$x = [1, 2, 3]
$y = $x.pop()

set(index, item)

$x = [1, 2, 3]
$y = $x.set(1, 0)
$z = $x.set(5, 'a')

remove(index)

$x = [1, 2, 3]
$y = $x.remove(1)

equals(other)

['a', 'b'].equals(['a', 'b'])
['a', 'b'].equals(['b', 'a'])

hash()

['a', true].hash()

Associative arrays (dictionaries)

An associative array or dictionary (map) is a mutable ordered collection of arbitrary key/value pairs. A dictionary is created with curly braces:

$items = {'a': 1, 'b': 2, 'c': 3} // Dictionary of three elements
$items = {1: true}                // Dictionary of one element
$items = {}                       // Dictionary without any elements (empty dictionary)

The following methods are used to work with dictionaries:

count()

{1: 'a', 2: 'b', 3: 'c'}.count()

clear()

$x = {true: false, 'b': true}
$x.clear()

reverse()

{'a': 1, 'b': 2, 'c': 3}.reverse()

values()

{'a': 1, 'b': 2, 'c': 3}.values()

keys()

{'a': 1, 'b': 2, 'c': 3}.keys()

firstKey()

{'a': 1, 'b': 2, 'c': 3}.firstKey()

lastKey()

{'a': 1, 'b': 2, 'c': 3}.lastKey()

first()

{'a': 1, 'b': 2, 'c': 3}.first()

last()

{'a': 1, 'b': 2, 'c': 3}.last()

contains(item)

{'a': 1, 'b': 2, 'c': 3}.contains(2)
{'a': 1, 'b': 2, 'c': 3}.contains(4)

has(key)

{'a': 1, 'b': 2, 'c': 3}.has('a')
{'a': 1, 'b': 2, 'c': 3}.has('d')

get(key)

{'a': 1, 'b': 2, 'c': 3}.get('b')
{'a': 1, 'b': 2, 'c': 3}.get('d')

$x = {1: true, 2: nil}
$x.set(2, false)

equals(other)

{'a': 'b'}.equals(['a': 'b'])
{'a': 'b'}.equals(['b': 'a'])

hash()

{'a': true}.hash()

Special value nil

When a variable is not defined but is already used in an expression, its value becomes nil. This is a special value that means the absence of any value. This value can also be assigned explicitly.

$x = 1 + 2 // $x contains 3
$x = nil   // $x contains nil

Operations

The bot expression language has several operation classes. An operation class is determined by its first argument. For example, if the first argument of the "+" operation is a string, then strings are concatenated. If the first argument is a number, then numbers are added.

Priorities of operations

The higher the priority is defined, the earlier the operation is performed. Parentheses are used to increase the priority.

Arithmetic operations

Arithmetic operations are used to work with numbers. If the value used in the arithmetic operation is not a number, the system will attempt to convert it to a number (see below).

+$a

-$a

$a + $b

$a - $b

$a * $b

$a / $b

$a \ $b

$a % $b

$a ** $b

Bitwise operations

This is a separate class of operations used to work with bit representations of integers.

~$a

$a & $b

$a | $b

$a ^ $b

Table for conversion of other data types to a number:

Logical operations

Logical operations are used to work with boolean values. If the value is not boolean, then there will be an attempt to convert it to a boolean value (see below).

!$a

$a && $b

$a || $b

Table for conversion of other data types to a boolean value:

Operations with strings

Only one operation is used to work with strings. This operation is called the addition or concatenation of strings.

"a" + "b"

If the first argument of the concatenation operation is not a string, then the addition is performed. If the second argument is not a string, then it is converted to a string according to the following conversion table:

Comparison operations

Comparison operations are used to work with any data types. Calculation results are boolean values.

$a == $b

$a != $b

$a > $b

$a >= $b

$a < $b

$a <= $b

Operations with collections

There is a union operation that is used for embedded object types: tuple, list, and map.

(1, 2) + (3, 4)

['a', 'b'] + ['c']

{'a': 0, 'b': 2} + {'a': 1, 'c': 3}

Assignment operations

Assignment operators allow to assign a value to variable.

$a = 123

$a += 1

$a -= 1

$a *= 2

$a /= 2

$a \= 2

$a %= 5

$a **= 3

$a &= 1

$a |= 3

$a ^= 4

Apart from assigning a value to a variable, you can also assign a value to several variables at once.

($x, $y, $z) = (1, 2, 3)

$x = 1
$y = 2
$z = 3

(1, 2, 3)

[$x, $y] = ($y, $x)

$x = $y
$y = $x

[$y, $x]

{'a': $x, 'b': $y} = {'b': true, 'a': false}

$x = false
$y = true

{'a': false, 'b': true}

($x, $y, $z) += [1, 2, 3]

$x = $x + 1
$y = $y + 2
$z = $z + 3

($x + 1, $y + 1, $z + 1)

{3: $x, 7: $y} *= (2, 3)

$x = $x * 2
$y = $y * 3

{3: $x * 2, 7: $y * 3}

Functions

Function calls are basic blocks that are used to build expressions in an operation block. A function is a part of a bot's functionality. For example, using functions you can work with date and time, perform complex arithmetic operations, convert a text string to intents using the NLU service, work with the client's message queue, etc.

To call a function, you need to specify its name, then list its parameters separated by a comma in parentheses. Names of most functions contain two parts separated by a dot: the name of the module and the name of the function itself.

$number = math.rand(5, 10) // Returns a random number in the range from 5 to 10. math – module name, rand – function name

Like object methods function names can be dynamically calculated during the execution of the bot script.

$funcIdx = math.rand(0, 1)                          // Returns a random number in the range from 0 to 1 that will be the index of the function name in the tuple 
$number = math.(('min', 'max').get($funcIdx))(3, 7) // Returns the name of the min or max function and then calls it. This way we calculate either the minimum or maximum value on the random basis