API скрипта и написание плагинов
Плагины являются расширениями, подключаемыми к движку плагинов скрипта Экзекутор. При написании собственных плагинов Вы можете использовать плагин-шаблон "- TEST PATTERN PLUGIN -", который есть в стандартном пакете дистрибутивов и который представляет собой набор всех возможных файлов событий с пустым шаблоном содержимого. Имя плагина - это название его папки. В папке плагина должен находится файл Pluginfo.lua, в котором в таблице Pluginfo содержатся данные о плагине: описание ("info"), версия ("version") и флаг активности ("enable"):
["version"] = 1,
["info"] = "Описание плагина.",
При запуске плагина, если флаг активности установлен на 0, то он не добавляется в очередь выполнения процедур (неактивен). Если при запуске этот файл не найден, то плагин считается некорректным и дезактивируется.
В этой папке должны находиться папки с названием локализаций, которые поддерживает плагин. В этих папках располагаются файлы, которые заносятся в соответствующие таблицы выполнения операций. Вот перечень файлов, которые могут быть в папке локализации плагина и их описание:
Config.lua - файл конфигурации с таблицей, содержащей переменные и значения по умолчанию, которые при запуске заносятся в общий конфигурационный файл скрипта (Config.cfg). Вот содержимое файла Config.lua:
Main.lua - файл, содержащий операции, выполняемые при запуске (активации) скрипта (плагина). Это может быть просто присваивание какого-либо значения переменным, либо выполнение каких-либо действий и т.п.
Vars.lua - в этом файле создаются переменные, содержатся функции и процедуры, которые использует плагин. Загружается в самом начале при запуске плагина.
Killer.lua - этот файл содержит так называемые "деструкторы". Тоесть просто уничтожение созданных в файле Vars.lua переменных и функций (присваивание значения nil), чтобы освободить занятую ими память. Выполняется при полной выгрузке плагина.
Menu.lua - файл аналогичен по структуре файлам меню бота или хаба. В таблице Menu содержатся таблицы команд, используемых плагином. При запуске команды из этого файла заносятся в таблицу меню Бота (BotMenu).
OnCommand.lua - файл, содержащий процедуру, вызываемую при событии, когда пользователь вводит команду. Вот его структура:
return
OnMsgAny.lua - в этом файле содержится функция, вызываемая при произвольном сообщении от пользователя. Также на её основе обрабатываются приватные сообщения. Вот структура файла:
return
Кстати, кроме переменной data при обработке можно пользоваться переменной rawdata, которая содержит текст, передаваемый в функцию обработки как есть, без изменения и предварительной обработки.
OnMsgChat.lua - этот файл содержит функцию, вызываемую, когда пользователь пишет сообщение в общий чат. Его структура:
return nil,chatdata
OnMsgSearch.lua - файл с функцией, вызываемой при поступлении поискового запроса и ответа на поисковый запрос от пользователя. Формат:
return
Если функция после обработки действий возвращает nil (return без параметров), то обработка запроса продолжается дальше, передавая обработку следующим плагинам после этого. Если Вы хотите прервать обработку запроса, то используйте возврат со значением true (return true).
OnPlugError.lua - файл с функцией, вызываемой при возникновении в скрипте ошибки (может не работать на Verlihub). Формат:
OnPlugTimer.lua - файл с функцией, выполняемой при срабатывании главного таймера бота (интервал 60 секунд). Формат:
OnSecondPlugTimer.lua - файл с функцией, выполняемой при срабатывании секундного таймера бота (интервал 1 секунда). Формат:
OnUnload.lua - файл с функцией, вызываемой при выгрузке плагина или скрипта. Формат:
OnUserLogin.lua - файл с функцией, вызываемой при подключении пользователя к Хабу. Формат:
return
Если функция возвращает nil (return без параметров), то обработка события продолжается дальше, передавая обработку следующим плагинам после этого. Если Вы хотите прервать обработку события, то используйте возврат со значением true (return true).
OnUserLogout.lua - файл с функцией, вызываемой при событии отключения (выхода) пользователя. Формат:
return
Если функция возвращает nil (return без параметров), то обработка события продолжается дальше, передавая обработку следующим плагинам после этого. Если Вы хотите прервать обработку события, то используйте возврат со значением true (return true).
OnMsgConnectToMe.lua - файл с функцией, вызываемой при активном запросе соединения. Формат:
return
Если функция возвращает nil (return без параметров), то обработка события продолжается дальше, передавая обработку следующим плагинам после этого. Если Вы хотите прервать обработку события, то используйте возврат со значением true (return true).
OnMsgRevConnectToMe.lua - файл с функцией, вызываемой при пассивном запросе соединения. Формат:
return
Если функция возвращает nil (return без параметров), то обработка события продолжается дальше, передавая обработку следующим плагинам после этого. Если Вы хотите прервать обработку события, то используйте возврат со значением true (return true).
OnMsgMyINFO.lua - файл с функцией, вызываемой при поступлении от пользователя строки MyINFO. Формат:
return
Если функция возвращает nil (return без параметров), то обработка события продолжается дальше, передавая обработку следующим плагинам после этого. Если Вы хотите прервать обработку события, то используйте возврат со значением true (return true).
OnConnect.lua - файл с функцией, вызываемой при подключении клиента к хабу перед авторизацией. Формат:
return
Если функция возвращает nil (return без параметров), то обработка события продолжается дальше, передавая обработку следующим плагинам после этого. Если Вы хотите прервать обработку события, то используйте возврат со значением true (return true).
Text_lang.lua, где lang - язык (2 символа в нижнем регистре из таблицы поддерживаемых языков EkzekutorLangs) - файл с текстом перевода плагина для выбранного языка (используется для многоязычных функций). Формат:
[2]="текст второго индекса",
…
Функции плагинов выполняются в порядке очерёдности их приоритетов, тоесть по порядку, в котором они находятся в списке плагинов.
Немного об особенностях работы скрипта и его API
gl(key, user) - мультиязычная функция бота. Служит для получения текста (или объекта) с желаемым ключом из файла локализации для языка пользователя user или языка по умолчанию, если пользователь не содержится в таблице UsersLangTable и для него не задан язык. Если вместо ника user в функцию передаётся пустая строка, это также означает получение языка по умолчанию. Ключ представляет собой совокупность файла с локализацией и индекса в нём. Для текста из файла языковой локализации Бота это сочетание "Bot_index". Для текста из файла языковой локализации Хаба это сочетание "Hub_index". Для текста из файла языковой локализации Плагина это сочетание "ИмяПлагина_index". Плагины для получения ключа для себя используют значение переменной CurPlugName, где содержится имя текущего плагина, и через знак подчёркивания индекс в таблице текстовой локализации.
GetLangsList() - возвращает список языков из таблицы EkzekutorLangs.
AddRobotBot(nm,cls,dsk,eml) - добавляет бота в список Хаба. Параметры: nm - имя, cls - класс, dsk - описание, eml - Email.
DelRobotBot(nm) - удалить бота из списка Хаба. Параметры: nm - имя.
GetClassCount() - возвращает количество имеющихся классов на Хабе.
PMToUser(bot, user, from, data) - послать приватное сообщение указанному пользователю. Параметры: bot - имя пользователя (бота), от чьего имени посылается сообщение, user - ник пользователя, которому мы отправляем сообщение, from - ник бота (пользователя), которое высвечивается в сообщении как отправителя, data - текст сообщения.
PMToAll(user, bot, data) - послать приватное сообщение всем пользователям. Параметры: user - отображаемое в сообщении имя, от кого поступило сообщение, bot - имя бота (пользователя) (может быть пустой строкой), от которого посылается сообщение, data - текст сообщения.
PMToOPs(user, bot, data) - послать приватное сообщение всем операторам. Параметры: user - отображаемое в сообщении имя, от кого поступило сообщение, bot - имя бота (пользователя), от которого посылается сообщение, data - текст сообщения.
PMToOPsOver(prf, user, bot, data) - послать приватное сообщение всем пользователям, чей профиль не ниже prf. Параметры: prf - профиль, которому посылается сообщение (и выше этого профиля), user - отображаемое в сообщении имя, от кого поступило сообщение, bot - имя бота (пользователя), от которого посылается сообщение, data - текст сообщения.
PMToClass(prf, user, bot, data) - послать приватное сообщение всем пользователям, чей профиль равен prf. Параметры: prf - профиль, которому посылается сообщение, user - отображаемое в сообщении имя, от кого поступило сообщение (может быть пустой строкой), bot - имя бота (пользователя), от которого посылается сообщение, data - текст сообщения.
PMToMode(prf, user, bot, data) - послать приватное сообщение всем пользователям, чей тип соединения равен prf. Параметры: prf - тип соединения, которому посылается сообщение (A, P или S, что соответствует активному, пассивному и SOCKS типу), user - отображаемое в сообщении имя (может быть пустой строкой), от кого поступило сообщение, bot - имя бота (пользователя), от которого посылается сообщение, data - текст сообщения.
ToUser(bot, user, data) - послать сообщение пользователю. Параметры: bot - ник, от которого отправляем сообщение (может быть пустой строкой), user - ник адресата, data - текст сообщения. Если параметр bot равен пустой строке, то пользователю отправляется текст data как есть.
ToAll(user, data) - послать сообщение всем. Параметры: user - ник, от которого отправляется сообщение (может быть пустой строкой), data - текст сообщения. Если параметр user равен пустой строке, то пользователю отправляется текст data как есть.
ToOPs(user, data) - послать сообщение операторам. Параметры: user - ник, от которого отправляется сообщение (может быть пустой строкой), data - текст сообщения. Если параметр user равен пустой строке, то пользователю отправляется текст data как есть.
ToClass(prf, user, data) - послать сообщение всем пользователям, чей профиль равен prf. Параметры: prf - профиль, которому посылается сообщение, user - отображаемое в сообщении имя, от кого поступило сообщение (может быть пустой строкой), data - текст сообщения.
ToMode(prf, user, data) - послать сообщение всем пользователям, чей тип соединения равен prf. Параметры: prf - тип соединения, которому посылается сообщение (A, P или S, что соответствует активному, пассивному и SOCKS типу), user - отображаемое в сообщении имя (может быть пустой строкой), от кого поступило сообщение, data - текст сообщения.
ToAllExeptGag(msgs) - отправить сообщение всем, кроме незаметнозаглушенных. Параметры: msgs - таблица с переченем ников, которым посылаем сообщение в формате [msgs][i]={"name","mes"}, тоесть каждый элемент таблицы msgs представляет из себя таблицу из двух элементов, первый из которых - ник, второй - сообщение.
ToAllExeptOPs(user, msgs) - отправить текст всем, кроме операторов. Параметры: user - ник, от которого отправляем сообщение, msgs - сообщение. Если параметр user равен пустой строке, то отправляем текст msgs как есть.
GetAllOnline() - возвращает таблицу с перечнем всех пользователей, подключенных к Хабу с указанием ников и классов в формате: [user]=class.
GetAllRegs() - возвращает таблицу с перечнем всех зарегистрированных пользователей на Хабе с указанием ников и классов в формате: [user]=class.
GetAllIPs() - возвращает таблицу с перечнем всех IP-адресов на Хабе и соответствующим им никам в формате: [IP]=user.
SendMenu(str, user) - посылает строку меню пользователю user. К строке str автоматически добавляется в начале "$UserCommand 1 3 " и "||" в конце.
SendMenuToAll(str) - аналогично предыдущей команде, только строка str посылается всем пользователям.
SendMenuToOPs(str) - также аналогична предыдущей команде, только строка str посылается всем операторам на Хабе.
GetUsrClass(user) - возвращает класс пользователя user (число).
UsrClassConvert(usercl) - конвертация класса usercl пользователя в шкалу стиля Verlihub, тоесть по возрастанию. В локализации verlihub, например, функция вернёт обратно входной параметр без изменений. В локализации ptokax04 вернёт результат по формуле: общее_число_классов - usercl.
isReg(user) - вернут true, если пользователь user зарегистрирован на Хабе, иначе вернёт false.
isVip(user) - вернёт true, если пользователь user является VIP-классом и false в противном случае. В локализации verlihub VIP-классом считается класс 2, в локализации ptokax VIP-классом считается класс, первый после класса с правами Оператора (если есть ещё классы, кроме этого, без прав Оператора).
isOp(user) - вернёт true, если пользователь user имеет права оператора, иначе false.
isMaster(user) - вернёт true, если пользователь user имеет права главного администратора (самый высокий класс), иначе false.
isClassPermissionValid(class1, class2) - функция производит сравнение прав двух классов, получаемых в качестве параметра. Если класс class1 главнее по правам, чем class2, то функция вернёт 1, если оба класса равны в правах, функция вернёт 0, если class1 ниже по правам, чем class2, вернёт nil.
isPermissionValid(user1, user2) - функция производит сравнение прав двух классов пользователей с никами user1 и user2, получаемых в качестве параметра. Если пользователь user1 главнее по правам, чем user2, то функция вернёт 1, если оба пользователя равны в правах, функция вернёт 0, если user1 ниже по правам, чем user2, вернёт nil.
GetIP(user) - возвращает строку, содержащую IP-адрес пользователя user.
GetMyInfo(user) - возвращает полную строку MyINFO пользователя user.
GetConMode(user) - вернёт описания режима подключения user. Если режим активный, вернёт "Активный", если пассивный, вернёт "Пассивный", если Socks5, вернёт "Socks5", иначе вернёт "Неизвестный".
GetUsrShare(user) - вернёт целое число байт шары пользователя user.
GetClient(user) - вернёт строку с описанием версии клиента пользователя user.
GetUsrConnection(user) - вернёт строку с типом подключения пользователя user.
GetDescription(user) - вернёт строку описания пользователя user.
GetUsrEmail(user) - вернёт строку с Email пользователя user.
GetSpeedLimit(user) - вернёт строку со значением ограничения скорости пользователем user, иначе пустую строку, если ограничение не используется.
GetSlotCount(user) - вернёт число слотов пользователя user или пустую строку.
DoBan(user, msg, bantime) - производит бан пользователя user на время в минутах bantime, с пояснением причины msg. Если bantime равно -1, то бан постоянный. Если bantime равно 0, то происходит бан пользователя на время по умолчанию.
DoDisconnect(user) - производит отключение пользователя user.
GetMyPrefix(user) - возвращает подходящий для текущего класса пользователя user префикс команд.
GetIPHost(host) - возвращает строку, содержащую IP-адрес DNS-имени host.
GetCurTopic() - возвращает строку с текущим топиком Хаба.
strLower(str) - конвертирует строку str в нижний регистр.
strUpper(str) - конвертирует строку str в верхний регистр.
FormatFileSize(int) - конвертирует целое число int в формат вывода размера шары (строка).
getDateTime(dtFormat,user) - возвращает строку времени или даты языком пользователя user (или языком по умолчанию). Если dtFormat = 0, то вернёт количество секунд от начала "Эпохи". Если dtFormat = 1, то вернёт время в виде hh:mm. Если dtFormat = 2, то вернёт дату в формате dd.mm.yyyy. Если dtFormat = 3, то вернёт форматированную строку по количеству секунд dtFormat, прошедших от начала "Эпохи".
SaveToFile(file,table,tablename) - функция сохранения в текстовый файл с именем file (полный путь) содержимого таблицы table с названием tablename.
BotReload() - горячая перезагрузка Бота.
isForbiddenChars(str) - проверка на содержание в строке str неразрешённых символов (не содержащихся в таблице разрешённых символов ника). Вернёт true если они найдены, иначе вернёт nil.
charEncode(str) - вернёт строку str, где все вхождения HTML кодов "&code;" заменяются на соответствующие символы.
getURLSource(url,gz,cp,prox) - вернёт исходный код страницы по адресу url. Если задан параметр qz и он равен 1, то будет производится распаковка GZip. Если задана строка cp, то будет проводится декодировка символов из кодировки cp. В параметре prox может указываться адрес proxy-сервера.
Некоторые полезные переменные и константы:
localization - текущая локализация Бота.
DefaultLang - язык Бота по умолчанию.
EkzekutorLangs - таблица с переченем языков (["lg"]="Language").
CurPlugName - название текущего плагина (для использования в плагинах).
version - версия скрипта.
myhubname - имя Хаба.
OpChat - имя ОП-чата.
PathSeparator - разделитель в пути файловой системы.
CmdPrefix - шаблон префикса команд.
wait_chat - таблица, содержащая очередь сообщений чата для отправки в формате: wait_chat[n]={user, data}.
wait_pm - таблица, содержащая очередь сообщений привата для отправки пользователям в формате: wait_pm[n]={bot, user, from, data}.
wait_touser - таблица, содержащая очередь сообщений для отправки указанным пользователям в формате: wait_touser[n]={bot, user, data}. Таблицы wait_chat, wait_pm и wait_touser обрабатываются при первом срабатывании основного таймера скрипта и очищаются.
TableName - таблица с никами-исключениями бота (["ник"]=1,).
MaskGagged - таблица незаметнозаглушенных.
Название папки, где расположен скрипт, хранится в переменной MySettings["FName"] с разделителем пути в конце.
