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

del(varName string)

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

Аргументы:

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

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

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

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

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.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.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 содержит ["один", "два три"]

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

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()

Объект 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.