Qubot Script/ru

Qubot Script

Qubot Script - это язык программирования, используемый для выполнения логических и математических операций при решении задач бота

Слоты

Слот - это переменная, значение которой доступно во всех состояниях бота. Также значение слота сохраняется, если бота закрыли и продолжили с ним работать через время.

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

a = 7

объявляет слот с именем a и присваивает ему значение 7

Локальные переменные

В отличие от слотов локальные переменные сохраняются только внутри скрипта, где они объявлены.
Объявление происходит путем добавления перед именем служебного слова local:

local b = 8    // локальная переменная

Если локальная переменная объявлена внутри фигурных скобок {}, то и ее значение доступно только там:

local b = 8    // локальная переменная текущего скрипта

if (b == 8)
{
   local c = 9 // локальная переменная блока оператора 'if'
   print(c)    // выведет 9
}

print(b)       // выведет 8 
print(c)       // выдаст ошибку, т.к. тут уже переменная 'с' недоступна

Типы переменных

sInt = 7                             // целочисленный
sFloat = 7.3                         // вещественный
sStr = "hello"                       // строковый
sArr = [7, 7.3, "hello", sStr]       // массив
sDic = { n: 1, s: "Wine"  }          // словарь
sBool = true                         // бинарный
sRegExp = /[abc]/                    // регулярное выражение
sNone = none                         // неопределенное значение

Логические операции

• and - логическое ‘И’
• or - логическое ‘ИЛИ’
• not - отрицание ‘НЕТ’

Например:

a = true
b = false
c = true
res = not((a and b) or c)

Арифметические операции

• + - сложение
• - - вычитание
• * - умножение
• / - деление

Например:

res = 2+3-4*5+(1.5-0.2/2)

Комментарии

Комментарии используются для документирования фрагментов скрипта. Могут быть многострочыми и однострочными:

/*
Пример
    многострочного
        комментария
*/

a = 2253 // пример однострочного комментария

Также разрешается и питоновский стиль комментария:

a = 2253 # пример однострочного комментария

Работа со словарем (объектом)

Объявление словаря:

dic = { n: 1, s: "Wine"  }

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

a = dic.n             // доступ к полю с именем "n" через точку  
a = dic["n"]          // доступ к полю с именем "n" через оператор доступа
dic["food"] = "milk"  // добавление в словарь пары ключ-значение

Работа с массивами

Объявление массива:

arr = [1,2,3]         // создает массив с тремя элементами со значениями 1,2,3

Доступ к элементам массива:

first  = arr[0]       // получить первый элемент массива
last   = arr[-1]      // получить последний элемент массива
last   = arr[-2]      // получить предпоследний элемент массива
arr[0] = 7            // изменить значение первого элемента

Функции работы с массивом:

push(val1,val2...) - добавить в конец массива элементы со значениями val1, val2...

arr.push(4) // добавить значение '4' в конец массива

unshift(val1,val2...) - добавить в начало массива элементы со значениями val1, val2...

arr.unshift(0) // добавить значение '0' в начало

pop() - удалить последний элемент массива и вернуть его значение

shift() - удалить первый элемент массива и вернуть его значение

slice(start,end) - возвращает часть массива начиная с позиции start и если указана переменная end, то до нее не включая

splice(start, deleteCount) - удаляет deleteCount элементов начиная с позиции start

clear() - очистить массив

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

find(EXPR) - ищет элементы массива, удовлетворяющие условию EXPR. Найденные элементы возвращаются в виде массива
Например:

arr = [                            // массив из трех объектов с продуктами
  {title: "Wine", price: 120},
  {title: "Cheese", price: 100},
  {title: "Cola", price: 40},
] 

local res = arr.find(price > 80)   // найти все объекты у которых поле 'price' больше 80 и вернуть их в массиве
print('найдено $res.length:')      // выведет количество найденных объектов
print(res)                         // выведет объекты, удовлетворяющие условию

total(EXPR) - применить выражение EXPR к каждому элементу массива и суммировать все значения
Например посчитаем сумму товаров в корзине:

arr = [                                 // массив из трех объектов с продуктами
  {title: "Wine", price: 120, amount: 3},
  {title: "Pizza", price: 100, amount: 2},
  {title: "Cola", price: 40, amount: 3},
] 

local res = arr.total(price * amount)   // для каждого элемента массива умножаем цену на количество и складываем результат
print("К оплате: $res грн.")            // выведет сумму товаров: "К оплате: 680 грн."

count(EXPR) - найти количество элементов массива для которых истинно выражение EXPR

arr = [                                 // массив из трех объектов с продуктами
  {title: "Wine", price: 120, amount: 3},
  {title: "Pizza", price: 100, amount: 2},
  {title: "Cola", price: 40, amount: 3},
] 

local res = arr.count(price < 100)                            // для каждого элемента массива умножаем цену на количество и складываем результат
print("Количество товаров, дешевле 100 грн: $res")            // выведет количество товаров: "Количество товаров, дешевле 100 грн: 1"

sort(KEY) - отсортировать массив

Поддерживаются только массивы, в которых все значения одного типа: число или строка для sort() и словарь для sort(key)

list = [1, 3, 2] // массив чисел
str  = ["a", "hi", "banana"] // массив строк
arr  = [         // массив из словарей с продуктами
  {title: "Wine", price: 120, amount: 3},
  {title: "Pizza", price: 100, amount: 2},
] 

list.sort()       // отсортировать массив по возрастанию
 str.sort()        // отсортировать массив по возрастанию
 arr.sort(price)   // отсортировать массив объектов по ключу 'price'
// TODO

reverse() - перевернуть массив

list = [1, 3, 2]  // массив

list.reverse()    // [2, 3, 1]

Работа со строками

Объявление строковых слотов:

str = "hello"           // используя двойные кавычки 
str = 'hello'           // используя одинарные кавычки

Операции со строками:

base = 'http://imgs/'
url = base + 'img1.png' // сложение строк

Подстановка слотов в строки:

a = 5
str = "a = $a"          // вместо $a будет подставлено значение слота a
print(str)              // выведет: "a = 5"

Вставка выражений в строки:

Выражения можно вставлять в строки, обрамляя их фигурными скобками:

str = "2 + 3 = {2+3}"   // вычислит выражение и вставит результат в строку
print(str)              // выведет: "2 + 3 = 5"

Экранирование спецсимволов '$','{','}' происходит путем добавления наклонной черты '\'

str = "price: 4.99\$ \{sale\}"   // вычислит выражение и вставит результат в строку
print(str)                       // выведет: "price: 4.99$ {sale}"

Функции работы со строками:

length - получить длинну строки

str = "hello"
len = str.length           // вернет 5 - число символов строки "hello"

substring(start,end) - получить подстроку начиная с позиции start и до позиции end не включая

str = "http://server/im.png"
substr = str.substring(7,13)  // вернет строку "server"

search(pattern) - найти позицию первого вхождения pattern, иначе вернуть -1. Аргумент pattern может быть как строкой так и регулярным выражением:

str = "apple orange juice"
res = str.search('orange')          // вернет позицию строки 'orange': 6
res = str.search(/(orange|juice)/)  // вернет позицию строки 'orange' или 'juice'
res = str.search('pizza')           // не найдет 'pizza' и вернет -1

Условный оператор

Оператор if используется, если необходимо ветвление логики в зависимости от условия

a = 9
if (a > 7) 
{
    res = 'a more than 7'
}
else
{
    res = 'a less or equal 7'
}

В данном примере проверяется условие a > 7 и если оно истинно, то выполняется первый блок скрипта, окруженный фигурными скобками, иначе выполняется блок после служебного слова else

Цикл while

Оператор цикла проверяет условие и пока оно истинно, выполняет код окруженный фигурными скобками

a = 7
while (a > 0) 
{
    a = a - 1
}

В данном примере скрипт a = a - 1 будет выполнятся до тех пор пока значение слота a не станет равным нулю

Итератор for

Итератор используется для перебора всех значений массива, либо ключей из словаря

arr = [3,2,1]
for(val in arr)
{
    print(val)
}
output:
3
2
1

В данном примере цикл последовательно перебирает значения массива и заносит их во временную переменную val соответственно для каждого элемента массива выполняется окруженный фигурными скобками скрипт print(val) выводящий значение в отладочное окно

Иногда удобно в цикле иметь и индекс массива, для этого перед переменной значения добавляем имя переменной индекса:

arr = [3,2,1]
for(i, val in arr)
{
    print("$i: $val")
}
output:
0: 3
1: 2
2: 1

Для перебора ключей и значений словаря используется аналогичная конструкция:

arr = {pizza: 100, milk: 20, wine: 120}
for(key, val in arr)
{
    print("$key: $val")
}
output:
pizza: 100
milk: 20
wine: 120

Оператор выбора switch

Конструкция switch заменяет собой сразу несколько if. Она представляет собой более наглядный способ сравнить выражение сразу с несколькими вариантами. Имеет один или более блок case и необязательный блок default.

a = 'one'
switch(a)
{
   case 'one': print('one'); break;
   case 'two': print('two'); break;
   default: print('def')
}

Переменная проверяется на строгое соответствие значению справа от case и если оно совпадает, то выполняется код до тех пор пока не встретится оператор break

Если ни одно из case не подошло, выполняется код справа от default

Оператор in

Оператор in проверяет есть ли значение в массиве либо является ключём в словаре.

sArr = [7, 7.3, "hello"]             // массив
print("hello" in sArr)               // вернет true, т.к. значение "hello" присутствует в массиве sArr 
sDic = { price: 100, food: "Wine"}   // словарь
print("food" in sDic)                // вернет true, т.к. ключ "food" присутствует в словаре sDic

Переменная проверяется на строгое соответствие значению справа от case и если оно совпадает, то выполняется код до тех пор пока не встретится оператор break

Если ни одно из case не подошло, выполняется код справа от default

Оператор button

button(caption){ SCRIPT }
Данный оператор добавляет в интерфейс кнопку с текстом caption в текущее сообщение. После нажатия на кнопку выполняется логика SCRIPT. Если caption - объект, то он должен состоять из двухбуквенных ключей (идентификаторов языка: en, ru,…) со строковыми значения на этих языках.

button('click me')      // текст в кнопке
{
    // скрипт, который выполнится после нажатия 
    print('button was clicked!')
    step('STATE_AFTER_CLICK')
}

При нажатии на кнопку скрипт будет выполнен в контексте локальных переменных на момент добавления данной кнопки, а также в контексте значений слотов на момент нажатия на кнопку!

Функции перехода

run(state) - выполнить логику шага state

step(state) - установка шага перехода по умолчанию в значение state

goto(state) - мгновенный переход в шаг state

Функции работы с контентом

text(obj) - вывести в текущее сообщение текст. Если obj - это строка, то она выводится независимо от текущего языка. Если obj - объект, то он должен состоять из двухбуквенных ключей (идентификаторов языка: en, ru,…) со строковыми значения на этих языках.

text("Hi world!")     
text({ en: "Hi world!", ru: "Привет мир!", es: "¡Hola mundo!"})

images() - создать новую строку картинок. Каждый последующий вызов image будет добавляться в эту строку, пока снова не будет вызван images().

URL = "https://qudata.com/qubot/im/"  
images()     
image(URL + "owl_a.png")     
image(URL + "owl_b.png")

image(url, width) - вывести в текущее сообщение картинку. Если url - это строка, то он используется не зависимо от текущего языка. Если url - объект, то он должен состоять из двухбуквенных ключей (идентификаторов языка: en, ru,…) со строковыми значения на этих языках.. Необязательный параметр width указывает насколько в процентах нужно сжать изображение

URL = "https://qudata.com/qubot/im/"     
image(URL + "owl_a.png")  
image({ en: URL + "en.png", ru: URL + "ru.png"})

buttons() - создать новую строку кнопок. Каждый последующий вызов button будет добавляться в эту строку, пока снова не будет вызван buttons().

get_check() - получить массив значений кнопок типа check (1 - нажата, 0 - отжата)

set_check(list) - задать значения кнопок типа check из массива list.

CHECK = [0,1,0]
set_check(CHECK)

get_radio() - получить массив значений кнопок типа radio (1 - нажата, 0 - отжата). Единица будет одна.

set_radio(list) - задать значения кнопок типа radio из массива list.

Отладочные функции

print(args) - вывод информации в окно отладки

Округление

floor(val) - округление чисел в меньшую сторону:

floor(5.8)    //  5
floor(-6.1)   // -7

trunc(val) - отбрасывание дробной части:

trunc(5.51)   //  5
trunc(-6.99)  // -6

ceil(val) - округление чисел в большую сторону:

ceil(5.15)    // 6

round(val, num) - округление val до num чисел после запятой:

round(3.14159265, 2)  // 3.14

Случайные числа

randint(min,max) - возвращает целое случайное число в диапазоне [min,max].

random() - возвращает случайное вещественное число в диапазоне [0,1].

Дата и время

date(format) - возвращает текущую дату и время в указанном формате. По умолчанию аргумент format принимает значение: %d/%m/%Y %H:%M:%S

Поддерживаемые коды форматирования:

• %y - год без столетия ('22')
• %Y - год ('2022')
• %m - месяц
• %d - день
• %H - часы
• %M - минуты
• %S - секунды

Например:

date()  // 17/05/2022 18:16:31 т.е. сейчас
date('%Y.%m.%d %H:%M:%S')  // 2022.05.17 18:16:31

Сохранение данных

save(storage, params...) - сохранить данные в таблицу.

Где params - это:

• для QuData.com, WordPress:
  • data - данные для сохранения

• для Google Sheets:
  • data - данные для сохранения
  • link - ссылка на гугл таблицу
  • filter - фильтр для изменения данных. По умолчанию равен null.

Например:

save('qudata', {field: 'val'})
save('google_sheets', {field: 'val'}, 'https://....com')
save('google_sheets', {field: 'val'}, 'https://....com', {'name':'Dmitry'})

Загрузка данных

load(storage, params...) - загрузить данные из таблицы. Для загрузки файлов поддерживаются форматы .yml и .csv(с разделителем ;(точка с запятой))

Где params - это:

• для Google Sheets:
  • link - ссылка на гугл таблицу
  • filter - фильтр для выборки данных. По умолчанию равен null.

• для Google Drive:
  • link - ссылка на файл

• для Dropbox: - Должен быть настроен канал!
  • path - путь к файлу на dropbox

Например:

result = load('google_sheets', 'https://....com')
result = load('google_sheets', 'https://....com', {'name':'Dmitry'})
result = load('google_drive', 'https://....com')
result = load('dropbox', '/folder_name/file_name.yml')

Подключение к оператору

operator(service, params...) - работа с онлайн чатом.

Где params - это:

• для LiveChat
  • state - состояние чата (start - отправить первое сообщение, wait - начать общение, close - закрыть)
  • name - имя клиента. Только для состояния state.
  • message - сообщение. Только для состояния state.

Например:

operator('livechat', 'start', 'Adam', 'Hi, operator!')
operator('livechat', 'wait')
operator('livechat', 'close')

Отправить событие

event(name, target) - Отправить в аналитику событие. Где:

• name - название события.
• target - является ли событие важным. По умолчанию false.

Например:

event('test')
event('test', true)