upd

Author: GyverLibs

docs/4.updates.md

@@ -56,6 +56,12 @@ void update(fb::Update& u) {
 
 > В примере с хэшем строка, указанная в `SH`, не существует в программе: вместо этого компилятор подставляет её хэш (число). А в `switch` мы подаём хэш пришедшей строки. Это позволяет максимально быстро, оптимально и очень удобно сравнивать строки в сценариях, когда приходящий текст может иметь известный набор значений. В данном случае - обработка query, очень типовая задача (определение кнопки клавиатуры, на которую нажал юзер).
 
+Удобного получения хэша сообщения с кириллицей не предусмотрено, можно получить его так:
+
+```cpp
+size_t hash = SH(u.message().text().decodeUnicode().c_str());   // раскодировать и передать в хэш-функцию
+```
+
 ### Личка с админом
 Телеграм бот - публичная штука, любой пользователь может найти вашего бота в поиске и взаимодействовать с ним. Чтобы ограничить круг лиц (админов), которые могут работать с ботом (или иметь дополнительные функции), достаточно вручную фильтровать обновления по id юзера. Несколько способов:
 ```cpp
@@ -94,6 +100,7 @@ void update(fb::Update& u) {
 
 ### Переполнение стека
 При создании больших программ с большим количеством кода внутри обработчика обновлений на esp8266 можно столкнуться с исключением (перезагрузка МК) по причине `core panic` или `stack smashed`, это происходит по причине переполнения стека памяти (на esp32 он выделен в два раза больше и получить это исключение практически невозможно). Проблема особенно хорошо проявляется при скачивании файлов внутри обработчика обновлений и наличии большого количества другого кода. Для избежания случайных перезагрузок рекомендуется разделять обработчик на несколько функций, это также позволит лучше структурировать программу и разделять на файлы/блоки:
+
 ```cpp
 // обработка сообщений
 void uMessage(fb::Update& u) {
@@ -119,51 +126,125 @@ void setup() {
 }
 ```
 
+Также можно разбить функцию разбора обновлений на лямбды:
+
+```cpp
+void update(fb::Update& u) {
+    [&](){
+        // блок 1
+    }();
+
+    [&](){
+        // блок 2
+    }();
+}
+```
+
+Или использовать встроенный макрос:
+
+```cpp
+void update(fb::Update& u) {
+    FB_SUB_BEGIN
+        // блок 1
+        
+    FB_SUB_NEXT
+        // блок 2
+
+    FB_SUB_NEXT
+        // блок 3
+
+    FB_SUB_END
+}
+```
+
 ## Разбор вручную
 Для работы напрямую с API Telegram вам понадобится [официальная документация](https://core.telegram.org/bots/api).
 
-Класс `Update`, а также все вложенные классы (`User`, `Message`...) имеют доступ к `gson::Entry` пакета (документация [здесь](https://github.com/GyverLibs/GSON?tab=readme-ov-file#gsonentry)), который представляет собой распарсенный JSON пакет с хэшированными ключами. FastBot2 в свою очередь хранит хэши всех команд API Telegram (имеют префикс `tg_apih`). Поэтому для получения доступа ко всему содержимому нужно обратиться к объекту через квадратные скобки с хэшем. Например, для получения текста сообщения код будет такой:
+Класс `Update`, а также все вложенные классы (`User`, `Message`...) имеют доступ к `gson::Entry` пакета (документация [здесь](https://github.com/GyverLibs/GSON?tab=readme-ov-file#gsonentry)), который представляет собой распарсенный JSON пакет с хэшированными ключами. FastBot2 в свою очередь хранит хэши всех команд API Telegram (имеют префикс `tg_apih`).
+
+Объект класса `Update` является JSON объектом, который содержит непосредственно данные обновления. То есть для апдейта типа `"message"` это будет его содержимое, например (ответ сервера Telegram):
+
+```json
+{
+  "ok": true,
+  "result": [
+    {
+      "update_id": 1234653458,
+      "message": {  <- вот это Update
+        "message_id": 178,
+        "from": {
+        },
+        "chat": {
+        },
+        "text": "123321"
+      }
+    }
+  ]
+}
+```
+
+Для получения доступа к содержимому нужно обратиться к объекту через квадратные скобки с хэшем. Например, для получения текста сообщения код будет такой:
+
 ```cpp
 void update(fb::Update& u) {
-    Serial.println(u[tg_apih::message][tg_apih::text]);
+    Serial.println(u[tg_apih::text]);
     // "изнутри" этот код аналогичен u.message().text()
 }
 ```
 
+Тип текущего обновления парсится библиотекой, его можно разобрать так:
+
+```cpp
+void update(fb::Update& u) {
+    switch (u.type()) {
+        case fb::Update::Type::Message:
+            break;
+            
+        case fb::Update::Type::ChannelPost:
+            break;
+        
+        // и так далее
+    }
+}
+```
+
 Для проверки наличия в текущем обновлении или вложенном объекте нужно информации нужно использовать `has`, чтобы обезопасить программу от чтения несуществующих данных:
+
 ```cpp
 void update(fb::Update& u) {
-    // если обновление содержит сообщение
-    if (u.has[tg_apih::message]) {
+    // если обновление содержит текст
+    if (u.has[tg_apih::text]) {
         // то вывести текст сообщения
-        Serial.println(u[tg_apih::message][tg_apih::text]);
+        Serial.println(u[tg_apih::text]);
     }
-    // по сути это аналог встроенного u.isMessage()
 }
 ```
 
 Также в целях отладки можно вывести содержимое любого JSON элемента с форматированием:
+
 ```cpp
 void update(fb::Update& u) {
-    u[tg_apih::message].stringify(Serial);
+    u[tg_apih::from].stringify(Serial);
 }
 ```
 
 Примечание: результат доступа к значению через `[]` также является типом `Text`, то есть доступны все его возможности:
+
 ```cpp
 void update(fb::Update& u) {
     // сравнение
-    u[tg_apih::message][tg_apih::text] == "1234";
+    u[tg_apih::text] == "1234";
 
     // конвертация
-    float v = u[tg_apih::message][tg_apih::text];
+    float v = u[tg_apih::text];
 
     // и так далее
 }
 ```
 
 ### Комбинированный доступ
 Все подклассы внутри `Update` имеют доступ через `[]`, то есть доступ к данным можно комбинировать. Например получить текст сообщения вот так:
+
 ```cpp
 void update(fb::Update& u) {
     Serial.println(u.message()[tg_apih::text]);

src/bot_config.h

@@ -18,6 +18,11 @@
 #define FB_ESP_BUILD 1
 #endif
 
+//
+#define FB_SUB_BEGIN [&]() {
+#define FB_SUB_END }();
+#define FB_SUB_NEXT FB_SUB_END FB_SUB_BEGIN
+
 // #define FB_USE_LOG Serial
 
 // log