QuBot: Справочник действий

Действия

Имена всех встроенных действий начинаются с префикса ACTION_. Действие, кроме обязательно поля action: ACTION_NAME, может иметь входные аргументы (некоторые из них обязательны, а некоторые - нет). Кроме этого action может иметь раздел result, где перечисляются возможные результаты его работы, в которых указывается, что необходимо сделать (задать слоты, вывести текст, кнопки и т.п.)

Действия со списками

✒ ACTION_LIST_LENGTH - в аргумент slots записывает длину списка list. Аргумент slots - это объект, состоящий из одного ключа - имени слота типа int, в который помещается длина списка: 

STATE:
  - action: ACTION_LIST_LENGTH     
    list:   ORDER  
    slots:  { LEN_ORDER }          # В слоте LEN_ORDER будет длина списка

Длину списка можно также получить в выражениях следуюшим образом: "{len($ORDER)} элементов".

✒ ACTION_LIST_ADD_ITEM - добавить в список list новый элемент item (оба аргумента обязательные): 

STATE:
  - action: ACTION_LIST_ADD_ITEM
    list:   ORDER                                          # имя слота, содержащего список
    item:   { _ITEM: $ITEM, _AMOUNT: $AMOUNT, _PRICE: $PRICE } # элемент списка объект
    
  - action: ACTION_LIST_ADD_ITEM
    list:   ITEMS                                          # имя слота, содержащего список
    item:   "Молоко"                                       # элемент списка - строка
Если элементами списка являются объекты (первый пример), то ключи item - это ключи элемента списка, а значения - их значения. Имена ключей могут быть любыми и пересекаться с именами слотов, но лучше этого не делать, используя для ключей элемента, например, символ подчёркивания. Если в данный момент слоты имеют значения: ITEM: "Вино", AMOUNT: 5, PRICE: 200, то в список слота ORDER добавится элемент: 
{"_ITEM": "Вино", "_AMOUNT": 5, "_PRICE": 200}

Есть ещё два необязательных аргумента equal и total:

Например, пусть необходимо в список покупок добавить _AMOUNT единиц товара ITEM с ценой PRICE. Но если этот товар уже в списке и цена PRICE не отличается от добавляемой, то вместо добавления, произойдет увеличение значения ключа из аргумента total: 

STATE:
  - action: ACTION_LIST_ADD_ITEM
    list:   ORDER
    item:   { _ITEM: "Молоко", _AMOUNT: 1, _PRICE: 10 }            
    equal:  { _ITEM, _PRICE   }
    total:  { _AMOUNT }

✒ ACTION_LIST_CLEAR - очистит список list. В обязательном аргументе list значением выступает имя слота, который содержит список: 

STATE:
  - action: ACTION_LIST_CLEAR     
    list:   ORDER

Можно очистить не все элементы списка, а только те, которые удовлетворяют некоторым условиям. Для этого служат необязательные аргументы bool и equal. Например, следующий вызов удалит все элементы (которые являются объектами), если ключ _PRICE элемента меньше 10: 

STATE:
  - action: ACTION_LIST_CLEAR     
    list:   ORDER 
    bool:   $_PRICE < 10
Аналогично можно удалить все элементы по значению их ключей: 
STATE:
  - action: ACTION_LIST_CLEAR     
    list:   ORDER 
    equal:  { _PRICE: 10, _COUNT: 3 }
Удалятся все элементы в которых _PRICE == 10 и _COUNT == 3. Аргументы bool и equal можно использовать совместно.

✒ ACTION_LIST_LOAD - загрузить список list из файла с именем file (оба аргумента обязательные): 

STATE:
  - action: ACTION_LIST_LOAD     
    list:   ORDER                # слот типа list в который помещается файл
    file:   "menu.csv"           # путь к файлу относительно корня проекта
Допустимы yml-файлы (состоящие из списка объектов) и csv-файлы (таблицы) в которых первой строкой должны идти названия ключей, разделённые точкой с запятой (;). Следующие строчки - это значения элементов списка, соответствующие ключам из первой строки (они тоже разделяются точкой с запятой).

✒ ACTION_LIST_REMOVE_ITEM - удалить из списка list элемент или уменьшить значения его ключей. Возможно два несовместные способа удаления. Если задан аргумент index, то удаляется элемент под этим номером (нумерация начинается с 1): 

STATE:
  - action:   ACTION_LIST_REMOVE_ITEM
    list:     ORDER               # слот типа list в котором удаляем
    index:    3                   # удалить элемент под номером 3

Во втором способе, вместо index передаются два аргумента equal и dec. В equal находятся ключи и значения, которые должны совпасть с аналогичными в элементах списка. В аргумента dec перечисляются ключи элементов списка, и значение на которое их необходимо уменьшить. Если результат вычитания меньше или равный нулю, элемент удаляется: 

STATE:
  - action:   ACTION_LIST_REMOVE_ITEM
    list:     ORDER
    equal:    { _ITEM: "Wine"} # если в элементе ест ключ _ITEM со значением  "Wine"
    dec:      { _AMOUNT: 2   } # уменьшить _AMOUNT на 2, если он стал 0 - удалить элемент.
Если аргумента dec нет, то при совпадении "фильтра" equal, данный элемент сразу удаляется.

✒ ACTION_LIST_SHOW - вывести элементы списка. Аргументы списка:

Возвращаемые значения: 
CUISINE_MENU_STATE:                         
  - action: ACTION_LIST_SHOW
    list:   MENU_LIST
    page:   PAGE
    count:  1        
    result:        
        empty:
          - text:   "Вы пока ничего не заказали"
        item:              
          - text:    $_NAME
          - image:   $_IMAGE
            caption: $_DESCR
        tail:
          - text:    "Вы заказали на $TOT_AMOUNT."
В качестве значения $_NAME может быть либо ключи элемента списка, либо глобальные слоты из раздела slots. При подстановке значения, сначала проверяются ключи элемента, а если таких ключей нет, идёт поиск в слотах. Если ни где такой ключ не найден, будет подставлено значение None.

У действия могут быть также необязательные аргументы:

Примеры см. в действии ACTION_LIST_CLEAR.

✒ ACTION_LIST_TOTAL - вычисляет сумму значений по элементам списка. Имеет следующие аргументы:

Пример: 
- action: ACTION_LIST_TOTAL
  list:   ORDER
  total: { TOTAL_SUM: $_AMOUNT * $_PRICE }
В слот TOTAL_SUM будет записана сумма произведений значений ключей _AMOUNT и _PRICE по всем элементам списка. При помощи логических условий equal и/или bool можно фильтровать только нужные элементы списка.

✒ ACTION_LIST_EXTRACT - извлечь из списка src в список des элементы, удовлетворяющие условиям equal и/или bool. В необязательный аргумент slots будет записана длина результирующего списка: 

- action: ACTION_LIST_EXTRACT
  src:    LIST1
  des:    LIST2
  bool:   $_PRICE > 10
  slots:  { LIST2_COUNT }

✒ ACTION_LIST_GET_ITEM - получить элемент списка.

Действие работет в двух не пересекающихся режимах: либо по номеру index, либо по условиям equal и/или bool: 
- action: ACTION_LIST_GET_ITEM
  list:   ORDER
  index:  5
  slots:  { PRICE: $_PRICE, AMOUNT: $_AMOUNT }
Можно возвращать целиком элемент списка в объект типа dict (см. примеры в Справочнике слотов).

✒ ACTION_LIST_SET_ITEM - установить значение элемента списка. 

- action: ACTION_LIST_SET_ITEM
  list:   ORDER
  index:  1
  slots: { _AMOUNT: $AMOUNT }

✒ ACTION_LIST_EMPTY - проверяет является ли список list пустым. В блоке return возвращает два значения: true (пустой список) false (если список пустой): 

- action: ACTION_LIST_EMPTY     
  list:   ORDER  
  result:
      true:
        - text: Пустой список
      false:
        - text: Не пустой список
Под этими значениями может стоять список с любыми объектами состояния. Пустоту списка можно также проверить в условных объектах if как len($ORDER) == 0.

Прочие действия

✒ ACTION_MESSAGE_SEND - посылка сообщений между двумя ботами или пользователями внутри обного бота. Детали в "Общение ботов".