On this page:

General functions

del(varName string)

Purpose: deletion of a local or module variable.

Arguments:

1. varName is the name of the variable as a string. The name can start with a variable scope prefix. If the prefix is ​​omitted, then the variable is regarded to be local.

Returned value: none.

$localVar = 123
#moduleVar = true
del("$localVar")   // Deletes the local variable $localVar
del("localVar")    // Result is the same as for del("$localVar")
del("#moduleVar")  //  Deletes a variable visiable within a module

Math functions

math.pos(num mixed) number

Purpose: converts the argument to a number. The function acts as quivalent to the unary "+" operator.

Arguments:

1. num – arbitrary value that will be converted to a number.

Returned value: number.

$a = math.pos(true)  // $a will be equal toо 1
$a = math.pos(false) // $a will be equal to 0
$a = math.pos(nil)   // $a will be equal to 0
$a = +true           // $a will be equal to 1, same as math.pos(true)

math.neg(num number) number

Purpose: changes the sign of a number. The function acts as quivalent to the unary operation "-".

Arguments:

1. num – an arbitrary number whose sign changes to the opposite.

Returned value: the same number with the opposite sign.

$a = math.neg(-1) // $a will be equal to 1
$a = math.neg(1)  // $a will be equal to -1
$a = math.neg(0)  // $a will be equal to 0
$a = -(-10)       // $a will be equal to 10, same as math.neg(-10)

math.inv(num number) number

Purpose: bit number inversion. This function is equivalent to the unary operator "~".

Arguments:

1. num – an arbitrary number with invertable bits.

Returned value: inverted number.

$a = math.inv(5) // $a is equal to 3
$a = ~5          // same as previous line

math.not(num number) bool

Purpose: logical negation of a number. This function is equivalent to the unary operation "!".

Arguments:

1. num – an arbitrary number.

Returned value: true if num is not equal to 0; otherwise false.

$a = math.not(5) // $a is equal to false
$a = math.not(0) // $a is equal to true
$a = !0          // same as previous line

math.add(num1 number, num2 number, precision int = 12) number

Purpose: addition of numbers.  This function is equivalent to the binary operation "+".

Arguments:

1. num1 – the first part
2. num2 – the second part.
3. precision – the accuracy of calculation, the number of digits after the decimal point. The default value is 12. The maximum value is 100.

Returned value: sum of numbers.

$a = math.add(1.5, 3.5)         // $a is equal to 5
$a = 1.5 + 3.5                  // same as previous line
$a = math.add(1.000006, 2.1, 5) // $a is equal to 3.10001

math.sub(num1 number, num2 number, precision int = 12) number

Purpose: difference of numbers. This function is equivalent to the binary operation "-".

Arguments:

1. num1 – minuend.
2. num2 – subtrahend.
3. precision – calculation accuracy, the number of digits after the decimal point. The default value is 12, the maximum is 100.

Returned value: difference of numbers.

$a = math.sub(1.5, 3.5)         // $a is equal to -2
$a = 1.5 - 3.5                  // same as previous line
$a = math.sub(2.100006, 1.1, 5) // $a is equal to 1.00001

math.mul(num1 number, num2 number, precision int = 12) number

Purpose: multiplication. This function is equivalent to the binary operation "*".

Arguments:

1. num1 – first multiplier.
2. num2 – second multiplier.
3. precision – calculation accuracy, the number of digits after the decimal point. The default value is 12, the maximum is 100.

Returned value: multiplication.

$a = math.mul(1.5, 3.5)         // $a is equal to 5.25
$a = 1.5 * 3.5                  // same as previous line
$a = math.mul(1.2345, 1.234, 5) // $a is equal to 1.52337

math.div(num1 number, num2 number, precision int = 12) number

Purpose: quotient of numbers. Equivalent to the binary operation "/".

Arguments:

1. num1 – dividend.
2. num2 – divider.
3. precision – calculation accuracy, the number of digits after the decimal point. The default value is 12, the maximum is 100.

Returned value: quotient of numbers.

$a = math.div(1.5, 3.5) // $a is equal to 0.428571428571
$a = 1.5 / 3.5          // same as previous line
$a = math.div(1, 3, 5)  // $a is equal to 0.33333

math.idiv(num1 number, num2 number) int

Purpose: integer division of numbers. This function is equivalent to the binary operation "\".

Arguments:

1. num1 – dividend.
2. num2 – divider.

Returned value: integer part of private numbers.

$a = math.idiv(2.5, 0.3) // $a is equal to 8
$a = 2.5 \ 0.3           // same as previous line

math.mod(num1 number, num2 number, precision int = 12) number

Purpose: remainder after dividing two numbers. This function is equivalent to the binary operation "%".

Arguments:

1. num1 – dividend.
2. num2 – divider.
3. precision – calculation accuracy, the number of digits after the decimal point. The default value is 12, the maximum is 100.

Returned value: remainder of the division.

$a = math.mod(3.5, 1.5)    // $a is equal to 0.5
$a = 3.5 % 1.5             // same as previous line
$a = math.mod(1/3, 2/7, 5) // $a is equal to 0.04762

math.pow(base number, power number, precision int = 12) number

Purpose: raising the number base to the power power. This function is equivalent to the binary operation "**".

Arguments:

1. base – base.
2. power – degree.
3. precision – calculation accuracy, the number of digits after the decimal point. The default value is 12, the maximum is 100.

Returned value: result of exponentiation.

$a = math.pow(1.5, 3.5)    // $a is equal to 4.133513940947
$a = 1.5 ** 3.5            // same as previous line
$a = math.pow(1.3, 7.1, 5) // $a is equal to 0.44166

math.sqrt(num number, precision int = 12) number

Purpose: extracting the square root.

Arguments:

1. num – the number from which the root is taken.
2. precision – calculation accuracy, the number of digits after the decimal point. The default value is 12, the maximum is 100.

Returned value: square root or error if the number is negative.

$a = math.sqrt(3.14)   // $a is equal to 1.772004514667
$a = math.sqrt(1.7, 5) // $a is equal to 0.30384

math.round(num number, precision int) number

Purpose: rounding the number to the required decimal place.

Arguments:

1. num – number to round.
2. precision – calculation accuracy, the number of digits after the decimal point. The maximum is 100.

Returned value: number rounded with a given precision.

$a = math.round(3.14159265358979323846264338327950288419716, 17) // $a is equal to 3.14159265358979324
$a = math.round(3.14159265358979323846264338327950288419716, 2)  // $a is equal to 3.14
$a = math.round(3.14159265358979323846264338327950288419716, 0)  // $a is equal to 3

Functions for working with strings

str.len(str string) int

Purpose: determining the length of the string in characters.

Arguments:

1. str – string whose length is to be determined.

Returned value: integer is equal to the number of characters in the string.

$str = "Some string"
$len = str.len($str) // $len will contain 15

str.lower(str string) string

Purpose: convertion of string characters to lower case.

Arguments:

1. str – string to be converted.

Returned value: a string with all characters in lowercase.

$str = "StRiNg"
$lower = str.lower($str) // $lower will contain "string" 

str.upper(str string) string

Purpose: convertion of string characters to uppercase.

Arguments:

1. str – string to be converted.

Returned value: a string with all characters in uppercase.

$str = "StRiNg"
$upper = str.upper($str) // $lower will contain "STRING" 

str.ucfirst(str string) string

Purpose: convertion of the first character of the string to uppercase.

Arguments:

1. str – string whose first character is to be converted.

Returned value: string with the first character written in upper case.

$str = str.ucfirst("строка") // $str будет содержать "Строка" 

str.lcfirst(str string) string

Purpose: convertion of the first character of the string to lowercase.

Arguments:

1. str – string whose first character is to be converted.

Returned value: string with the first character written in lower case.

$str = str.ucfirst("String") // $str will contain "string" 

str.letter(str string, index int) string

Purpose: retrieve the specified character of the string.

Arguments:

1. str – string whose character is to be retrieved.
2. index – an integer that defines the character position in the string starting from 0. If this number is negative, then the count starts from the end of the string.

Returned value: the string that corresponds to the specified character or the empty string if there is no character at that position.

$str = "Word"
$firstLetter = str.letter($str, 0)  // First character
$lastLetter = str.letter($str, -1)  // Last character

str.first(str string, index int = 0) string

Purpose: retrieve the specified character of a string starting from the beginning of the string.

Arguments:

1. str – string whose character is to be retrieved.
2. index – an integer that defines the position of the character from the beginning of the string starting from 0. In this case, the sign of the number is ignored. The default value is 0 (first character).

   
   

Returned value: string that corresponds to the specified character or the empty string if there is no character at that position.

$str = "Word"
$firstLetter = str.first($str)      // First character
 $secondLetter = str.first($str, 1)  // Last character

str.last(str string, index int = 0) string

Purpose: retrieve the specified character of the string starting from the end of the string.

Arguments:

1. str – string whose character is to be retrieved.
2. index – an integer that defines the position of the character from the end of the string starting from 0. In this case, the sign of the number is ignored. The default value is 0 (last character).

Returned value: строка соответствующая указанному символу, либо пустая строка если символа с такой позицией не существует.

$str = "Слово"
$lastLetter = str.last($str)       // Последняя буква
$penultLetter = str.last($str, 1)  // Предпоследняя буква

str.concat(str1 string, str2 string) string

Purpose: concatenates two strings into one.

Arguments:

1. str1 – string to be concatenated.
2. str2 – string to be concatenated with.

Returned value: a new line that cosists of the first line to the right of which the second line is added.

$str1 = "one"
$str2 = "two"
$str = str.concat($str1, $str2) // $str will contain "onetwo" 

str.sub(str string, offset int, length int = nil) string

Purpose: returns a substring of str starting from the offset character by count and length of character length.

Arguments:

1. str – original string.
2. offset – if offset is not negative, the returned substring starts at the offset position from the beginning of the string, starting from zero.
   If offset is negative, the returned substring starts at offset characters from the end of str string.
   If str is less than offset characters, an empty string will be returned.
3. length – if length is positive, the returned string will be no longer than length characters starting at the offset parameter (depending on the length of string).
   If length is negative, then the number of characters specified by this argument will be discarded from the end of string (after the starting position has been calculated, if offset is negative). If the position of the beginning of the substring specified by the offset argument is in or after the discarded part of the string, then the empty string is returned.
   If the length parameter is defined and equals to 0, an empty string will be returned.
   If the length parameter is omitted or nil, then a substring will be returned starting at the position specified by the offset parameter up to the end of the string.

Returned value: part of str or the empty string.

$sub = str.sub("abcdef", 1)      // $sub равен bcdef
$sub = str.sub("abcdef", 1, 3)   // $sub равен bcd
$sub = str.sub("abcdef", 0, 4)   // $sub равен abcd
$sub = str.sub("abcdef", 0, 8)   // $sub равен abcdef
$sub = str.sub("abcdef", -1, 1)  // $sub равен f
$sub = str.sub("abcdef", -1)     // $sub равен f
$sub = str.sub("abcdef", -2)     // $sub равен ef
$sub = str.sub("abcdef", -3, 1)  // $sub равен d
$sub = str.sub("abcdef", 0, -1)  // $sub равен abcde
$sub = str.sub("abcdef", 2, -1)  // $sub равен cde
$sub = str.sub("abcdef", 4, -4)  // $sub равен пустой строке
$sub = str.sub("abcdef", -3, -1) // $sub равен de

str.join(arr Collection, separator string = "") string

Purpose: concatenates the elements of a collection (tuple, list, or associative array) into a string.

Arguments:

1. arr – collection of items to  concatenate.
2. separator – collection separator. The default is an empty string.

Returned value:  a new string that contains all the elements of the collection separated by a delimiter.

$str = str.join([1, 2, 3, 4, 5], "-")             // $str will contain "1-2-3-4-5"
$str = str.join(("a", "b", "c"))                  // $str will contain "abc"
$str = str.join({"a": "один", "b": "два"}, " + ") // $str will contain "one + two"
$str = str.join(["одно"], "/")                    // $str will contain "one"
$str = str.join([], "/")                          // $str will contain ""

str.split(str string, separator string = "", limit int = 0) List

Purpose: splits the string into parts using separator as the delimiter.

Arguments:

1. str – string to split.
2. separator – separator. If it is equal to an empty string, then splitting is carried out character by character.
3. limit – an optional parameter equal to the maximum number of parts the string is splitted to. If limit is 0, then there is no limit. If the limit is positive, then the returned list will contain a maximum of limit elements, with the last element containing the remainder of str. If the limit is negative, then all components will be returned except for the last one – limit.

Returned value:  list of substrings into which the string is split.

$letters = str.split("abcdef")             // returnes a list of letters in a word
$words = str.split("one two three", " ")    // returnes a list of words
$words = str.split("one two three", " ", 1) // words contains ["one", "two three"]

str.replace(str string, search string, replace string) string

Purpose: searches for all occurrences of a substring in a string and replaces them with the given value.

Arguments:

1. str – string to be converted.
2. search – substring that is searched for in the source string. 
3. replace – replacement string.

Returned value:  a new line where all all cccurences of "search" are replaced with "replace".

$str = str.replace("mother washed frame", "frame", "Dasha") // $str содержит "mother washed Dasha"

str.match(str string, pattern string) bool

Purpose: performs a regular expression check on the given string.

Arguments:

1. str – string to match against the regular expression.
2. pattern – pattern of regular expression.

Returned value: returns true if the string matches the regular expression, otherwise returns false.

Note: Perl Compatible Regular Expressions (PCRE) are used as regular expressions.  Link to documentation and examples of regular expressions.

Online regular expression editor.

$isIntNumber = str.match("1.234", "/^[0-9]+$/") // $isIntNumber will be equal to false
$isIntNumber = str.match("1234", "/^[0-9]+$/")  // $isIntNumber will be equal to true

str.distance(str1 string, str2 string) number

Purpose: calculates the similarity of two strings.

Arguments:

1. str1 – first line to compare.
2. str2 – second line to compare. 

Returned value:  returns a number between 0 and 1 that indicates the similarity of two strings. 1 - strings are equivalent, 0 - strings are completely different.

Note: This function actually calculates the Damerau-Levenshtein distance.

$d = str.distance("", "abc")              // $d is equal to 0
$d = str.distance("Да", "да")             // $d is equal to 1
$d = str.distance("корыто", "открыто")    // $d is equal to 0.714
$d = str.distance("Да, верно", "таверна") // $d is equal to 0.625
$d = str.distance("terribly oblique bananas", "chew coconuts, eat bananas") // $d is equal to 0.714 
$d = str.distance("went crazy from the wound, "He became a pusurmany")  // $d is equal to 0.45
$d = str.distance("hedgehog", "deoxyribonucleic acid")         // $d is equal to 0.033

Hash functions

hash.of(text string, algo string = "md5", binary bool = false) string

Purpose: calculates the hash of the string according to the specified algorithm.

Arguments:

1. text – arbitrary string to hash.
2. algo – the name of the hash algorithm. The default algorithm is md5.
3. binary – when it is set to true, then it returns output raw binary data. If it is set to false, it outputs the data in lowercase hexadecimal encoding. By default it is set to false.

Returned value: returns a string that contains the computed hash code in lowercase hexadecimal encoding. If binary is set to true, then the hash code is returned as binary data. It returns an empty string in case of error (for example, if an invalid hash algorithm is specified).

Possible hash algorithms values:

• md2
• md4
• md5
• sha1
• sha224
• sha256
• sha384
• sha512/224
• sha512/256
• sha512
• sha3-224
• sha3-256
• sha3-384
• sha3-512
• ripemd128
• ripemd160
• ripemd256
• ripemd320
• whirlpool
• tiger128,3
• tiger160,3
• tiger192,3
• tiger128,4
• tiger160,4
• tiger192,4
• snefru
• snefru256
• gost
• gost-crypto
• adler32
• crc32
• crc32b
• crc32c
• fnv132
• fnv1a32
• fnv164
• fnv1a64
• joaat
• murmur3a
• murmur3c
• murmur3f
• xxh32
• xxh64
• xxh3
• xxh128
• haval128,3
• haval160,3
• haval192,3
• haval224,3
• haval256,3
• haval128,4
• haval160,4
• haval192,4
• haval224,4
• haval256,4
• haval128,5
• haval160,5
• haval192,5
• haval224,5
• haval256,5

Note: if the third parameter is true, then you cannot pass the value returned by the function as a bot message or part of it. This will crash the bot.

$hash = hash.of("Impudent brown fox cub jumps around a lazy dog.")                 // $hash will contain bff8b4bc8b5c1c1d5b3211dfb21d1e76
$hash = hash.of("Impudent brown fox cub jumps around a lazy dog.", "ripemd160")    // $hash will contain 8817ca339f7f902ad3fb456150a1bb9b4cb5dde9
$hash = hash.of("Impudent brown fox cub jumps around a lazy dog.", "sha256", true) // $hash will contain a binary string (with displayable characters)

Encoding/decoding functions

codec.base64Encode(str string) string

Purpose: encodes the given string into Base64.

Arguments:

1. str – arbitrary string to encode.

Returned value: returns a string encoded in Base64.

$encoded = codec.base64Encode("Привет!") // $encoded will contain string "0J/RgNC40LLQtdGCIQ=="

codec.base64Decode(str string) ?string

Purpose: decodes the provided Base64 string.

Arguments:

1. str – Base64 encoded string.

Returned value: returns the decoded string or nil if the encoded string contains characters that are not in the base64 character alphabet of the encoding.

$decoded = codec.base64Decode("0J/RgNC40LLQtdGCIQ==") // $decoded will contain string "Hello!"
$failed = codec.base64Decode("Привет!")               // $failed will be equal to nil

Date and Time Functions

dt.add(d1 int|string, d2 int|string) string

Purpose: adds two dates, provided as a string or as a number of seconds.

• If at least one of the function arguments is the number of seconds, then this number will be added to the number of seconds of another date.
• If both dates are strings, then the result is d1 + abs(secondsOf(d1) - secondsOf(d2)), where abs is the absolute value of the number (a positive value), secondsOf is the date represented as the number of seconds since the beginning of 1970 (dates prior to that time are represented by a negative value).

Arguments:

1. d1 – a string that represents a date in one of the allowed formats or an integer that corresponds to the number of seconds.
2. d2 – similar to the first argument.

Returned value: returns the new date and time as a string.

$d = dt.add("2022-01-01 12:30:00", 59)                    // $d contains string "2022-01-01 12:30:59" 
$d = dt.add(3600, "2022-01-01 12:30:00")                  // $d contains string "2022-01-01 13:30:00"
$d = dt.add("2022-01-01 00:00:00", "2022-01-02 00:00:00") // $d contains string "2022-01-03 00:00:00"

dt.sub(d1 int|string, d2 int|string) int|string

Purpose: calculates the difference between two dates provided as strings or seconds.

• If both dates are provided in number of seconds, then the function will return their difference as a number of seconds.
• If both dates are provided as a string, then an integer equal to the difference between the dates in seconds will be returned.
• If the first argument is a date string and the second argument is a number of seconds, then the result is a new date equal to the difference between the date and the number of seconds.
• If the second argument is a date string and the first argument is a number of seconds, then the result is an error.

Arguments:

1. d1 – a string that represents a date in one of the allowed formats or an integer that corresponds to the number of seconds.
2. d2 – similar to the first argument.

Returned value: returns a new date and time as a string, or the number of seconds – the difference between the dates.

$d = dt.sub(100, 50)                                      // $d contains 50
$d = dt.sub("2022-01-01 12:30:00", 3600)                  // $d  contains string "2022-01-01 11:30:00"
$d = dt.sub(3600, "2022-01-01 12:30:00")                  // Thisa call is invalid and will cause the program to terminate.
$d = dt.sub("2022-01-01 01:00:00", "2022-01-01 00:00:00") // $d contains 3600

dt.format(dt int|string, format string) string

Purpose: brings the date to the specified format.

Arguments:

• dt – date provided as a string or number of seconds.
• format – string that specifies the date and time format.

Returned value: date string in the provided format.

Possible formatting parameters:

Note: if the format string contains characters that match the above, but are not formatting options, then they should be escaped with the backslash character "\".

$dt = dt.format('2022-12-20 08:34:05', 'y.MM.dd h-mm-ss')    // $dt будет содержать строку "22.12.20 8-34-05"
$dt = dt.format('16:30:47', '\Hour\s an\d \minute\s: HH/mm') // $dt будет содержать строку "Hours and minutes: 16/30"

date.nearFuture(day int) string

Purpose: returns the nearest future date to the current date for the specified day.

Arguments:

1. day – number of days to determine the next date in the future.

Returned value: returns the closest date to day.

// Допустим сейчас 2022-12-20
$d = date.nearFuture(25) // $d contains 2022-12-25
$d = date.nearFuture(10) // $d contains 2023-01-10

date.nearPast(day int) string

Purpose: returns the nearest past date to the current date for the given day.

Аргументы:

1. day – number of days to determine the closest date in the past.

Returned value: returns the closest date to day.

// Допустим сейчас 2022-12-20
$d = date.nearPast(25) // $d contains 2022-11-25
$d = date.nearPast(10) // $d contains 2023-12-10

date.future(day int) string

Purpose: returns the date that corresponds to the specified day in the next month.

Arguments:

1. day – number of days to determine a date in the future.

Returned value: date in the future.

// Допустим сейчас 2022-12-20
$d = date.future(25) // $d contains 2023-01-25
$d = date.future(10) // $d contains 2023-01-10

date.past(day int) string

Purpose: returns the date that corresponds to the specified day in the previous month.

Аргументы:

1. day – number of days to determine a date in the past.

Returned value: date in the past.

// Допустим сейчас 2022-12-20
$d = date.past(25) // $d содержит 2022-11-25
$d = date.past(10) // $d содержит 2022-11-10

time.nearFuture(minute int) string

Purpose: returns the nearest future to the current time by the provided number of minutes.

Arguments:

1. minute – number of minutes to determine the nearest future time.

Returned value: returns the time closest to minute.

// Допустим сейчас 23:30:00
$t = time.nearFuture(45) // $t содержит 23:45:00
$t = time.nearFuture(15) // $t содержит 00:15:00

time.nearPast(minute int) string

Purpose: returns the nearest past to the current time for the specofoed number of minutes.

Arguments:

1. minute – number of minutes to determine the nearest past time.

Returned value: returns the time closest to minute.

// Let's say now it is 23:30:00
$t = time.nearPast(45) // $t contains 22:45:00
$t = time.nearPast(15) // $t contains 23:15:00

time.future(minute int) string

Purpose: returns time that corresponds to the specified number of minutes in the next hour.

Arguments:

1. minute – number of minutes to determine the time in the future.

Returned value: time in the future.

// Let's say now it is 23:30:00
$t = time.future(45) // $t contains 00:45:00
$t = time.future(15) // $t contains 00:15:00

time.past(minute int) string

Purpose: returns the time that corresponds to the specified number of minutes in the past hour.

Arguments:

1. minute – number of minutes to determine the time in the past.

Returned value: time in the past.

// Допустим сейчас 23:30:00
$t = time.past(45) // $t contains 22:45:00
$t = time.past(15) // $t contains 22:15:00

Functions for user message queue

queue.size() int

Purpose: determines the size of the user message queue.

Arguments: not present.

Returned value: number of user messages.

$messageCount = queue.size() // $messageCount contains the number of user messages for the entire dialog

queue.last() ?UserMessage

Purpose: returns the last user message or nil if the message queue is empty.

Arguments: not present.

Returned value: UserMessage object or nil.

$lastMessage = queue.last() // $lastMessage contains the last user message in a dialog

queue.first() ?UserMessage

Purpose: returns the first user message or nil if the message queue is empty.

Arguments: not present.

Returned value: UserMessage object or nil.

$firstMessage = queue.first() // $firstMessage contains the first user message in a dialog

queue.nth(index int) ?UserMessage

Purpose: returns the user message by its sequence number starting from 1.

Arguments:

1. index – sequence number of the user message.

Returned value: UserMessage object or nil.

$message = queue.nth(1) // $message contains the first user message 
$message = queue.nth(5) // $message  contains the fifth user message  

queue.lastNth(index int) ?UserMessage

Purpose: returns the user message by its sequence number starting from the end of the queue. The last message corresponds to sequence number 1.

Arguments:

1. index – sequence number of the user message starting from the end of the queue.

Returned value: UserMessage object or nil.

$message = queue.lastNth(1) // $message contains the last user message
$message = queue.lastNth(5) // $message contains the fifth user message

Functions for working with facts

fact.save(context string, factName string, factValue mixed, botId string = nil, clientId string = nil)

Purpose: saves the fact to the fact base.

Arguments:

1. context – string that specifies the context where the fact exists.
2. factName – string that specidies the name of the fact.
3. factValue – any value that defines the contents of a fact.
4. botId – bot ID. Not specified by default.
5. clientId – Client ID. Not specified by default.

Returned value: not present.

fact.save("place", "city", "Moscow")                    // Fact that is available to all company bots
fact.save("place", "city", "Moscow", nil, @clientId)    // Fact with reference to the client
fact.save("place", "city", "Moscow", @botId)            // Fact with reference to the bot
fact.save("place", "city", "Moscow", @botId, @clientId) // Fact with reference to the bot and client

fact.load(context string, factName string, botId string = nil, clientId string = nil) mixed

Purpose:  retrieves a fact from the fact base.

Arguments:

1. context – a string that specifies the context where the fact exists.
2. factName – a string that specifies the name of the fact.
3. botId – bot ID. Not specified by default.
4. clientId – client ID. Not specified by default.

Returned value: contents of the fact.

fact.save("place", "city", "Moscow", @botId, @clientId) // Saves the fact with reference to the bot and the client
 $city = fact.load("place", "city", @botId, @clientId) // We load the fact into a variable. $city contains "Moscow"

fact.delete(context string, factName string, botId string = nil, clientId string = nil)

Purpose:  deletes a fact from the fact base.

Arguments:

1. context – a string that specifies the context where the fact exists.
2. factName – a string that specifies the name of the fact.
3. botId – bot ID. Not specified by default.
4. clientId – client ID. Not specified by default.

Returned value: not present.

fact.save("place", "city", "Moscow", @botId, @clientId) // Saves the fact with reference to the bot and the client
$city = fact.load("place", "city", @botId, @clientId)         // We load the fact into a variable. $city contains "Moscow"
fact.delete("place", "city", @botId, @clientId)               // Deletes fact.
$city = fact.load("place", "city", @botId, @clientId)         // Trying to load a remote fact. Now $city contains nil.

fact.query() FactQuery

Purpose: returns a FactQuery instance for working with the fact database.

Arguments: not present.

Returned value: FactQuery object.

// Added a couple of facts to the database
fact.save("place", "country", "Russia")
fact.save("place", "city", "Moscow")

// We loaded into $places a list of places sorted by fact name in descending order:
// [{"name": "city", "value": "Russia"}, {"name": "country", "value": "Moscow"}]
$places = fact.query().
    select("name,value").
    where("context", "=", "place").
    sortBy("-name").
    rows()

fact.cond() FactQueryCondition

Purpose: returns an instance of FactQueryCondition for creating complex conditions when working with the fact database.

Arguments: not present.

Returned value: FactQueryCondition object.

// Added facts to the database
fact.save("cities", "ekaterinburg", "Ekaterinburg")
fact.save("cities", "moscow", "Moscow")
fact.save("cities", "saint-petersburg", "Saint-Petersburg")
fact.save("cities", "novosibirsk", "Novosibirsk")

// Let's find one city whose name starts with letter "m" or with letter "t" and is not equal to the cities "Ekaterinburg" and "Novosibirsk"
$city = fact.query().
    select("value").
    where("context", "=", "cities").
    where(fact.cond().
        where("name", "^@", "м").
        orWhere("name", "^@", "т")).
    where("name", "not in", ("ekaterinburg", "novosibirsk")).
    one()

Функции для работы с таймером

timer.start(time int, nodeId string) string

Purpose: запускает таймер обратного отсчёта. По истечении указанного времени бот осуществит переход на указанный узел (блок).

Arguments:

1. time – время в секундах.
2. nodeId – идентификатор блока для перехода после завершения отсчёта.

Returned value: идентификатор таймера.

$timerId = timer.start(60, "760b9732-4bfb-4846-a348-faae5138fcb2") // $timerId содержит уникальный идентификатор таймера на 60 секунд

timer.stop(timerId string)

Purpose: останавливает (удаляет) таймер обратного отсчёта.

Arguments:

1. timerId – идентификатор таймера.

Returned value: отсутствует.

$timerId = timer.start(60, "760b9732-4bfb-4846-a348-faae5138fcb2")
timer.stop($timerId) // останавливаем (удаляем) таймер

Функции для работы с текстом на естественном языке (NLP)

nlp.parse(message string|UserMessage) Sentence

Purpose: парсит текст на естественном языке. 

Arguments:

1. message – текст на естественном языке или объект UserMessage.

Returned value: объект Sentence содержащий информацию о всех намерениях и сущностях исходного сообщения.

Примечание: данная функция извлекает из текста только сущности. Для работы с намерениями используйте функцию nlu.parse

$sentence = nlp.parse(queue.first()) // парсим первое сообщение пользователя

nlp.join(message1 string|UserMessage, message2 string|UserMessage) Sentence

Purpose: объединяет два текста на естественном языке в одно и затем парсит его.

Arguments:

1. message1 – текст на естественном языке или объект UserMessage.
2. message2 – текст на естественном языке или объект UserMessage.

Returned value: объект Sentence содержащий информацию о всех намерениях и сущностях объединённого сообщения.

$sentence = nlp.join(queue.lastNth(2), queue.lastNth(1)) // объединяем предпоследнее и последнее сообщения пользователя и затем парсим его  

nlp.setPerception($sentence Sentence)

Purpose: позволяет установить сообщение пользователя для обработки в других узлах (блоках) схемы бота. 

Arguments:

1. sentence – объект Sentence содержащий информацию о намерениях и сущностях некоторого сообщения.

Returned value: отсутствует.

$sentence = nlp.join(queue.lastNth(2), queue.lastNth(1)) // объединяем предпоследнее и последнее сообщения пользователя и затем парсим его
nlp.setPerception($sentence)                             // Теперь остальные узлы схемы будут работать с cообщением $sentence

Функции для "понимания" естественного языка.

nlu.parse(text string, agentId string, timezoneOffset int = 0, version int = 1) Sentence

Purpose: разбор текста на естественном языке. Выявление намерений и сущностей.

Arguments:

1. text – текст для разбора.
2. agentId – идентификатор (uuid) агента (нейросети) производящего разбор текста.
3. timezoneOffset – смещение временной зоны, необходимое для правильного выявления временных сущностей. По умолчанию используется смещение для UTC.
4. version – версия NLU. Может быть числом 1 или 2.

Returned value: объект Sentence.

$sentence = nlu.parse("Доброе утро Вася!", "d926726a-5acb-4233-8c1e-ce4300921de0")

Функции для работы с HTTP

http.sendRequest(url string, method string, body any = nil, headers Map = nil) Response

Purpose: отправляет HTTP запрос на указанный URL. 

Arguments:

1. url – URL адрес на который будет оправлен запрос.
2. method – HTTP метод. Допустимые значения: GET, POST, PUT, DELETE, PATCH, HEAD и OPTIONS.
3. body – тело запроса. Может быть представлено скалярным значением, списком или ассоциативным массивом.
4. headers – HTTP заголовки запроса. По умолчанию устанавливается заголовок Content-Type: application/json. 

Returned value: объект HTTP ответа.

// Выполняем запрос на получение списка юзеров
$response = http.sendRequest("https://iam.twin24.ai/api/v1/users", "GET", {"limit": 15, "offset": 5}, {"Authorization": "Bearer authToken"})

// Извлекаем информацию о запросе
$statusCode = $response.statusCode
$body = $response.body
$headers = $response.headers
$error = $response.error

http.request(url string = "", method string = "POST", body any = nil) Request

Purpose: формирует новый объект HTTP запроса.

Arguments:

1. url – строка URL.
2. method – название HTTP метода.
3. body – содержимое тела запроса.

Returned value: объект содержащий информацию о HTTP запросе.

$response = http.request("https://some.url", "POST", {"param1": 123, "param2": true}).
                 headers({"Content-Type": "application/json"}).
                 timeout(300).
                 send()

Объект Request

timeout(timeout int) Request

Purpose: задаёт максимально допустимое время запроса в секундах. Если запрос отрабатывает дольше указанного времени, то его выполнение прерывается.

Arguments:

1. timeout – допустимое время запроса в секундах.

Returned value: объект содержащий информацию о HTTP запросе.

$response = http.request("https://some.url", "GET").
                 timeout(300).
                 send()

url(url string) Request

Purpose: задаёт URL запроса.

Arguments:

1. url – строка URL.

Returned value: объект содержащий информацию о HTTP запросе.

$response = http.request().
                 url("http://some.url?p1=v1&p2=v2").
                 method("GET").
                 send()

method(method string) Request

Purpose: задаёт HTTP метод запроса.

Arguments:

1. method – название HTTP метода.

Returned value: объект содержащий информацию о HTTP запросе.

$response = http.request().
                 url("http://some.url?p1=v1&p2=v2").
                 method("GET").
                 send()

body(body any) Request

Purpose: задаёт тело запроса.

Arguments:

1. body – тело запроса.

Returned value: объект содержащий информацию о HTTP запросе.

$response = http.request().
                 url("http://some.url?p1=v1&p2=v2")
                 method("PUT").
                 body("some body").
                 send()

header(header string, value string) Request

Purpose: добавляет HTTP заголовок.

Arguments:

1. header – название HTTP заголовка.
2. value – значение HTTP заголовка.

Returned value: объект содержащий информацию о HTTP запросе.

$response = http.request().
                 url("http://some.url?p1=v1&p2=v2").
                 method("POST").
                 header("Content-Type", "application/json").
                 header("Accept-Language", "en-US,en;q=0.5").
                 send()

headers(headers Map) Request

Purpose: задаёт HTTP заголовки.

Arguments:

1. headers – HTTP заголовки.

Returned value: объект содержащий информацию о HTTP запросе.

$response = http.request().
                 url("http://some.url?p1=v1&p2=v2").
                 method("PUT").
                 body("some body").
                 headers({"Content-Type": "application/json", "Accept-Language": "en-US,en;q=0.5"}).
                 send()

file(fileId string, name string = "") Request

Purpose: добавляет файл для отправки по HTTP.

Arguments:

1. fileId – идентификатор ранее загруженного файла.
2. name – название параметра запроса. Если параметр не задан, то его имя будет совпадать с идентификатором файла.

Returned value: объект содержащий информацию о HTTP запросе.

$response = http.request().
                 url("http://some.url").
                 method("POST").
                 header("Content-Type", "multipart/form-data").
                 file($fileId, "file").
                 send()

send() Response

Purpose: отправляет сформированный запрос.

Returned value: объект ответа сервера.

$response = http.request("http://some.url?p1=v1&p2=v2", "PUT", "some body").
                 headers({"header1": "...", "header2": "...").
                 send()

Объект Response

statusCode int

Purpose: код статуса ответа.

$response = http.sendRequest("http://some.url?p1=v1&p2=v2", "PUT", "some body")
$code = $response.statusCode

body any

Purpose: тело ответа.

$response = http.sendRequest("http://some.url?p1=v1&p2=v2", "PUT", "some body")
$body = $response.body

headers Map

Purpose: заголовки ответа.

$response = http.sendRequest("http://some.url?p1=v1&p2=v2", "PUT", "some body")
$headers = $response.headers

error string

Purpose: значение элемента error тела ответа или пустая строка, если такого элемента нет.

$response = http.sendRequest("http://some.url?p1=v1&p2=v2", "PUT", "some body")
$error = $response.error

isError() bool

Purpose: определение успешности ответа.

Returned value: возвращает true, если свойство error не пустое или код статуса больше или равен 400, иначе возвращает false.

$response = http.sendRequest("http://some.url?p1=v1&p2=v2", "PUT", "some body")
$isError = $response.isError()

isSuccessful() bool

Purpose: определение успешности ответа.

Returned value: возвращает true, если свойство error пустое и код статуса меньше 400, иначе возвращает false.

$response = http.sendRequest("http://some.url?p1=v1&p2=v2", "PUT", "some body")
$isSuccessful = $response.isSuccessful()

hasHeader(header string) bool

Purpose: определение наличия заголовка.

Arguments:

1. header – название заголовка.

Returned value: true, если заголовок с указанным именем существует и false в противном случае.

$response = http.sendRequest("http://some.url?p1=v1&p2=v2", "PUT", "some body")
$hasContentType = $response.hasHeader("Content-Type")

header(header string) string

Purpose: получение значения заголовка.

Arguments:

1. header – название заголовка.

Returned value: значение заголовка с указанным именем или пустую строку, если такого заголовка нет.

$response = http.sendRequest("http://some.url?p1=v1&p2=v2", "PUT", "some body")
$contentType = $response.header("Content-Type")

toFile() string

Purpose: получение файла из HTTP ответа.

Returned value: идентификатор загруженного файла.

$response = http.sendRequest("http://some.url", "GET")
$fileId = $response.toFile()

Системные функции

sys.sleep(microseconds int)

Purpose: останавливает работу бота на указанное количество микросекунд. Если количество микросекунд превышает 1 минуту, то пауза будет уменьшена до 1 минуты.

Arguments:

1. microseconds – число микросекунд паузы.

Returned value: отсутствует.

sys.sleep(3_000_000) // Пауза в 3 секунды

Функции для работы с GPT-3

gpt3.ask(text string) string

Purpose: отправляет сообщение в нейросеть ChatGPT3 и возвращает её ответ.

Arguments:

1. text – запрос к нейросети на русском языке.

Returned value: ответ нейросети в виде строки.

$answer = gpt3.ask("Есть ли жизнь на Марсе?") // В $answer будет ответ нейросети на заданный вопрос

Объект FactQuery

Используя методы этого объекты вы можете выполнять и строить разнообразные запросы к базе фактов. База фактов представляет собой список записей. Каждая запись представляет собой единичный факт состоящий из следующих частей (полей):

• Контекст (context). Произвольная строка длина которой не превышает 255 символов. Обозначает некоторую предметную область в рамках которой существует факт. Может участвовать в поиске.
• Имя факта (name). Произвольная строка длина которой не превышает 255 символов. Служит для идентификации факта в заданном контексте. Может участвовать в поиске.
• Значение факта (value). Любое значение. Это собственно и есть та информация которую мы трактуем как факт. Не может участвовать в поиске (технически может, но результат недетерминирован).
• Идентификатор бота (botId). Может быть задан при сохранении факта с целью привязки факта к боту. Может участвовать в поиске.
• Идентификатор клиента (clientId). Может быть задан при сохранении факта с целью привязки факта к клиенту. Может участвовать в поиске.

select(fields string|Collection) FactQuery

Purpose: задаёт список полей из базы фактов значения которых следует вернуть в результате запроса. Если метод select не вызыался, то будут возвращены поля context,name и value.

Arguments:

1. fields – строка содержащая список неободимых полей разделённых запятой либо коллекция этих полей.

Returned value: тот же объект FactQuery.

$facts = fact.query().rows()                               // select не вызван возвращаем все поля.
$facts = fact.query().select(["value", "context"]).rows()  // Возвращаем список фактов для которых нам нужны только value и context.
$facts = fact.query().select("botId").rows()               // Возвращаем только поле botId к которым привязаны факты.

where(field string, operator string, value mixed) FactQuery

Purpose: задаёт условие поиска фактов. Несколько методов where объединяются по принципу логического "И", т.е. все условия должны быть выполнены. Метод where равносилен методу andWhere(field, operator, value).

Arguments:

1. field – название поля для которого задаётся условие, т.е. первый аргумент операции operator.
2. operator – оператор обозначающий операцию выполняющуюся над field. Список доступных операций смотри ниже.
3. value – второй аргумент операции.

Returned value: тот же объект FactQuery.

Список доступных операций:

1. "=" проверка, что field равно value.
2. "!=" или "<>" проверка на неравенство, что field не равно value.
3. ">" проверяет, что field больше value.
4. "<" проверяет, что field меньше value.
5. ">=" проверяет, что field больше или равно value.
6. "<=" проверяет, что field меньше или равно value.
7. "^@" или "startsWith" ищет совпадение строки value с началом field. Поиск регистрозависимый.
8. "~" проверяет соответствие field регулярному выражению value. Поиск регистрозависимый.
9. "!~" проверяет несоотвествие field регулярному выражению value. Поиск регистрозависимый.
10. "~*" проверяет соответствие field регулярному выражению value. Поиск регистронезависимый.
11. "!~*" проверяет несоотвествие field регулярному выражению value. Поиск регистронезависимый.
12. "in" проверяет совпадение field хотя бы с одним значением в коллекции value. 
13. "not in" проверяет несовпадение field со всеми значениями из коллекции value.

// Ищем факты у которых context содержит подстроку test
$facts = fact.query().
    select("name,value").
    where("context", "~", "^.*test.*$").
    rows()

andWhere(field string, operator string, value mixed) FactQuery

Эквивалентен where(field, operator, value).

orWhere(field string, operator string, value mixed) FactQuery

Аналогичен where, с той лишь разницей, что несколько вызовов этого метода объединяются по принципу логического "ИЛИ", т.е. должно выполняться хотя бы одно условие.

where(cond FactQueryCondition) FactQuery

Purpose: задаёт сложное (вложенное) условие. Несколько вызвов метода объединяются по принципу логического "И". Эквивалентен методу andWhere(cond).

Arguments:

1. cond – объект FactQueryCondition определяющий сложносоставное условие.

Returned value: тот же объект FactQuery.

// Ищем факты у которых context содержит подстроку test и при этом name равен "слово" или name начинается на "оп".
$facts = fact.query().
    select("name,value").
    where("context", "~", "^.*test.*$").
    andWhere(fact.cond().
        where("name", "=", "слово").
        orWhere("name", "^@", "оп")).
    rows()

andWhere(cond FactQueryCondition) FactQuery

Эквивалентен where(cond)

orWhere(cond FactQueryCondition) FactQuery

Аналогичен where(cond), с той лишь разницей, что несколько вызовов этого метода объединяются по принципу логического "ИЛИ", т.е. должно выполняться хотя бы одно условие.

sortBy(fields string|Collection) FactQuery

Purpose: задаёт сортирову фактов по указанным полям.

Arguments:

1. fields – строка содержащая список полей (через запятую) по которым следует отсортировать факты либо коллекция содержащая названия полей. Каждое поле может содержать префикс "+" для сортировки по возрастанию или "-" для сортировки по убыванию. Если префикс не указан, то используется сортировка по возрастанию. 

Returned value: тот же объект FactQuery. 

// Получаем все факты для бота с двойной сортировкой: 
// сначала по контексту по возрастанию (т.е. в алфавитном порядке)
// и далее по имени факта по убыванию.
$facts = fact.query().
    select("name,value").
    where("botId", "=", @botId)
    sortBy("+context,-name"). // можно также использовать коллеции. Например, sortBy(["+context", "-name"])
    rows()

limit(limit int) FactQuery

Purpose: ставит ограничение на максимальное количество извлекаемых фактов.

Arguments:

1. limit – целое число определяющее лимит на количество извлекаемых фактов.

Returned value: тот же объект FactQuery. 

// Получаем первые 10 фактов
$facts = fact.query().
    select("name,value").
    sortBy("name").
    limit(10).
    rows()

skip(count int) FactQuery

Purpose: задаёт количество фактов которые следует пропустить при поиске.

Arguments:

1. count – целое число определяющее количество фактов для пропуска.

Returned value: тот же объект FactQuery. 

// Пропускаем 5 первых фактов и извлекаем следующие 10
$facts = fact.query().
    select("name,value").
    sortBy("name").
    skip(5).
    limit(10).
    rows()

one() mixed

Purpose: возвращает первое указанное через select поле первого найденного факта.

Arguments: отсутствуют.

Returned value: значение поля.

// Извлекает имя первого найденного факта
$firstFactName = fact.query().
    select("name,value").        // value хоть и указано, но будет проигнорировано
    one()

column() List

Purpose: возвращает список состоящий из всех значений первого выбранного поля найденных фактов.

Arguments: отсутствуют.

Returned value: список значений поля.

// Извлекает список имён всех найденных фактов
$names = fact.query().
    select("name,value").        // value хоть и указано, но будет проигнорировано
    column()

row() Map

Purpose: возвращает все выбранные поля в виде ассоциативного массива для первого найденного факта.

Arguments: отсутствуют.

Returned value: значения всех полей первого факта.

// Извлекает имя и значение первого найденного факта
$names = fact.query().
    select("name,value").
    row()

rows() List<Map>

Purpose: возвращает список всех найденных фактов. Каждый факт возвращается как ассоциативный массив ключами которого являются поля факта, а значениями - значения полей.

Arguments: отсутствуют.

Returned value: значения всех полей всех фактов.

// Извлекает имя и значение всех фактов
$names = fact.query().
    select("name,value").
    rows()

Объект FactQueryCondition

Используйте методы этого объекта чтобы строить сложные вложенные условия к базе фактам.

where(field string, operator string, value mixed) FactQueryCondition

Аналогичен методу where(field string, operator string, value mixed) объекта FactQuery.

andWhere(field string, operator string, value mixed) FactQueryCondition

Аналогичен методу andWhere(field string, operator string, value mixed) объекта FactQuery.

orWhere(field string, operator string, value mixed) FactQueryCondition

Аналогичен методу orWhere(field string, operator string, value mixed) объекта FactQuery.

and(field string, operator string, value mixed) FactQueryCondition

Аналогичен методу andWhere(field string, operator string, value mixed) объекта FactQuery.

or(field string, operator string, value mixed) FactQueryCondition

Аналогичен методу orWhere(field string, operator string, value mixed) объекта FactQuery.

where(cond FactQueryCondition) FactQueryCondition

Аналогичен методу where(cond FactQueryCondition) объекта FactQuery.

andWhere(cond FactQueryCondition) FactQueryCondition

Аналогичен методу andWhere(cond FactQueryCondition) объекта FactQuery.

orWhere(cond FactQueryCondition) FactQueryCondition

Аналогичен методу orWhere(cond FactQueryCondition) объекта FactQuery.

and(cond FactQueryCondition) FactQueryCondition

Аналогичен методу andWhere(cond FactQueryCondition) объекта FactQuery.

or(cond FactQueryCondition) FactQueryCondition

Аналогичен методу orWhere(cond FactQueryCondition) объекта FactQuery.

Объект UserMessage

message string

Purpose: оригинальный текст сообщения.

$msg = queue.last().message // $msg содержит текст последнего сообщения пользователя

attachments List<string>

Purpose: список идентификаторов файлов приложенных к сообщению.

$attachments = queue.first().attachments // $attachments содержит список вложений первого сообщения пользователя.

isEmpty() bool

Purpose: определяет пустое ли сообщение.

Arguments: отсутствуют.

Returned value: true, если сообщение пустое и false в противном случае.

$isEmpty = queue.last().isEmpty() // $isEmpty содержит true, если последнее сообщение пользователя пустое и false в противном случае

hasAttachments() bool

Purpose: определяет есть ли вложения в данном сообщении.

Arguments: отсутствуют.

Returned value: true, если сообщение имеет вложения и false в противном случае.

$hasAttachments = queue.first().hasAttachments() // $hasAttachments содержит true, если первое сообщение пользователя имеет вложения и false в противном случае

Объект Sentence

intent string

Purpose: распознанное намерение.

$sentence = nlu.parse("Привет Вася", "d926726a-5acb-4233-8c1e-ce4300921de0")
$intent = $sentence.intent   // $intent содержит "greeting"

intentConfidence number

Purpose: степень достоверности распознанного намерения (1 – однозначное распознавание, 0 – намерение фактически нераспознанно).

$sentence = nlu.parse("Привет Вася", "d926726a-5acb-4233-8c1e-ce4300921de0")
$confidence = $sentence.intentConfidence   // $confidence содержит 0.98

entities List<Tuple>

Purpose: список распознанных сущностей. Каждый элемент списка содержит кортеж из трёх элементов: тип сущности (string), значение сущности (строка), достоверность распознавания сущности (number).

$sentence = nlu.parse("Доброе утро Вася", "d926726a-5acb-4233-8c1e-ce4300921de0")
$entities = $sentence.entities // $entities содержит [("human-name", "Вася", 0.96), ("time", "2023-01-09 23:30:00", 0.87)]
$first = $entities.get(0)      // $first содержит ("human-name", "Вася", 0.96)
$type = $first.get(0)          // $type содержит "human-name"