Функции общего назначения

del(varName string)

Назначение: удаление локальной или модульной переменной.

Аргументы:

1. varName - название переменной в виде строки. Может начинаться с префикса области видимости переменной. Если префикс опущен то считается, что переменная локальная.

Возвращаемое значение: отсутствует.

$localVar = 123
#moduleVar = true
del("$localVar")   // Удаляет локальную переменную $localVar
del("localVar")    // Тоже самое что и del("$localVar")
del("#moduleVar")  // Удаляет переменную с областью видимости в пределах модуля 

Математические функции

math.pos(num mixed) number

Назначение: фактически преобразует аргумент к числу. Эквивалент унарной операции "+".

Аргументы:

1. num - произвольное значение которое будет преобразовано к числу.

Возвращаемое значение: число.

$a = math.pos(true)  // $a будет равно 1
$a = math.pos(false) // $a будет равно 0
$a = math.pos(nil)   // $a будет равно 0
$a = +true           // $a будет равно 1, то же что и math.pos(true)

math.neg(num number) number

Назначение: меняет знак числа. Эквивалент унарной операции "-".

Аргументы:

1. num - произвольное число у кторого изменится знак на противоположный.

Возвращаемое значение: число со знаком обратному исходному.

$a = math.neg(-1) // $a будет равно 1
$a = math.neg(1)  // $a будет равно -1
$a = math.neg(0)  // $a будет равно 0
$a = -(-10)       // $a будет равно 10, то же что и math.neg(-10)

math.inv(num number) number

Назначение: инверсия бит числа. Эквивалент унарной операции "~".

Аргументы:

1. num - произвольное число у кторого инвертируем биты.

Возвращаемое значение: инвертированное число.

$a = math.inv(5) // $a равно 3
$a = ~5          // то же, что и предыдущая строка

math.not(num number) bool

Назначение: логическое отрицание числа. Эквивалент унарной операции "!".

Аргументы:

1. num - произвольное число.

Возвращаемое значение: true если num не равно 0 и false в противном случае.

$a = math.not(5) // $a равно false
$a = math.not(0) // $a равно true
$a = !0          // то же, что и предыдущая строка

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

Назначение: сложение чисел. Эквивалент бинарной операции "+".

Аргументы:

1. num1 - первое слагаемое.
2. num2 - второе слагаемое.
3. precision - точность вычислений, количество цифр после запятой. Значение по умолчанию 12, масимальное - 100.

Возвращаемое значение: сумма чисел.

$a = math.add(1.5, 3.5)         // $a равно 5
$a = 1.5 + 3.5                  // то же, что и предыдущая строка
$a = math.add(1.000006, 2.1, 5) // $a равно 3.10001

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

Назначение: разность чисел. Эквивалент бинарной операции "-".

Аргументы:

1. num1 - уменьшаемое.
2. num2 - вычитаемое.
3. precision - точность вычислений, количество цифр после запятой. Значение по умолчанию 12, масимальное - 100.

Возвращаемое значение: разность чисел.

$a = math.sub(1.5, 3.5)         // $a равно -2
$a = 1.5 - 3.5                  // то же, что и предыдущая строка
$a = math.sub(2.100006, 1.1, 5) // $a равно 1.00001

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

Назначение: произведение чисел. Эквивалент бинарной операции "*".

Аргументы:

1. num1 - первый множитель.
2. num2 - второй множитель.
3. precision - точность вычислений, количество цифр после запятой. Значение по умолчанию 12, масимальное - 100.

Возвращаемое значение: произведение чисел.

$a = math.mul(1.5, 3.5)         // $a равно 5.25
$a = 1.5 * 3.5                  // то же, что и предыдущая строка
$a = math.mul(1.2345, 1.234, 5) // $a равно 1.52337

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

Назначение: частное чисел. Эквивалент бинарной операции "/".

Аргументы:

1. num1 - делимое.
2. num2 - делитель.
3. precision - точность вычислений, количество цифр после запятой. Значение по умолчанию 12, масимальное - 100.

Возвращаемое значение: частное чисел.

$a = math.div(1.5, 3.5) // $a равно 0.428571428571
$a = 1.5 / 3.5          // то же, что и предыдущая строка
$a = math.div(1, 3, 5)  // $a равно 0.33333

math.idiv(num1 number, num2 number) int

Назначение: целочисленное деление чисел. Эквивалент бинарной операции "\".

Аргументы:

1. num1 - делимое.
2. num2 - делитель.

Возвращаемое значение: целая часть частного чисел.

$a = math.idiv(2.5, 0.3) // $a равно 8
$a = 2.5 \ 0.3           // то же, что и предыдущая строка

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

Назначение: остаток от деления двух чисел. Эквивалент бинарной операции "%".

Аргументы:

1. num1 - делимое.
2. num2 - делитель.
3. precision - точность вычислений, количество цифр после запятой. Значение по умолчанию 12, масимальное - 100.

Возвращаемое значение: остаток от деления.

$a = math.mod(3.5, 1.5)    // $a равно 0.5
$a = 3.5 % 1.5             // то же, что и предыдущая строка
$a = math.mod(1/3, 2/7, 5) // $a равно 0.04762

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

Назначение: возведение числа base в степень power. Эквивалент бинарной операции "**".

Аргументы:

1. base - основание.
2. power - степень.
3. precision - точность вычислений, количество цифр после запятой. Значение по умолчанию 12, масимальное - 100.

Возвращаемое значение: результат возведения в степень.

$a = math.pow(1.5, 3.5)    // $a равно 4.133513940947
$a = 1.5 ** 3.5            // то же, что и предыдущая строка
$a = math.pow(1.3, 7.1, 5) // $a равно 0.44166

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

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

Аргументы:

1. num - число из которого извлекается корень.
2. precision - точность вычислений, количество цифр после запятой. Значение по умолчанию 12, масимальное - 100.

Возвращаемое значение: квадратный корень либо ошибка, если число отрицательное.

$a = math.sqrt(3.14)   // $a равно 1.772004514667
$a = math.sqrt(1.7, 5) // $a равно 0.30384

math.round(num number, precision int) number

Назначение: округление числа до требуемого знака после запятой.

Аргументы:

1. num - число для округления.
2. precision - точность округления, количество цифр после запятой. Масимальное значение - 100.

Возвращаемое значение: округлённое с заданной точностью число.

$a = math.round(3.14159265358979323846264338327950288419716, 17) // $a равно 3.14159265358979324
$a = math.round(3.14159265358979323846264338327950288419716, 2)  // $a равно 3.14
$a = math.round(3.14159265358979323846264338327950288419716, 0)  // $a равно 3

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

str.len(str string) int

Назначение: определение длины строки в символах.

Аргументы:

1. str - строка длину которой необходимо определить.

Возвращаемое значение: целое число равное количеству символов в строке.

$str = "Какая-то строка"
$len = str.len($str) // $len будет содержать 15

str.lower(str string) string

Назначение: преобразовапние символов строки в нижний регистр.

Аргументы:

1. str - строка, которую необходимо преобразовать.

Возвращаемое значение: строка все символы которой находятся в нижнем регистре.

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

str.upper(str string) string

Назначение: преобразование символов строки в верхний регистр.

Аргументы:

1. str - строка, которую необходимо преобразовать.

Возвращаемое значение: строка все символы которой находятся в верхнем регистре.

$str = "СтРоКа"
$upper = str.upper($str) // $lower будет содержать "СТРОКА" 

str.ucfirst(str string) string

Назначение: преобразование первого символа строки в верхний регистр.

Аргументы:

1. str - строка, первый символ которой необходимо преобразовать.

Возвращаемое значение: строка в которой первый символ записан в верхнем регистре.

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

str.lcfirst(str string) string

Назначение: преобразование первого символа строки в нижний регистр.

Аргументы:

1. str - строка, первый символ которой необходимо преобразовать.

Возвращаемое значение: строка в которой первый символ записан в нижнем регистре.

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

str.letter(str string, index int) string

Назначение: получение указанного символа строки.

Аргументы:

1. str - строка, символ которой требуется получить.
2. index - целое число определяющее позицию символа в строке начиная с 0. Если это число отрицательное то отсчёт начинается с конца строки.

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

$str = "Слово"
$firstLetter = str.letter($str, 0)  // Первая буква
$lastLetter = str.letter($str, -1)  // Последняя буква

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

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

Аргументы:

1. str - строка, символ которой требуется получить.
2. index - целое число определяющее позицию символа с начала строки начиная с 0. При этом знак числа игнорируется. Значение по умолчанию 0 (первый символ).

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

$str = "Слово"
$firstLetter = str.first($str)      // Первая буква
$secondLetter = str.first($str, 1)  // Вторая буква

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

Назначение: получение указанного символа строки начиная с конца строки.

Аргументы:

1. str - строка, символ которой требуется получить.
2. index - целое число определяющее позицию символа с конца строки начиная с 0. При этом знак числа игнорируется. Значение по умолчанию 0 (последний символ).

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

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

str.concat(str1 string, str2 string) string

Назначение: объединяет две строки в одну.

Аргументы:

1. str1 - строка которая объединяется.
2. str2 - строка с которой объединяются.

Возвращаемое значение: новая строка состоящая из первой строки справа от которой добавлена вторая строка.

$str1 = "один"
$str2 = "два"
$str = str.concat($str1, $str2) // $str будет содержать "одиндва" 

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

Назначение: возвращает подстроку строки str, начинающейся с offset символа по счету и длиной length символов.

Аргументы:

1. str - исходная строка.
2. offset - если offset неотрицателен, возвращаемая подстрока начинается с позиции offset от начала строки, считая от нуля.
   Если offset отрицательный, возвращаемая подстрока начинается с позиции, отстоящей на offset символов от конца строки str.
   Если str меньше offset символов, будет возвращена пустая строка.
3. length - если length положительный, возвращаемая строка будет не длиннее length символов, начиная с параметра offset (в зависимости от длины string).
   Если length отрицательный, то будет отброшено указанное этим аргументом число символов с конца строки string (после того как будет вычислена стартовая позиция, если offset отрицателен). Если при этом позиция начала подстроки, определяемая аргументом offset, находится в отброшенной части строки или за ней, возвращается пустая строка. 
   Если параметр length задан и равен 0, будет возвращена пустая строка.
   Если параметр length опущен или nil, то будет возвращена подстрока, начинающаяся с позиции, указанной параметром offset и длящейся до конца строки.

Возвращаемое значение: часть str или пустая строка.

$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

Назначение: объединяет элементы коллекции (кортежа, списка или ассоциативного массива) в строку.

Аргументы:

1. arr - коллекция элементов для объединения.
2. separator - разделитель элементов коллекции. По умолчанию равен пустой строке.

Возвращаемое значение:  новая строка составленная из всех элементов коллекции отделённых между собой разделителем.

$str = str.join([1, 2, 3, 4, 5], "-")             // $str будет содержать "1-2-3-4-5"
$str = str.join(("a", "b", "c"))                  // $str будет содержать "abc"
$str = str.join({"a": "один", "b": "два"}, " + ") // $str будет содержать "один + два"
$str = str.join(["одно"], "/")                    // $str будет содержать "одно"
$str = str.join([], "/")                          // $str будет содержать ""

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

Назначение: разбивает строку на части использую separator в качестве разделителя.

Аргументы:

1. str - строка для разделения.
2. separator - разделитель. Если равен пустой строке, то разбиение происходит посимвольно.
3. limit - необязательный параметр равный максимальному количеству частей на которые будет разбита строка. Если limit равен 0, то без ограничений. Если limit является положительным, возвращаемый список будет содержать максимум limit элементов, при этом последний элемент будет содержать остаток строки str. Если limit отрицателен, то будут возвращены все компоненты, кроме последних -limit.

   
   

Возвращаемое значение:  список подстрок на которые была разбита строка.

$letters = str.split("абвгде")             // Получили список букв слова
$words = str.split("один два три", " ")    // Получили список слов
$words = str.split("один два три", " ", 1) // words содержит ["один", "два три"]

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

Назначение: ищет все вхождения подстроки в строке и заменяет их на заданное значение.

Аргументы:

1. str - строка для преобразования.
2. search - подстрока которая ищется в исходной строке. 
3. replace - строка замены.

Возвращаемое значение:  новая строка в которой все search заменены на replace.

$str = str.replace("мама мыла раму", "рам", "Даш") // $str содержит "мама мыла Дашу"

str.match(str string, pattern string) bool

Назначение: выполняет проверку данной строки регулярному выражению.

Аргументы:

1. str - строка для сопоставления с регулярным выражением.
2. pattern - шаблон регулярного выражения. 

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

Примечание: в качестве регулярных выражений используется Perl совместимые регулярные выражения (PCRE). Ссылка на документацию и примеры регулярных выражений: PCRE Doc.

Онлайн редактор регулярных выражений: http://myregexp.com/

$isIntNumber = str.match("1.234", "/^[0-9]+$/") // $isIntNumber будет равен false
$isIntNumber = str.match("1234", "/^[0-9]+$/")  // $isIntNumber будет равен true

str.distance(str1 string, str2 string) number

Назначение: вычисляет степень сходства двух строк.

Аргументы:

1. str1 - первая строка для сравнения.
2. str2 - вторая строка для сравнения. 

Возвращаемое значение:  возвращает число от 0 до 1 включительно определяющее степень сходства двух строк. 1 - строки эквивалентны, 0 - строки абсолютно разные.

Примечание: функция фактически вычисляет расстояние Дамерау-Левенштейна.

$d = str.distance("", "abc")              // $d равен 0
$d = str.distance("Да", "да")             // $d равен 1
$d = str.distance("корыто", "открыто")    // $d равен 0.714
$d = str.distance("Да, верно", "таверна") // $d равен 0.625
$d = str.distance("жутко косые бананы", "жуй кокосы, ешь бананы") // $d равен 0.714 
$d = str.distance("сошел с ума от раны", "Пошел он в пусурманы")  // $d равен 0.45
$d = str.distance("ёж", "дезоксирибонуклеиновая кислота")         // $d равен 0.033

Функции хэширования

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

Назначение: вычисляет хэш строки согласно указанному алгоритму.

Аргументы:

1. text - произвольная строка для хэширования.
2. algo - название алгоритма хэширования. По умолчанию используется алгоритм md5.
3. binary - когда установлено в true, выводит необработанные двоичные данные. При false выводит данные в шестнадцатеричной кодировке в нижнем регистре. По умолчания равен false.

Возвращаемое значение: возвращает строку содержащую вычисленный хеш-код в шестнадцатеричной кодировке в нижнем регистре. Если binary задан как true, то возвращается хеш-код в виде бинарных данных. В случае ошибки (например, если указан недопустимый алгоритм хэширования) возвращает пустую строку.

Допустимые значения алгоритмов хэширования:

• 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

Примечание: если третий параметр true, то передавать возвращаемое функцией значение в качества сообщения бота или его части нельзя. Это приведёт к падению бота.

$hash = hash.of("Наглый коричневый лисёнок прыгает вокруг ленивой собаки.")                 // $hash будет содержать bff8b4bc8b5c1c1d5b3211dfb21d1e76
$hash = hash.of("Наглый коричневый лисёнок прыгает вокруг ленивой собаки.", "ripemd160")    // $hash будет содержать 8817ca339f7f902ad3fb456150a1bb9b4cb5dde9
$hash = hash.of("Наглый коричневый лисёнок прыгает вокруг ленивой собаки.", "sha256", true) // $hash будет содержать бинарную строку (содержащую неотображаемые символы)

Функции кодирования/декодирования

codec.base64Encode(str string) string

Назначение: кодирует заданную строку в base64.

Аргументы:

1. str - произвольная строка для кодирования.

Возвращаемое значение: возвращает строку закодированную в base64.

$encoded = codec.base64Encode("Привет!") // $encoded будет содержать строку "0J/RgNC40LLQtdGCIQ=="

codec.base64Decode(str string) ?string

Назначение: декодирует заданную в base64 строку.

Аргументы:

1. str - строка закодированная в base64.

Возвращаемое значение: возвращает раскодированную строку либо nil, если закодированная строка содержит символы не входящие в алфавит символов base64 кодировки.

$decoded = codec.base64Decode("0J/RgNC40LLQtdGCIQ==") // $decoded будет содержать строку "Привет!"
$failed = codec.base64Decode("Привет!")               // $failed будет равен nil

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

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

Назначение: складывает две даты, заданные в виде строки либо как число секунд.

• Если хотя бы один из аргументов функции число секунд, то это число будет прибавлено к числу секунд другой даты.
• Если обе даты заданы строкой, то результат определяется по формуле d1 + abs(secondsOf(d1) - secondsOf(d2)), где abs - модуль числа (положительное значение), secondsOf - это дата представленная как количество секунд прошедших с начала 1970 года (даты до этого времени представлены отрицательным значением). 

Аргументы:

1. d1 - строка представляющая собой дату в одном из допустимых форматов или целое число соответствующее количеству секунд.
2. d2 - аналогично первому аргументу.

Возвращаемое значение: возвращает новую дату и время в виде строки.

$d = dt.add("2022-01-01 12:30:00", 59)                    // $d содержит строку "2022-01-01 12:30:59" 
$d = dt.add(3600, "2022-01-01 12:30:00")                  // $d содержит строку "2022-01-01 13:30:00"
$d = dt.add("2022-01-01 00:00:00", "2022-01-02 00:00:00") // $d содержит строку "2022-01-03 00:00:00"

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

Назначение: вычисляет разность двух дат, заданных в виде строк либо количеством секунд.

• Если обе даты заданы количеством секунд, то функция вернёт их разность в виде числа секунд.
• Если обе даты заданы строкой, то будет возвращено целое число равное разности между датами в секундах.
• Если первый аргумент задан строкой даты, а второй числом секунд, то результатом будет новая дата равная разности даты и числа секунд.
• Если второй аргумент задан строкой даты, а первый числом секунд, то результатом будет ошибка.

Аргументы:

1. d1 - строка представляющая собой дату в одном из допустимых форматов или целое число соответствующее количеству секунд.
2. d2 - аналогично первому аргументу.

Возвращаемое значение: возвращает новую дату и время в виде строки либо число секунд - разность дат.

$d = dt.sub(100, 50)                                      // $d содержит 50
$d = dt.sub("2022-01-01 12:30:00", 3600)                  // $d содержит строку "2022-01-01 11:30:00"
$d = dt.sub(3600, "2022-01-01 12:30:00")                  // Такой вызов недопустим и приведёт к остановке программы
$d = dt.sub("2022-01-01 01:00:00", "2022-01-01 00:00:00") // $d содержит 3600

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

Назначение: форматирует дату согласно заданному формату.

Аргументы:

• dt - дата заданная строкой или числом секунд.
• format - строка определяющая формат даты и времени.

Возвращаемое значение: строка даты в заданном формате.

Допустимые параметры форматирования:

Примечание: если строка формата содержит символы совпадающие с вышеперечисленными, но не являющиеся параметрами форматирования, то их следует экранировать с помощью символа обратного слэша "\".

$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

Назначение: возвращает ближайшую будущую к текущей дату по заданному дню.

Аргументы:

1. day - число дней для определения ближайшей в будущем даты.

Возвращаемое значение: возвращает ближайшую к day дату.

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

date.nearPast(day int) string

Назначение: возвращает ближайшую прошлую к текущей дату по заданному дню.

Аргументы:

1. day - число дней для определения ближайшей в прошлом даты.

Возвращаемое значение: возвращает ближайшую к day дату.

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

date.future(day int) string

Назначение: возвращает дату соответствующую указанному дню в следующем месяце.

Аргументы:

1. day - число дней для определения даты в будущем.

Возвращаемое значение: дата в будущем.

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

date.past(day int) string

Назначение: возвращает дату соответствующую указанному дню в прошлом месяце.

Аргументы:

1. day - число дней для определения даты в прошлом.

Возвращаемое значение: дата в прошлом.

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

time.nearFuture(minute int) string

Назначение: возвращает ближайшее будущее к текущему время по заданному количеству минут.

Аргументы:

1. minute - число минут для определения ближайшего в будущем времени.

Возвращаемое значение: возвращает ближайшее к 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

Назначение: возвращает ближайшее прошлое к текущему время по заданному количеству минут.

Аргументы:

1. minute - число минут для определения ближайшего в прошлом времени.

Возвращаемое значение: возвращает ближайшее к minute время.

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

time.future(minute int) string

Назначение: возвращает время соответствующее указанному числу минут в следующем часе.

Аргументы:

1. minute - число минут для определения времени в будущем.

Возвращаемое значение: время в будущем.

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

time.past(minute int) string

Назначение: возвращает время соответствующее указанному числу минут в прошедшем часе.

Аргументы:

1. minute - число минут для определения времени в прошлом.

Возвращаемое значение: время в прошлом.

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

Функции по работе с очередью сообщений пользователя

queue.size() int

Назначение: определение размера очереди сообщений пользователя.

Аргументы: отсутствуют.

Возвращаемое значение: число сообщений пользователя.

$messageCount = queue.size() // $messageCount содержит число сообщений пользователя за всё время диалога

queue.last() ?UserMessage

Назначение: возвращает последнее сообщение пользователя либо nil, если очередь сообщений пуста.

Аргументы: отсутствуют.

Возвращаемое значение: объект UserMessage или nil.

$lastMessage = queue.last() // $lastMessage содержит последнее на данный момент сообщение пользователя

queue.first() ?UserMessage

Назначение: возвращает первое сообщение пользователя либо nil, если очередь сообщений пуста.

Аргументы: отсутствуют.

Возвращаемое значение: объект UserMessage или nil.

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

queue.nth(index int) ?UserMessage

Назначение: возвращает сообщение пользователя по его порядковому номеру, начиная с 1.

Аргументы:

1. index - порядковый номер сообщения пользователя.

Возвращаемое значение: объект UserMessage или nil.

$message = queue.nth(1) // $message содержит первое сообщение пользователя
$message = queue.nth(5) // $message содержит пятое сообщение пользователя

queue.lastNth(index int) ?UserMessage

Назначение: возвращает сообщение пользователя по его порядковому номеру считая с конца очереди. Последнее сообщение соответствует порядковому номеру 1.

Аргументы:

1. index - порядковый номер сообщения пользователя считая с конца очереди.

Возвращаемое значение: объект UserMessage или nil.

$message = queue.lastNth(1) // $message содержит последнее сообщение пользователя
$message = queue.lastNth(5) // $message содержит пятое с конца очереди сообщение пользователя

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

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

Назначение: сохраняет факт в базе фактов.

Аргументы:

1. context - строка определяющая контекс в рамках которого существует факт.
2. factName - строка определяющая название факта.
3. factValue - любое значение определяющее содержимое факта.
4. botId - идентификатор бота. По умолчанию не задан.
5. clientId - идентификатор клиента, По умолчанию не задан.

Возвращаемое значение: отсутствует.

fact.save("место", "город", "Екатеринбург")                    // Факт доступный всем ботам компании       
fact.save("место", "город", "Екатеринбург", nil, @clientId)    // Факт с привязкой к клиенту
fact.save("место", "город", "Екатеринбург", @botId)            // Факт с привязкой к боту
fact.save("место", "город", "Екатеринбург", @botId, @clientId) // Факт с привязкой к боту и клиенту

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

Назначение:  извлекает факт из базы фактов.

Аргументы:

1. context - строка определяющая контекс в рамках которого существует факт.
2. factName - строка определяющая название факта.
3. botId - идентификатор бота. По умолчанию не задан.
4. clientId - идентификатор клиента, По умолчанию не задан.

Возвращаемое значение: содержимое факта.

fact.save("место", "город", "Екатеринбург", @botId, @clientId) // Сохраняет факт с привязкой к боту и клиенту
$city = fact.load("место", "город", @botId, @clientId)         // Загружаем факт в переменную. $city содержит "Екатеринбург"

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

Назначение:  удаляет факт из базы фактов.

Аргументы:

1. context - строка определяющая контекс в рамках которого существует факт.
2. factName - строка определяющая название факта.
3. botId - идентификатор бота. По умолчанию не задан.
4. clientId - идентификатор клиента, По умолчанию не задан.

Возвращаемое значение: отсутствует.

fact.save("место", "город", "Екатеринбург", @botId, @clientId) // Сохраняет факт с привязкой к боту и клиенту
$city = fact.load("место", "город", @botId, @clientId)         // Загружаем факт в переменную. $city содержит "Екатеринбург"
fact.delete("место", "город", @botId, @clientId)               // Удаляем факт.
$city = fact.load("место", "город", @botId, @clientId)         // Пытаемся загрузить удалённый факт. Теперь $city содержит nil.

fact.query() FactQuery

Назначение: возвращает экземпляр FactQuery для построения и выполнения запросов к базе фактов.

Аргументы: отсутствуют.

Возвращаемое значение: объект FactQuery.

// Добавили пару фактов в базу
fact.save("место", "страна", "Россия")
fact.save("место", "город", "Екатеринбург")

// Загрузили в $places список мест отсортированных по имени факта в порядке убывания:
// [{"name": "город", "value": "Россия"}, {"name": "страна", "value": "Екатеринбург"}]
$places = fact.query().
    select("name,value").
    where("context", "=", "место").
    sortBy("-name").
    rows()

fact.cond() FactQueryCondition

Назначение: возвращает экземпляр FactQueryCondition для построения составных условий в запросах к базе фактов.

Аргументы: отсутствуют.

Возвращаемое значение: объект FactQueryCondition.

// Добавили факты в базу
fact.save("города", "екатеринбург", "Екатеринбург")
fact.save("города", "москва", "Москва")
fact.save("города", "санкт-петербург", "Санкт-Петербург")
fact.save("города", "новосибирск", "Новосибирск")

// Найдём один город начинающийся с буквы "м" или с буквы "т" и не равный городам "Екатеринбург" и "Новосибирск"
$city = fact.query().
    select("value").
    where("context", "=", "города").
    where(fact.cond().
        where("name", "^@", "м").
        orWhere("name", "^@", "т")).
    where("name", "not in", ("екатеринбург", "новосибирск")).
    one()

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

timer.start(time int, nodeId string) string

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

Аргументы:

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

Возвращаемое значение: идентификатор таймера.

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

timer.stop(timerId string)

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

Аргументы:

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

Возвращаемое значение: отсутствует.

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

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

nlp.parse(message string|UserMessage) Sentence

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

Аргументы:

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

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

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

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

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

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

Аргументы:

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

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

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

nlp.setPerception($sentence Sentence)

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

Аргументы:

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

Возвращаемое значение: отсутствует.

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

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

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

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

Аргументы:

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

Возвращаемое значение: объект Sentence.

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

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

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

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

Аргументы:

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

Возвращаемое значение: объект 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

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

Аргументы:

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

Возвращаемое значение: объект содержащий информацию о 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

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

Аргументы:

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

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

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

url(url string) Request

Назначение: задаёт URL запроса.

Аргументы:

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

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

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

method(method string) Request

Назначение: задаёт HTTP метод запроса.

Аргументы:

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

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

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

body(body any) Request

Назначение: задаёт тело запроса.

Аргументы:

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

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

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

header(header string, value string) Request

Назначение: добавляет HTTP заголовок.

Аргументы:

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

Возвращаемое значение: объект содержащий информацию о 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

Назначение: задаёт HTTP заголовки.

Аргументы:

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

Возвращаемое значение: объект содержащий информацию о 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

Назначение: добавляет файл для отправки по HTTP.

Аргументы:

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

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

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

send() Response

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

Возвращаемое значение: объект ответа сервера.

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

Объект Response

statusCode int

Назначение: код статуса ответа.

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

body any

Назначение: тело ответа.

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

headers Map

Назначение: заголовки ответа.

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

error string

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

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

isError() bool

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

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

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

isSuccessful() bool

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

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

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

hasHeader(header string) bool

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

Аргументы:

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

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

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

header(header string) string

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

Аргументы:

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

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

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

toFile() string

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

Возвращаемое значение: идентификатор загруженного файла.

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

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

sys.sleep(microseconds int)

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

Аргументы:

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

Возвращаемое значение: отсутствует.

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

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

gpt3.ask(text string) string

Назначение: отправляет сообщение в демо версию нейросети RuGTP-3 и возвращает её ответ.

Аргументы:

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

Возвращаемое значение: ответ нейросети в виде строки.

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

Объект FactQuery

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

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

select(fields string|Collection) FactQuery

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

Аргументы:

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

Возвращаемое значение: тот же объект 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

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

Аргументы:

1. field - название поля для которого задаётся условие, т.е. первый аргумент операции operator.
2. operator - оператор обозначающий операцию выполняющуюся над field. Список доступных операций смотри ниже.
3. 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

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

Аргументы:

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

Возвращаемое значение: тот же объект 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

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

Аргументы:

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

Возвращаемое значение: тот же объект FactQuery. 

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

limit(limit int) FactQuery

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

Аргументы:

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

Возвращаемое значение: тот же объект FactQuery. 

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

skip(count int) FactQuery

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

Аргументы:

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

Возвращаемое значение: тот же объект FactQuery. 

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

one() mixed

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

Аргументы: отсутствуют.

Возвращаемое значение: значение поля.

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

column() List

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

Аргументы: отсутствуют.

Возвращаемое значение: список значений поля.

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

row() Map

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

Аргументы: отсутствуют.

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

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

rows() List<Map>

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

Аргументы: отсутствуют.

Возвращаемое значение: значения всех полей всех фактов.

// Извлекает имя и значение всех фактов
$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

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

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

attachments List<string>

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

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

isEmpty() bool

Назначение: определяет пустое ли сообщение.

Аргументы: отсутствуют.

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

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

hasAttachments() bool

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

Аргументы: отсутствуют.

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

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

Объект Sentence

intent string

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

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

intentConfidence number

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

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

entities List<Tuple>

Назначение: список распознанных сущностей. Каждый элемент списка содержит кортеж из трёх элементов: тип сущности (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"

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: преобразование символов строки в верхний регистр.

Arguments:

1. str - строка, которую необходимо преобразовать.

Returned value: строка все символы которой находятся в верхнем регистре.

$str = "СтРоКа"
$upper = str.upper($str) // $lower будет содержать "СТРОКА" 

str.ucfirst(str string) string

Purpose: преобразование первого символа строки в верхний регистр.

Arguments:

1. str - строка, первый символ которой необходимо преобразовать.

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

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

str.lcfirst(str string) string

Purpose: преобразование первого символа строки в нижний регистр.

Arguments:

1. str - строка, первый символ которой необходимо преобразовать.

Returned value: строка в которой первый символ записан в нижнем регистре.

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

str.letter(str string, index int) string

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

Arguments:

1. str - строка, символ которой требуется получить.
2. index - целое число определяющее позицию символа в строке начиная с 0. Если это число отрицательное то отсчёт начинается с конца строки.

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

$str = "Слово"
$firstLetter = str.letter($str, 0)  // Первая буква
$lastLetter = str.letter($str, -1)  // Последняя буква

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

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

Arguments:

1. str - строка, символ которой требуется получить.
2. index - целое число определяющее позицию символа с начала строки начиная с 0. При этом знак числа игнорируется. Значение по умолчанию 0 (первый символ).

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

$str = "Слово"
$firstLetter = str.first($str)      // Первая буква
$secondLetter = str.first($str, 1)  // Вторая буква

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

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

Arguments:

1. str - строка, символ которой требуется получить.
2. index - целое число определяющее позицию символа с конца строки начиная с 0. При этом знак числа игнорируется. Значение по умолчанию 0 (последний символ).

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

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

str.concat(str1 string, str2 string) string

Purpose: объединяет две строки в одну.

Arguments:

1. str1 - строка которая объединяется.
2. str2 - строка с которой объединяются.

Returned value: новая строка состоящая из первой строки справа от которой добавлена вторая строка.

$str1 = "один"
$str2 = "два"
$str = str.concat($str1, $str2) // $str будет содержать "одиндва" 

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

Purpose: возвращает подстроку строки str, начинающейся с offset символа по счету и длиной length символов.

Arguments:

1. str - исходная строка.
2. offset - если offset неотрицателен, возвращаемая подстрока начинается с позиции offset от начала строки, считая от нуля.
   Если offset отрицательный, возвращаемая подстрока начинается с позиции, отстоящей на offset символов от конца строки str.
   Если str меньше offset символов, будет возвращена пустая строка.
3. length - если length положительный, возвращаемая строка будет не длиннее length символов, начиная с параметра offset (в зависимости от длины string).
   Если length отрицательный, то будет отброшено указанное этим аргументом число символов с конца строки string (после того как будет вычислена стартовая позиция, если offset отрицателен). Если при этом позиция начала подстроки, определяемая аргументом offset, находится в отброшенной части строки или за ней, возвращается пустая строка. 
   Если параметр length задан и равен 0, будет возвращена пустая строка.
   Если параметр length опущен или nil, то будет возвращена подстрока, начинающаяся с позиции, указанной параметром offset и длящейся до конца строки.

Returned value: часть str или пустая строка.

$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: объединяет элементы коллекции (кортежа, списка или ассоциативного массива) в строку.

Arguments:

1. arr - коллекция элементов для объединения.
2. separator - разделитель элементов коллекции. По умолчанию равен пустой строке.

Returned value:  новая строка составленная из всех элементов коллекции отделённых между собой разделителем.

$str = str.join([1, 2, 3, 4, 5], "-")             // $str будет содержать "1-2-3-4-5"
$str = str.join(("a", "b", "c"))                  // $str будет содержать "abc"
$str = str.join({"a": "один", "b": "два"}, " + ") // $str будет содержать "один + два"
$str = str.join(["одно"], "/")                    // $str будет содержать "одно"
$str = str.join([], "/")                          // $str будет содержать ""

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

Purpose: разбивает строку на части использую separator в качестве разделителя.

Arguments:

1. str - строка для разделения.
2. separator - разделитель. Если равен пустой строке, то разбиение происходит посимвольно.
3. limit - необязательный параметр равный максимальному количеству частей на которые будет разбита строка. Если limit равен 0, то без ограничений. Если limit является положительным, возвращаемый список будет содержать максимум limit элементов, при этом последний элемент будет содержать остаток строки str. Если limit отрицателен, то будут возвращены все компоненты, кроме последних -limit.

   
   

Returned value:  список подстрок на которые была разбита строка.

$letters = str.split("абвгде")             // Получили список букв слова
$words = str.split("один два три", " ")    // Получили список слов
$words = str.split("один два три", " ", 1) // words содержит ["один", "два три"]

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

Purpose: ищет все вхождения подстроки в строке и заменяет их на заданное значение.

Arguments:

1. str - строка для преобразования.
2. search - подстрока которая ищется в исходной строке. 
3. replace - строка замены.

Returned value:  новая строка в которой все search заменены на replace.

$str = str.replace("мама мыла раму", "рам", "Даш") // $str содержит "мама мыла Дашу"

str.match(str string, pattern string) bool

Purpose: выполняет проверку данной строки регулярному выражению.

Arguments:

1. str - строка для сопоставления с регулярным выражением.
2. pattern - шаблон регулярного выражения. 

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

Примечание: в качестве регулярных выражений используется Perl совместимые регулярные выражения (PCRE). Ссылка на документацию и примеры регулярных выражений: PCRE Doc.

Онлайн редактор регулярных выражений: http://myregexp.com/

$isIntNumber = str.match("1.234", "/^[0-9]+$/") // $isIntNumber будет равен false
$isIntNumber = str.match("1234", "/^[0-9]+$/")  // $isIntNumber будет равен true

str.distance(str1 string, str2 string) number

Purpose: вычисляет степень сходства двух строк.

Arguments:

1. str1 - первая строка для сравнения.
2. str2 - вторая строка для сравнения. 

Returned value:  возвращает число от 0 до 1 включительно определяющее степень сходства двух строк. 1 - строки эквивалентны, 0 - строки абсолютно разные.

Примечание: функция фактически вычисляет расстояние Дамерау-Левенштейна.

$d = str.distance("", "abc")              // $d равен 0
$d = str.distance("Да", "да")             // $d равен 1
$d = str.distance("корыто", "открыто")    // $d равен 0.714
$d = str.distance("Да, верно", "таверна") // $d равен 0.625
$d = str.distance("жутко косые бананы", "жуй кокосы, ешь бананы") // $d равен 0.714 
$d = str.distance("сошел с ума от раны", "Пошел он в пусурманы")  // $d равен 0.45
$d = str.distance("ёж", "дезоксирибонуклеиновая кислота")         // $d равен 0.033

Функции хэширования

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

Purpose: вычисляет хэш строки согласно указанному алгоритму.

Arguments:

1. text - произвольная строка для хэширования.
2. algo - название алгоритма хэширования. По умолчанию используется алгоритм md5.
3. binary - когда установлено в true, выводит необработанные двоичные данные. При false выводит данные в шестнадцатеричной кодировке в нижнем регистре. По умолчания равен false.

Returned value: возвращает строку содержащую вычисленный хеш-код в шестнадцатеричной кодировке в нижнем регистре. Если binary задан как true, то возвращается хеш-код в виде бинарных данных. В случае ошибки (например, если указан недопустимый алгоритм хэширования) возвращает пустую строку.

Допустимые значения алгоритмов хэширования:

• 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

Примечание: если третий параметр true, то передавать возвращаемое функцией значение в качества сообщения бота или его части нельзя. Это приведёт к падению бота.

$hash = hash.of("Наглый коричневый лисёнок прыгает вокруг ленивой собаки.")                 // $hash будет содержать bff8b4bc8b5c1c1d5b3211dfb21d1e76
$hash = hash.of("Наглый коричневый лисёнок прыгает вокруг ленивой собаки.", "ripemd160")    // $hash будет содержать 8817ca339f7f902ad3fb456150a1bb9b4cb5dde9
$hash = hash.of("Наглый коричневый лисёнок прыгает вокруг ленивой собаки.", "sha256", true) // $hash будет содержать бинарную строку (содержащую неотображаемые символы)

Функции кодирования/декодирования

codec.base64Encode(str string) string

Purpose: кодирует заданную строку в base64.

Arguments:

1. str - произвольная строка для кодирования.

Returned value: возвращает строку закодированную в base64.

$encoded = codec.base64Encode("Привет!") // $encoded будет содержать строку "0J/RgNC40LLQtdGCIQ=="

codec.base64Decode(str string) ?string

Purpose: декодирует заданную в base64 строку.

Arguments:

1. str - строка закодированная в base64.

Returned value: возвращает раскодированную строку либо nil, если закодированная строка содержит символы не входящие в алфавит символов base64 кодировки.

$decoded = codec.base64Decode("0J/RgNC40LLQtdGCIQ==") // $decoded будет содержать строку "Привет!"
$failed = codec.base64Decode("Привет!")               // $failed будет равен nil

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

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

Purpose: складывает две даты, заданные в виде строки либо как число секунд.

• Если хотя бы один из аргументов функции число секунд, то это число будет прибавлено к числу секунд другой даты.
• Если обе даты заданы строкой, то результат определяется по формуле d1 + abs(secondsOf(d1) - secondsOf(d2)), где abs - модуль числа (положительное значение), secondsOf - это дата представленная как количество секунд прошедших с начала 1970 года (даты до этого времени представлены отрицательным значением). 

Arguments:

1. d1 - строка представляющая собой дату в одном из допустимых форматов или целое число соответствующее количеству секунд.
2. d2 - аналогично первому аргументу.

Returned value: возвращает новую дату и время в виде строки.

$d = dt.add("2022-01-01 12:30:00", 59)                    // $d содержит строку "2022-01-01 12:30:59" 
$d = dt.add(3600, "2022-01-01 12:30:00")                  // $d содержит строку "2022-01-01 13:30:00"
$d = dt.add("2022-01-01 00:00:00", "2022-01-02 00:00:00") // $d содержит строку "2022-01-03 00:00:00"

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

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

• Если обе даты заданы количеством секунд, то функция вернёт их разность в виде числа секунд.
• Если обе даты заданы строкой, то будет возвращено целое число равное разности между датами в секундах.
• Если первый аргумент задан строкой даты, а второй числом секунд, то результатом будет новая дата равная разности даты и числа секунд.
• Если второй аргумент задан строкой даты, а первый числом секунд, то результатом будет ошибка.

Arguments:

1. d1 - строка представляющая собой дату в одном из допустимых форматов или целое число соответствующее количеству секунд.
2. d2 - аналогично первому аргументу.

Returned value: возвращает новую дату и время в виде строки либо число секунд - разность дат.

$d = dt.sub(100, 50)                                      // $d содержит 50
$d = dt.sub("2022-01-01 12:30:00", 3600)                  // $d содержит строку "2022-01-01 11:30:00"
$d = dt.sub(3600, "2022-01-01 12:30:00")                  // Такой вызов недопустим и приведёт к остановке программы
$d = dt.sub("2022-01-01 01:00:00", "2022-01-01 00:00:00") // $d содержит 3600

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

Purpose: форматирует дату согласно заданному формату.

Arguments:

• dt - дата заданная строкой или числом секунд.
• format - строка определяющая формат даты и времени.

Returned value: строка даты в заданном формате.

Допустимые параметры форматирования:

Примечание: если строка формата содержит символы совпадающие с вышеперечисленными, но не являющиеся параметрами форматирования, то их следует экранировать с помощью символа обратного слэша "\".

$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: возвращает ближайшую будущую к текущей дату по заданному дню.

Arguments:

1. day - число дней для определения ближайшей в будущем даты.

Returned value: возвращает ближайшую к day дату.

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

date.nearPast(day int) string

Purpose: возвращает ближайшую прошлую к текущей дату по заданному дню.

Аргументы:

1. day - число дней для определения ближайшей в прошлом даты.

Returned value: возвращает ближайшую к day дату.

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

date.future(day int) string

Purpose: возвращает дату соответствующую указанному дню в следующем месяце.

Arguments:

1. day - число дней для определения даты в будущем.

Returned value: дата в будущем.

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

date.past(day int) string

Purpose: возвращает дату соответствующую указанному дню в прошлом месяце.

Аргументы:

1. day - число дней для определения даты в прошлом.

Returned value: дата в прошлом.

// Допустим сейчас 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: возвращает ближайшее будущее к текущему время по заданному количеству минут.

Arguments:

1. minute - число минут для определения ближайшего в будущем времени.

Returned value: возвращает ближайшее к 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: возвращает ближайшее прошлое к текущему время по заданному количеству минут.

Arguments:

1. minute - число минут для определения ближайшего в прошлом времени.

Returned value: возвращает ближайшее к minute время.

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

time.future(minute int) string

Purpose: возвращает время соответствующее указанному числу минут в следующем часе.

Arguments:

1. minute - число минут для определения времени в будущем.

Returned value: время в будущем.

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

time.past(minute int) string

Purpose: возвращает время соответствующее указанному числу минут в прошедшем часе.

Arguments:

1. minute - число минут для определения времени в прошлом.

Returned value: время в прошлом.

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

Функции по работе с очередью сообщений пользователя

queue.size() int

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

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

Returned value: число сообщений пользователя.

$messageCount = queue.size() // $messageCount содержит число сообщений пользователя за всё время диалога

queue.last() ?UserMessage

Purpose: возвращает последнее сообщение пользователя либо nil, если очередь сообщений пуста.

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

Returned value: объект UserMessage или nil.

$lastMessage = queue.last() // $lastMessage содержит последнее на данный момент сообщение пользователя

queue.first() ?UserMessage

Purpose: возвращает первое сообщение пользователя либо nil, если очередь сообщений пуста.

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

Returned value: объект UserMessage или nil.

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

queue.nth(index int) ?UserMessage

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

Arguments:

1. index - порядковый номер сообщения пользователя.

Returned value: объект UserMessage или nil.

$message = queue.nth(1) // $message содержит первое сообщение пользователя
$message = queue.nth(5) // $message содержит пятое сообщение пользователя

queue.lastNth(index int) ?UserMessage

Purpose: возвращает сообщение пользователя по его порядковому номеру считая с конца очереди. Последнее сообщение соответствует порядковому номеру 1.

Arguments:

1. index - порядковый номер сообщения пользователя считая с конца очереди.

Returned value: объект UserMessage или nil.

$message = queue.lastNth(1) // $message содержит последнее сообщение пользователя
$message = queue.lastNth(5) // $message содержит пятое с конца очереди сообщение пользователя

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

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

Purpose: сохраняет факт в базе фактов.

Arguments:

1. context - строка определяющая контекс в рамках которого существует факт.
2. factName - строка определяющая название факта.
3. factValue - любое значение определяющее содержимое факта.
4. botId - идентификатор бота. По умолчанию не задан.
5. clientId - идентификатор клиента, По умолчанию не задан.

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

fact.save("место", "город", "Екатеринбург")                    // Факт доступный всем ботам компании       
fact.save("место", "город", "Екатеринбург", nil, @clientId)    // Факт с привязкой к клиенту
fact.save("место", "город", "Екатеринбург", @botId)            // Факт с привязкой к боту
fact.save("место", "город", "Екатеринбург", @botId, @clientId) // Факт с привязкой к боту и клиенту

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

Purpose:  извлекает факт из базы фактов.

Arguments:

1. context - строка определяющая контекс в рамках которого существует факт.
2. factName - строка определяющая название факта.
3. botId - идентификатор бота. По умолчанию не задан.
4. clientId - идентификатор клиента, По умолчанию не задан.

Returned value: содержимое факта.

fact.save("место", "город", "Екатеринбург", @botId, @clientId) // Сохраняет факт с привязкой к боту и клиенту
$city = fact.load("место", "город", @botId, @clientId)         // Загружаем факт в переменную. $city содержит "Екатеринбург"

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

Purpose:  удаляет факт из базы фактов.

Arguments:

1. context - строка определяющая контекс в рамках которого существует факт.
2. factName - строка определяющая название факта.
3. botId - идентификатор бота. По умолчанию не задан.
4. clientId - идентификатор клиента, По умолчанию не задан.

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

fact.save("место", "город", "Екатеринбург", @botId, @clientId) // Сохраняет факт с привязкой к боту и клиенту
$city = fact.load("место", "город", @botId, @clientId)         // Загружаем факт в переменную. $city содержит "Екатеринбург"
fact.delete("место", "город", @botId, @clientId)               // Удаляем факт.
$city = fact.load("место", "город", @botId, @clientId)         // Пытаемся загрузить удалённый факт. Теперь $city содержит nil.

fact.query() FactQuery

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

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

Returned value: объект FactQuery.

// Добавили пару фактов в базу
fact.save("место", "страна", "Россия")
fact.save("место", "город", "Екатеринбург")

// Загрузили в $places список мест отсортированных по имени факта в порядке убывания:
// [{"name": "город", "value": "Россия"}, {"name": "страна", "value": "Екатеринбург"}]
$places = fact.query().
    select("name,value").
    where("context", "=", "место").
    sortBy("-name").
    rows()

fact.cond() FactQueryCondition

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

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

Returned value: объект FactQueryCondition.

// Добавили факты в базу
fact.save("города", "екатеринбург", "Екатеринбург")
fact.save("города", "москва", "Москва")
fact.save("города", "санкт-петербург", "Санкт-Петербург")
fact.save("города", "новосибирск", "Новосибирск")

// Найдём один город начинающийся с буквы "м" или с буквы "т" и не равный городам "Екатеринбург" и "Новосибирск"
$city = fact.query().
    select("value").
    where("context", "=", "города").
    where(fact.cond().
        where("name", "^@", "м").
        orWhere("name", "^@", "т")).
    where("name", "not in", ("екатеринбург", "новосибирск")).
    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) Sentence

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

Arguments:

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

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: отправляет сообщение в демо версию нейросети RuGTP-3 и возвращает её ответ.

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"