upd

Author: GyverLibs

README.md

@@ -21,10 +21,10 @@
 Любые Arduino
 
 ### Зависимости
-- [GSON](https://github.com/GyverLibs/GSON) v1.5+
-- [StringUtils](https://github.com/GyverLibs/StringUtils) v1.4.14+
-- [GyverHTTP](https://github.com/GyverLibs/GyverHTTP) v1.0.2+
-- [GTL](https://github.com/GyverLibs/GTL) v1.1.7+
+- [GSON](https://github.com/GyverLibs/GSON) v1.8.0+
+- [StringUtils](https://github.com/GyverLibs/StringUtils) v1.5.0+
+- [GyverHTTP](https://github.com/GyverLibs/GyverHTTP) v1.0.27+
+- [GTL](https://github.com/GyverLibs/GTL) v1.3.1+
 
 ## Содержание
 - [Документация](#docs)

docs/1.main.md

@@ -37,6 +37,9 @@ void setTimeout(uint16_t timeout);
 
 // ============================== SYSTEM ==============================
 
+// автоматически декодировать юникод в тексте (умолч. true)
+void decodeUCN(bool decode);
+
 // установить токен
 void setToken(const String& token);
 
@@ -331,7 +334,7 @@ Text id();
 Text threadID();
 
 // сообщение отправлено в топик форума
-Text isTopic();
+bool isTopic();
 
 // дата отправки или пересылки сообщения
 Text date();
@@ -419,6 +422,12 @@ ChatRead chat();
 ```cpp
 // наследует gson::Entry
 
+enum class Type {
+    Empty,
+    OK,
+    Error,
+};
+
 // освободить память
 void reset();
 
@@ -427,6 +436,21 @@ StreamReader& getReader();
 
 // получить скачанный json пакет как Text
 Text getRaw();
+
+// тип результата
+Type type();
+
+// результат - ошибка
+bool isError();
+
+// результат пуст
+bool isEmpty();
+
+// получить текст ошибки
+Text getError();
+
+// получить код ошибки
+Text getErrorCode();
 ```
 </details>
 <details>
@@ -485,7 +509,7 @@ Text lastName();
 Text description();
 
 // в supergroup включены темы
-Text isForum();
+bool isForum();
 ```
 </details>
 <details>
@@ -539,7 +563,7 @@ Text proximityAlertRadius();
 Text id();
 
 // бот или нет
-Text isBot();
+bool isBot();
 
 // имя
 Text firstName();
@@ -554,7 +578,7 @@ Text username();
 Text languageCode();
 
 // true - премиум юзер
-Text isPremium();
+bool isPremium();
 ```
 </details>
 <details>
@@ -590,7 +614,7 @@ Message();
 Message(const String& text, Value chatID);
 
 // для ручного добавления тех параметров, которых нет в классе!
-gson::string json;
+gson::Str json;
 
 // текст сообщения
 String text;
@@ -684,7 +708,7 @@ bool notification = Message::notificationDefault;
 bool protect = Message::protectDefault;
 
 // для ручного добавления тех параметров, которых нет в классе!
-gson::string json;
+gson::Str json;
 ```
 </details>
 <details>

docs/3.start.md

@@ -1,10 +1,13 @@
 ## Начало работы
 ### ESP8266/ESP32
 Библиотека нативно поддерживает МК ESPxx классом `FastBot2`:
+
 ```cpp
 #include <FastBot2.h>
 FastBot2 bot;
+// FastBot2 bot("токен");
 ```
+
 Для подключения к WiFi можно использовать типичную конструкцию:
 
 ```cpp
@@ -22,6 +25,7 @@ void setup() {
 
 ### Другие платформы
 Библиотека работает напрямую с `Arduino Client` интерфейсом, поэтому можно подключить любую библиотеку, которая предоставляет к нему доступ (для Ethernet, GPRS и так далее). Для этого используется класс `FastBot2Client`:
+
 ```cpp
 SomeClient client;
 
@@ -30,6 +34,7 @@ FastBot2Client bot(client);
 ```
 
 Пример с [TinyGSM](https://github.com/vshymanskyy/TinyGSM):
+
 ```cpp
 // обязательно нужен модем с поддержкой HTTPS
 #define TINY_GSM_MODEM_SIM7000SSL
@@ -126,7 +131,7 @@ void setup() {
 
     bot.setToken(BOT_TOKEN);
     bot.onUpdate(update);
-    // bot.setPollMode(fb::Poll::Long, 30000);
+    // bot.setPollMode(fb::Poll::Long, 60000);
 }
 
 void loop() {
@@ -139,6 +144,7 @@ void loop() {
 ```cpp
 bot.setPollMode(fb::Poll::Sync, 4000);
 ```
+
 #### Обновление
 Такой же режим, как в первой версии FastBot: библиотека запрашивает обновления и ждёт ответа внутри `tick()`. При плохой связи может "зависать" внутри `tick()` на ощутимое (не дольше таймаута) время. Ставить период меньше `4000` не рекомендуется - сервер Телеграм "накажет" долгим ответом за слишком частый опрос!
 
@@ -149,6 +155,7 @@ bot.setPollMode(fb::Poll::Sync, 4000);
 ```cpp
 bot.setPollMode(fb::Poll::Async, 4000);
 ```
+
 #### Обновление
 "Асинхронный" режим - библиотека запросит обновления и обработает ответ, когда он придёт. Период опроса - такая же особенность, как в `Sync`.
 
@@ -157,8 +164,9 @@ bot.setPollMode(fb::Poll::Async, 4000);
 
 ### `Long`
 ```cpp
-bot.setPollMode(fb::Poll::Long, 30000);
+bot.setPollMode(fb::Poll::Long, 60000);
 ```
+
 #### Обновление
 Самый правильный способ опроса - асинхронный *long polling*. Период можно ставить побольше - от 20 секунд. Библиотека отправляет запрос и получит ответ либо по указанному таймауту, либо по факту поступления новых сообщений в бота. Таймаут переподключения - по умолчанию 300мс. Это самый быстрый и безопасный способ получения обновлений, сообщения доставляются мгновенно.
 

docs/4.updates.md

@@ -1,13 +1,15 @@
 ## Разбор обновлений
 Обновления попадают в подключенный обработчик:
+
 ```cpp
 void update(fb::Update& u) {
 }
 ```
 
-Каждый вызов этой функции - одно "сообщение" от бота. Здесь `fb::Update` - это класс, в котором удобно доступны самые основные инструменты для работы с ботом и с сообщениями, как в виде значений, так и в виде вложенных классов. В "ручном режиме" разбора JSON библиотека поддерживает весь Telegram Bot API и позволяет получать из обновлений все возможные данные.
+Каждый вызов этой функции - одно "сообщение" от бота. Здесь `fb::Update` - это класс, в котором удобно доступны самые основные инструменты для работы с ботом и с сообщениями, как в виде значений, так и в виде вложенных классов. В "ручном режиме" разбора JSON библиотека поддерживает весь [Telegram Bot API](https://core.telegram.org/bots/api) и позволяет получать из обновлений все возможные данные.
 
 Например выведем текст сообщения:
+
 ```cpp
 void update(fb::Update& u) {
     Serial.println(u.message().text());
@@ -21,7 +23,7 @@ void update(fb::Update& u) {
 - Печататься в любой `Print` (например `Serial`)
 - Сравниваться со строками любого типа
 - Экспортироваться в любой тип данных
-- Имеет встроенный декодер Unicode (для кириллицы и смайликов)
+- Имеет декодер Unicode (для кириллицы и смайликов)
 - Может посчитать свой хэш для быстрого сравнения строк
 
 > Это очень мощный инструмент! Рекомендую изучить [полную документацию](https://github.com/GyverLibs/StringUtils?tab=readme-ov-file#sutext), чтобы знать все возможности и разбирать апдейты с удовольствием
@@ -35,9 +37,7 @@ void update(fb::Update& u) {
 
     uint32_t id = u.message().id();         // вывод в число
 
-    // вывод в String с преобразованием юникода (кириллицы)
-    String text = u.message().text().decodeUnicode();
-    Serial.println(text);
+    Serial.println(u.message().text());     // печать
 
     // пример с разбором callback query через хэш
     switch (u.query().data().hash()) {
@@ -56,19 +56,16 @@ void update(fb::Update& u) {
 
 > В примере с хэшем строка, указанная в `SH`, не существует в программе: вместо этого компилятор подставляет её хэш (число). А в `switch` мы подаём хэш пришедшей строки. Это позволяет максимально быстро, оптимально и очень удобно сравнивать строки в сценариях, когда приходящий текст может иметь известный набор значений. В данном случае - обработка query, очень типовая задача (определение кнопки клавиатуры, на которую нажал юзер).
 
-Удобного получения хэша сообщения с кириллицей не предусмотрено, можно получить его так:
-
-```cpp
-size_t hash = SH(u.message().text().decodeUnicode().c_str());   // раскодировать и передать в хэш-функцию
-```
+> Начиная с версии `1.2.0` библиотека сама декодирует юникод (UCN). Если в каком-то стандартном поле остался юникод (текст вида `\uabcd` - пишите мне на почту, добавлю обработку). В остальных случаях декодировать юникод можно как `u.foo().decodeUnicode()`
 
 ### Личка с админом
 Телеграм бот - публичная штука, любой пользователь может найти вашего бота в поиске и взаимодействовать с ним. Чтобы ограничить круг лиц (админов), которые могут работать с ботом (или иметь дополнительные функции), достаточно вручную фильтровать обновления по id юзера. Несколько способов:
+
 ```cpp
 void update(fb::Update& u) {
     // один админ
     // Если не наш id - выходим
-    if (u.message().from().id() != 12345678ll) return;
+    if (u.message().from().id() != 12345678LL) return;
 
     // несколько админов
     switch (u.message().from().id().toInt64()) {
@@ -189,13 +186,18 @@ void update(fb::Update& u) {
 void update(fb::Update& u) {
     Serial.println(u[tg_apih::text]);
     // "изнутри" этот код аналогичен u.message().text()
+    
+    Serial.println(u[tg_apih::from][tg_apih::username]);
 }
 ```
 
+> Для корректного получения `bool` данных из `Text` нужно сравнивать его с `bool`, например `u[tg_apih::from][tg_apih::is_bot] == true`
+
 Тип текущего обновления парсится библиотекой, его можно разобрать так:
 
 ```cpp
 void update(fb::Update& u) {
+    // встроенные типы
     switch (u.type()) {
         case fb::Update::Type::Message:
             break;
@@ -206,7 +208,7 @@ void update(fb::Update& u) {
         // и так далее
     }
 
-    // или
+    // или из hash api
 
     switch ((size_t)u.type()) {
         case tg_apih::message:
@@ -251,7 +253,7 @@ void update(fb::Update& u) {
     u[tg_apih::text] == "1234";
 
     // конвертация
-    float v = u[tg_apih::text];
+    float f = u[tg_apih::text];
 
     // и так далее
 }
@@ -262,9 +264,9 @@ void update(fb::Update& u) {
 
 ```cpp
 void update(fb::Update& u) {
-    Serial.println(u.message()[tg_apih::text]);
+    Serial.println(u.message().chat()[tg_apih::id]);
 
     // или получить значения, для которых в библиотеке не предусмотрено функций
-    Serial.println(u.message()[tg_apih::is_from_offline]);
+    Serial.println(u[tg_apih::is_from_offline]);
 }
 ```