scripting

Скрипты ".hex"

".hex" — небольшой изолированный язык сценариев для расширения возможностей DimLife IRC. С его помощью можно автоматизировать ответы, создавать собственные команды, обрабатывать сообщения, обращаться к веб-сервисам и создавать интерактивные экраны.

Содержание

• "Обзор" (#обзор)
• "Структура скрипта" (#структура-скрипта)
• "События" (#события)
• "Переменные и аргументы" (#переменные-и-аргументы)
• "Команды языка" (#команды-языка)
• "Функции" (#функции)
• "Условия и циклы" (#условия-и-циклы)
• "HTTP-запросы и таймеры" (#http-запросы-и-таймеры)
• "Работа с файлами" (#работа-с-файлами)
• "Интерактивные экраны" (#интерактивные-экраны)
• "Безопасность" (#безопасность)

Обзор

Скрипты позволяют расширять клиент без установки дополнительных приложений или изменения исходного кода.

С их помощью можно:

• реагировать на сообщения, подключения и отключения пользователей;
• создавать команды вида "/имя";
• автоматически отправлять сообщения и выполнять действия;
• изменять отображение входящих сообщений;
• выполнять HTTP-запросы;
• использовать таймеры и события;
• выбирать и загружать файлы с разрешения пользователя;
• создавать собственные интерфейсы с кнопками, текстом и изображениями.

Язык имеет синтаксис, напоминающий mIRC, но представляет собой самостоятельную реализацию.

Скрипты находятся в разделе Меню → Scripts / Скрипты. Встроенные скрипты необходимо включать самостоятельно. Там же можно добавлять, импортировать, редактировать и восстанавливать сценарии.

Структура скрипта

Файл ".hex" состоит из двух основных типов блоков.

Обработчик события

on TEXT { if ($contains($text, $me) == true) { msg $chan Привет, $nick! } }

Этот обработчик реагирует на входящие сообщения, содержащие ваш никнейм.

Пользовательская команда

alias wave { me машет рукой в сторону $1- }

После создания команды можно написать:

/wave всем

Комментарии начинаются с ";" и продолжаются до конца строки. Команды внутри блока разделяются переводом строки или символом "|".

; Пример комментария alias hello { msg $chan Привет! echo $chan Команда выполнена }

События

События позволяют выполнять код в ответ на действия пользователей, сообщения сервера и изменения состояния приложения.

Основные события

"on LOAD"

Выполняется при загрузке или перезагрузке скрипта. Используется для начальной настройки переменных.

"on TEXT"

Срабатывает при получении сообщения в любом буфере. Позволяет изменить текст перед отображением или скрыть его.

"on ACTION"

Обрабатывает действия, отправленные через "/me".

"on INPUT"

Срабатывает при отправке текста из поля ввода до обработки команды или отправки сообщения.

"on NUMERIC"

Обрабатывает числовые ответы IRC-сервера. Переменная "$code" содержит код ответа.

События каналов

• "on JOIN" — пользователь входит в канал.
• "on PART" — пользователь покидает канал.
• "on QUIT" — пользователь отключается от сети.
• "on KICK" — пользователь исключён из канала.
• "on MODE" — изменяется режим пользователя или канала.
• "on OP" — пользователю выдан статус оператора.
• "on DEOP" — статус оператора снят.
• "on VOICE" — выдан голос.
• "on DEVOICE" — голос снят.
• "on HELP" — изменился соответствующий статус, если событие поддерживается.
• "on DEHELP" — соответствующий статус снят.
• "on BAN" — установлен бан.
• "on UNBAN" — бан снят.
• "on RAWMODE" — получена строка изменения режимов канала.
• "on TOPIC" — изменена тема канала.
• "on INVITE" — получено приглашение в канал.

События сети и приложения

• "on CONNECT" — завершено подключение к сети.
• "on DISCONNECT" — ранее установленное соединение закрыто.
• "on NICK" — пользователь сменил никнейм.
• "on NOTICE" — получено уведомление.
• "on SNOTICE" — получено серверное уведомление.
• "on CTCP" — получен CTCP-запрос.
• "on CTCPREPLY" — получен ответ на CTCP-запрос.
• "on NOTIFY" — пользователь из списка MONITOR появился в сети.
• "on UNOTIFY" — пользователь из списка MONITOR вышел из сети.
• "on APPACTIVE" — приложение перешло на передний план или в фон.
• "on FILERCVD" — завершено получение файла.
• "on FILESENT" — завершена отправка файла.
• "on SIGNAL:NAME" — получен пользовательский сигнал с именем "NAME".

Фильтрация событий

Можно ограничить обработчик определённым текстом или каналом:

on TEXT:help { msg $chan Чем могу помочь? }

Обработчик будет реагировать на сообщения, содержащие "help".

Для событий каналов можно указывать канал:

on JOIN:#help { if ($isme == true) { return } notice $nick Добро пожаловать в #help! }

Проверка "$isme" позволяет не отправлять приветствие при собственном входе в канал.

Изменение и скрытие сообщений

В обработчиках "TEXT", "ACTION", "INPUT" и "NUMERIC" используются специальные операторы.

"rewrite" заменяет отображаемый или отправляемый текст.

"halt" прекращает обработку текущей строки.

Пример автоматической замены сокращения:

on TEXT { rewrite $replace($text, ":wave:", "👋") }

Скрытие сообщений с определённым словом:

on TEXT { if ($contains($text, "spoiler") == true) { halt } }

Защита от случайной отправки определённого текста:

on INPUT { if ($iscmd == true) { return }

if ($contains($text, "hunter2") == true) { echo $chan Сообщение не отправлено halt } }

"$iscmd" позволяет отличать ввод IRC-команд от обычных сообщений.

События подключения

Автоматическая идентификация через NickServ:

on CONNECT { msg NickServ IDENTIFY %ns_pass }

Здесь "%ns_pass" — переменная с паролем. Не храните чувствительные данные в общедоступных скриптах и не импортируйте неизвестные сценарии с паролями.

Переменные и аргументы

Глобальные переменные

Переменные с префиксом "%" хранят строки, числа, списки и карты. Их значения сохраняются между событиями до перезагрузки скриптов.

set %counter 1 inc %counter dec %counter unset %counter

• "set %x <значение>" — записать значение.
• "set %x" — очистить переменную.
• "set -l %x <значение>" — создать локальную переменную.
• "unset %x" — удалить переменную.
• "inc %x" — увеличить числовое значение.
• "dec %x" — уменьшить числовое значение.
• "push %list <значение>" — добавить элемент в список.
• "setat %collection <ключ> <значение>" — записать значение по ключу или индексу.

Переменные общие для загруженных скриптов и сетей. Чтобы избежать конфликтов, используйте уникальные префиксы, например "%img_endpoint" или "%mybot_counter".

Встроенные поля

Эти переменные содержат сведения о текущем событии.

• "$me" — ваш никнейм.
• "$nick" — никнейм отправителя или участника события.
• "$chan" — канал или буфер.
• "$buffer" — текущий буфер.
• "$target" — цель события.
• "$network" — идентификатор сети.
• "$text" — текст сообщения или события.
• "$isme" — "true", если событие относится к вам.
• "$isprivate" — "true" для личного сообщения или уведомления.
• "$iscmd" — "true", если ввод содержит IRC-команду.
• "$victim" — пользователь, к которому применяется действие.
• "$mode" — изменяемый режим.
• "$newnick" — новый никнейм.
• "$account" — учётная запись, если сервер передаёт её.
• "$isserver" — признак серверного уведомления.
• "$ctime" — текущее Unix-время в секундах.
• "$ticks" — показания монотонных часов в миллисекундах.
• "$time" — локальное время в формате "HH:mm:ss".
• "$code" — числовой код ответа сервера.
• "$whois" — признак ответа на выполненный WHOIS.

Для выбора расположения элементов интерфейса доступны также "$screen.landscape", "$screen.width", "$screen.height" и "$screen.tv".

Аргументы команд

При вызове псевдонима аргументы доступны через позиционные переменные:

• "$1" — первый аргумент.
• "$2" — второй аргумент.
• "$2-" — все аргументы со второго до конца.
• "$1-" — все аргументы одной строкой.

Пример:

alias greet { set -l %who $1 msg $chan Привет, %who! Также привет: $2- }

Вызов:

/greet Alice Bob Charlie

Локальная переменная "%who" существует только во время выполнения текущей команды.

Команды языка

"echo"

Вывести локальную строку в буфер. Сообщение не отправляется на IRC-сервер.

echo $chan Скрипт загружен

Первый аргумент определяет буфер:

• "-a" — текущий буфер;
• "-s" — буфер сервера;
• "$chan" — буфер текущего события.

"msg"

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

msg #DimLife Всем привет!

Если цель передана через пустую переменную, сообщение не отправляется.

"raw"

Отправить необработанную строку IRC-протокола.

raw WHO #DimLife

Используйте команду осторожно: она обходит обычные команды клиента.

"rewrite"

Изменить текст в поддерживаемом обработчике.

rewrite $upper($text)

"signal"

Создать пользовательское событие.

signal refresh $chan

Обработать его можно через "on SIGNAL:refresh".

"timer"

Запланировать выполнение сигнала через заданное количество миллисекунд.

timer 500 refresh

Минимальная задержка — 20 мс. Таймеры позволяют выполнять повторяющиеся задачи без длительной блокировки интерфейса.

"toast"

Показать короткое уведомление в приложении.

toast Настройки сохранены

"return" и "halt"

• "return" — завершить текущий обработчик или псевдоним.
• "halt" — остановить обработку текущего события.

Команды IRC

Скрипты также могут вызывать поддерживаемые команды клиента: "me", "join", "part", "cycle", "topic", "mode", "invite", "kick", "knock", "names", "who", "whois", "whowas", "list", "notice", "ctcp", "nick", "away", "back", "op", "deop", "voice", "devoice", "ban", "unban", "ignore" и "unignore".

Команды, которые могут отключить или перенаправить соединение, например "quit" и "server", намеренно не предоставляются как обычные команды скриптов.

Функции

Функции записываются в формате "$имя(аргументы)" и возвращают значение.

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

• "$len(s)" — длина строки или количество элементов коллекции.
• "$lower(s)" — преобразование в нижний регистр.
• "$upper(s)" — преобразование в верхний регистр.
• "$left(s,n)" — первые "n" символов.
• "$right(s,n)" — последние "n" символов.
• "$substr(s,start,len)" — извлечение подстроки.
• "$replace(s,find,with)" — замена всех совпадений.
• "$trim(s)" — удаление пробелов по краям.
• "$contains(s,sub)" — проверка наличия подстроки.
• "$indexof(s,sub)" — позиция подстроки.
• "$repeat(s,n)" — повторение строки.
• "$capitalize(s)" — заглавная первая буква.
• "$title(s)" — заглавные первые буквы слов.
• "$pad(s,n)" — дополнение строки справа.
• "$padleft(s,n)" — дополнение строки слева.
• "$urlencode(s)" — кодирование для URL или формы.

Математика

• "$calc(expr)" — вычисление арифметического выражения.
• "$mod(a,b)" — остаток от деления.
• "$idiv(a,b)" — целочисленное деление.
• "$int(n)" — округление вниз до целого.
• "$abs(n)" — абсолютное значение.
• "$round(n,dp)" — округление до заданного количества знаков.
• "$ceil(n)" — округление вверх.
• "$pow(a,b)" — возведение в степень.
• "$clamp(n,lo,hi)" — ограничение диапазоном.
• "$rand(n)" — случайное целое от "0" до "n-1".
• "$rand(lo,hi)" — случайное целое в указанном диапазоне.
• "$min(...)" — минимальное значение.
• "$max(...)" — максимальное значение.

Важно: "$rand" не предназначен для генерации криптографически стойких случайных значений. Для задач безопасности используйте специально предназначенные криптографические функции, если они доступны.

Регулярные выражения

• "$re_match(s,re)" — проверить совпадение.
• "$re_find(s,re)" — найти первое совпадение.
• "$re_group(s,re,n)" — получить группу совпадения.
• "$re_replace(s,re,with)" — заменить совпадения.

JSON

"$json(body,path)" извлекает значение из JSON по пути с разделителями-точками.

$json($httpbody, translatedText) $json($httpbody, results.0.url)

"$tojson(value)" сериализует значение в JSON. Результат можно использовать в теле HTTP-запроса.

Списки и карты

• "$list(a,b,...)" — создать список.
• "$map(k,v,k,v,...)" — создать карту ключей и значений.
• "$get(collection,key)" — получить элемент по индексу или ключу.
• "$has(collection,key)" — проверить наличие элемента или ключа.
• "$keys(map)" — получить ключи карты.
• "$values(map)" — получить значения карты.
• "$split(s,sep)" — разделить строку на список.
• "$join(list,sep)" — объединить элементы списка.
• "$sort(list)" — отсортировать список.
• "$reverse(list)" — развернуть порядок элементов.
• "$slice(list,from,to)" — получить часть списка.
• "$concat(a,b,...)" — объединить коллекции или значения.
• "$find(list,x)" — найти индекс элемента.
• "$count(list,x)" — посчитать совпадения.
• "$sum(list)" — сумма чисел.
• "$range(lo,hi)" — последовательность целых чисел.
• "$pick(list)" — выбрать случайный элемент.
• "$shuffle(list)" — перемешать список.
• "$setting(key)" — прочитать настройку приложения.

Условия и циклы

Условия записываются в круглых скобках. Поддерживаются логические операторы "&&" и "||", сравнения "==", "!=", "<", ">", "<=", ">=", а также "isin" и "iswm".

if ($nick == ChanServ) { echo $chan Получено сообщение службы } elseif (%warned > 3 && $isme == false) { msg $chan Пожалуйста, соблюдайте правила } else { inc %warned }

Перебор коллекции

foreach %p $keys(%score) { echo $chan %p: $get(%score, %p) очков }

"foreach" перебирает элементы списка или ключи карты.

Цикл "while"

while ($len(%queue) > 0) { ; обработать очередь }

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

Каждый обработчик выполняется в ограниченном бюджете времени и инструкций. Длительные циклы могут сделать интерфейс неотзывчивым. Для повторяющихся задач используйте "timer".

HTTP-запросы и таймеры

HTTP-запросы выполняются асинхронно. Результат передаётся обработчику сигнала.

GET-запрос

http.get https://example.com/api done $chan

POST-запрос

http.post https://example.com/api text=hello done $chan

Параметры HTTP

Флаги указываются перед URL.

• "-t <тип>" — задать "Content-Type".
• "-h <имя:значение>" — добавить HTTP-заголовок; флаг можно повторять.
• "-b %var" — использовать полное содержимое переменной в качестве тела запроса.

Пример отправки JSON:

set %payload $tojson($map(text, $1-, lang, irc)) http.post -t application/json -b %payload https://example.com/api done $chan

Без "-t" тип содержимого определяется по форме тела запроса: JSON, данные формы или обычный текст.

Результат запроса

В обработчике ответа доступны следующие поля:

• "$httpok" — "true", если запрос завершился успешно.
• "$httpstatus" — HTTP-код ответа.
• "$httpbody" — тело ответа, ограниченное примерно 1 МБ.
• "$httplocation" — значение заголовка "Location".
• "$httperror" — описание ошибки, если ответ не был получен.
• "$json(body,path)" — извлечение значения из JSON-ответа.

Пример:

on SIGNAL:done { if ($httpok == true) { echo $1 Ответ получен } else { echo $1 Ошибка HTTP: $httpstatus } }

Здесь "$1" содержит контекст, переданный при запуске запроса.

Перезагрузка скриптов отменяет ожидающие таймеры, HTTP-запросы и запросы выбора файлов. Старые обработчики не должны получать результаты, предназначенные для предыдущей версии скрипта.

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

Работа с файлами

Скрипт не имеет прямого доступа к файловой системе и не может произвольно читать файлы по пути. Для выбора файла предусмотрена команда "media.pick".

Выбор файла

media.pick -m image/* picked $chan

Приложение запрашивает разрешение пользователя и открывает системный выбор файлов. Скрипт получает временный токен файла, а не путь к нему.

Доступные поля:

• "$mediaok" — "true", если файл выбран.
• "$mediatoken" — временный токен доступа.
• "$medianame" — имя файла.
• "$mediamime" — MIME-тип.
• "$mediasize" — размер в байтах либо "-1", если размер неизвестен.

Загрузка файла

media.upload https://example.com/upload $mediatoken done $chan

"media.upload" отправляет выбранный файл на указанный URL. По умолчанию используется "multipart/form-data" с полем "file".

Дополнительные флаги:

• "-h <имя:значение>" — добавить заголовок.
• "-p <имя=значение>" — добавить текстовое поле формы.
• "-f <поле>" — изменить имя поля файла.
• "-r" — отправить файл как необработанное тело запроса.

Размер файла ограничен 64 МБ. Перенаправления HTTP не выполняются автоматически.

Пример сценария загрузки:

alias img { media.pick -m image/* picked $chan }

on SIGNAL:picked { if ($mediaok != true) { return }

toast Загружается $medianame media.upload https://example.com/upload $mediatoken done $1 }

on SIGNAL:done { if ($httpok != true) { echo $1 Ошибка загрузки return }

set -l %url $trim($httplocation)

if ($len(%url) == 0) { set -l %url $trim($httpbody) }

msg $1 %url }

Замените адрес "https://example.com/upload" на реальный URL сервиса загрузки. Скрипт должен проверять ответ сервера: успешный HTTP-код сам по себе не гарантирует, что файл действительно сохранён.

Интерактивные экраны

Команда "view" позволяет создавать интерфейсы из текстов, кнопок, панелей, изображений и других элементов.

alias counter_render { view { surface bg #13243f radius 20 pad 16 { column gap 12 align center { text "Счётчик" bold color #ffffff textsize 18 text %n color #8fd0ff textsize 40 row gap 10 { button "-1" dec weight 1 button "+1" inc weight 1 } } } } }

Экран можно обновлять повторным вызовом "view" после изменения состояния. Кнопки вызывают псевдонимы или создают сигналы.

Элементы интерфейса

• "column { ... }" — вертикальное расположение элементов.
• "row { ... }" — горизонтальное расположение.
• "stack { ... }" — размещение элементов слоями.
• "ring { ... }" — расположение элементов по кругу.
• "surface { ... }" — панель с фоном, отступами и оформлением.
• "text "..."" — текстовая надпись.
• "button "название" действие [аргументы]" — кнопка.
• "card "Ah" [red] [back]" — игральная карта.
• "image "URL"" — удалённое изображение.
• "spacer" — свободное пространство.

Модификаторы

Для оформления элементов предусмотрены следующие модификаторы:

• "bold" — жирный текст.
• "fill" — заполнение доступного пространства.
• "wrap" — перенос элементов строки.
• "circle" — круглая форма.
• "color " — цвет текста.
• "bg " — цвет фона.
• "bgimage " — изображение фона.
• "gradient linear::" — линейный градиент.
• "textsize " — размер текста.
• "width " — ширина.
• "height " — высота.
• "size " — размер.
• "radius " — скругление углов.
• "pad " — внутренние отступы.
• "gap " — расстояние между элементами.
• "weight " — вес элемента в раскладке.
• "align " — выравнивание.
• "border [w]" — рамка.
• "offsetx " и "offsety " — смещение.
• "elevation " — визуальная высота.

Для изображений доступны режимы масштабирования "crop", "fit" и "stretch".

Безопасность

Язык ".hex" спроектирован как изолированная среда.

• Скрипты выполняются с ограничениями по времени и количеству инструкций.
• Доступ к сети осуществляется через предусмотренные HTTP- и файловые функции.
• Скрипты не могут произвольно читать файловую систему.
• Выбор файла требует явного действия пользователя.
• Передача файла выполняется через временный токен.
• Нативный код не загружается: интерфейсы описываются декларативно.
• Неизвестные команды пропускаются с сообщением в буфере.

Однако изоляция не делает любой скрипт автоматически безопасным. Скрипт может отправлять сообщения, обращаться к внешним сервисам и передавать выбранные пользователем файлы. Устанавливайте сценарии только из источников, которым доверяете, и проверяйте их содержимое перед запуском.

Другие разделы документации

• "Первые шаги" (https://github.com/dimliferu/DimLifeIRC/wiki)
• "Возможности" (https://github.com/dimliferu/DimLifeIRC/wiki/features)
• "Команды IRC" (https://github.com/dimliferu/DimLifeIRC/wiki/commands)
• "Шифрование" (https://github.com/dimliferu/DimLifeIRC/wiki/encryption)
• "Справочник" (https://github.com/dimliferu/DimLifeIRC/wiki/reference)
• "Политика конфиденциальности" (https://github.com/dimliferu/DimLifeIRC/wiki/privacy)

---

DimLife IRC — IRC-клиент для Android с поддержкой пользовательских сценариев ".hex".

Исходный код: https://github.com/dimliferu/DimLifeIRC