USERBOT - Программируемый ICQ-Бот

Настройка

Для настройки параметров Бота существует два файла - config.xml и messages.xml. Первый файл содержит основную конфигурацию Бота, такую как UIN, пароль, сервер, UIN администратора, включение логов и т.п. Второй файл содержит настройки диалога ответа Бота. Именно во второй файл заносятся все нужные вам команды и ответы на них. Стоит отметить, что второй файл в отличие от первого, перечитывается при каждом вводе команды пользователя, тогда как первый считывается один раз при старте Бота. Это позволяет добавлять новые диалоги в файл без перезапуска Бота.

Файл config.xml

Как уже говорилось ранее, данный файл содержит главные настройки Бота, полное их описание представлено ниже.
Допустимы комментарии в формате .

Блок <auth>:
В данном блоке указываются параметры подключения к серверу, а также задается статус выхода в Он-лайн. Директивы:
<server> -- Имя или IP-адрес ICQ-сервера.
<login> -- UIN
<password> -- Пароль
<status> -- Статус, в котором будет находиться Бот после его старта. Параметры директивы: ONLINE, AWAY, DND, NA, OCCUPIED, FREE4CHAT, INVISIBLE.
<substatus> - Суб-статус (или статус-картинка), который будет отображаться при старте Бота. Параметры директивы: ANGRY, DUCK, TIRED, PARTY, BEER, THINK, EAT, TV, FRIENDS, COFFEE, MUSIC, USINESS, CINEMA, FUNNY, PHONE, GAMES, COLLEGE, SHOP, SICK, SLEEP, SURF, INTERNET, WORK, TYPING. Укажите NONE для того, чтобы отключить суб-статус.

Блок <config>:
В данном блоке задается остальные настройки Бота.
Директивы:
<enablelogging> -- Вести лог в файл. Параметры директивы: YES/NO
<enablescreenlog> -- Выводить лог на экран. Параметры директивы: YES/NO
<enableadvertising> -- Включать рекламные сообщения в ответ Бота. Параметры директивы: YES/NO
<enableantiflood> -- Включать Флад-контроль. Параметры директивы: YES/NO
<functions> -- Включение исходного кода с функциями на PHP4/5. Относительный или абсолютный путь к файлу. Количество директив <functions> не ограничено.

Блок <logging>:
В данном блоке задаются параметры ведения логов.
<file> -- Лог-файл. Относительный или абсолютный путь к файлу.

Блок <advertising>:
В данном блоке задаются параметры отображения рекламных вставок
<file> -- Файл рекламной вставки. Относительный или абсолютный путь к файлу.
<frequency> -- Частота включения рекламных сообщений относительно количества запросов. Значение от 1 до 100 (чем меньше значение, тем чаще).
<prefix> -- Приставка, добавляемая в начало рекламного сообщения. Любое текстовое значение.

Блок <antiflood>:
В данном блоке задаются параметры отображения рекламных вставок
<count> -- Интервал, с которым пользователь должен вводить команды, в противном случае получит предупреждение и будет заблокирован. Значение в секундах.
<block> -- Время блокировки пользователя, если он не ввел код разблокировки. Значение в секундах.
<hash> -- Количество символов в коде разблокировки. Числовое значение.
<response> -- Предупреждение в случае превышения интервала <count>. Любое текстовое значение, также допустимо отображение интервала макротэгом %COUNT%.
<locked> -- Предупреждение в случае блокировки пользователя, а также отображение времени автоматический разблокировки, отобразить которое можно макротэгом %TIME%, и команды разблокировки, которые можно отобразить макротэгом %COMMAND%. Любое текстовое значение, а также макротэги %TIME% и %COMMAND%.
<unlocked> -- Сообщение об успешном вводе кода разблокировки. Любое текстовое значение.
<command> -- Команда разблокировки. Любое текстовое значение (не регулярные выражения).

Блок <kill>:
В данном блоке задаются параметры команды останова/перезапуска Бота.
<uin> -- UIN Администратора Бота. Указывается UIN.
<command> -- Команда перезагрузки/останова Бота. Любое текстовое значение (не регулярные выражения).
<response> -- Ответ на попытку несанкционированного выполнения команды перезагрузки/останова Бота. Любое текстовое значение.

Файл messages.xml

В данном файле указываются параметры диалога Бота с пользователем. Допустимы комментарии в формате .

Блок <config>:
В данном блоке указываются параметры ответа на нераспознанную команду и настройки включения PHP кода.
Директивы:
<response> -- Ответ Бота на любую нераспознанную команду. Любое текстовое значение. Количество директив <response> не ограничено.
<include> -- Включение исходного кода без функций на PHP4/5. Относительный или абсолютный путь к файлу. Количество директив <include> не ограничено.

Блок <dialogue>:
В данном блоке задаются параметры команды и ответа на нее Бота. Количество блоков <dialogue> не ограничено. Директивы:
<query> -- Команда. Указываются регулярные выражения.
<response> -- Ответ Бота. Любое текстовое значение.

Блок <random>:
В данном блоке задаются параметры команды и случайных ответов. Количество блоков <random> не ограничено. Директивы:
<query> -- Команда. Указываются регулярные выражения.
<response> -- Случайный ответ Бота. Любое текстовое значение. Количество директив <response> не ограничено.

Статические команды

Для того чтобы Бот мог отвечать на команды пользователя, следует указать все команды и ответы на них в файле конфигурации messages.xml в виде блоков <dialogue> и <random>, описание которых представлено в разделах ниже.

Ко всему прочему, блоки <dialogue> и <random> поддерживают макротэги, при помощи который можно включать в запрос или ответ определенные значения, такие как UIN, введенное и отправленное сообщение и т.п. Полный список макротэгов представлен ниже:

%INPUT_TEXT% -- Содержит текст, присланный пользователем.
%OUTPUT_TEXT% -- Содержит текст, отправляемый пользователю.
%USER_UIN% -- Содержит UIN пользователя.
%ADMIN_UIN% -- Содержит UIN администратора.

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

Задание команд и ответов на них

Простые статические команды задаются при помощи блоков <dialogue>. В блоке указывается две директивы, <query> и <response>. Первая служит для указания команды в виде регулярного выражения PHP/Perl, тогда как вторая, собственно и содержит ответ на команду, в нее можно указать простой текст.
Вот пример команды и ответа:

<dialogue>
<query>#^привет#i</query>
<response>Привет, я Робот!</response>
</dialogue>

Данный пример реализует ответ на слово "Привет". Параметр задан в виде регулярного выражения, из чего следует что, учитывая, наличие перед словом символа ^, команда должна начинаться именно с этого слова, иначе не будет выполнена. В конце параметра не указан символ $ (окончание строки), а это означает, что в качестве команды можно использовать любое словосочетание, начинающиеся со слова "Привет", например: "Привет, как дела?". Более подробно изучить регулярные выражения можно в соответствующей документации в интернете.

Команды со случайным ответом

Статические команды со случайным ответом задаются при помощи блоков <random>. В блоке указывается директива <query> которая служит для указания команды в виде регулярного выражения. Также в блоке указывается несколько директив <response>, которые и служат вариантами случайного ответа.
Вот пример команды и ответа:

<random>
   <query>#^пример#i</query>
   <response>Случайный ответ 1</response>
   <response>Случайный ответ 2</response>
   <response>Случайный ответ 3</response>
</random>

Данный пример реализует вывод случайного варианта ответа в ответ на команду "пример", из ответов, которые перечислены в директивах <response>.

Подключение PHP-кода.

Для того чтобы Бот мог выполнять ваш PHP-код, его следует подключить к Боту в виде файла исходного текста. Имя и путь к файлу задается в файле конфигурации Бота messages.xml с блоке <config> директивой <include>. Например:

<include>mycode.php</include>

Данная строка включит в Бот файл mycode.php. Следует отметить, что код в php-файле должен содержать особую структуру, о которой будет рассказно ниже.

Структура подключаемого PHP-кода

Для того чтобы Бот умел работать с PHP-кодом, код следует написать в соответствии с синтаксисом Бота. Синтаксис Бота представляет собой набор операторов if-elseif-else, в которых задаются условия и следствия выполнения условий - т.е. отправка сообщения пользователю. Для того чтобы задать условие, в Боте существует ряд переменных, полный их список представлен ниже.
Переменные:

$INPUT_TEXT -- Содержит текст, присланный пользователем.
$OUTPUT_TEXT -- Содержит текст, отправляемый пользователю.
$USER_UIN -- Содержит UIN пользователя.
$ADMIN_UIN -- Содержит UIN администратора.

Задание условия в PHP-коде

Чтобы задать условие, или и ответить на него, следует в качестве анализируемой переменной указать $INPUT_TEXT. Текст, который будет отправлен Ботом пользователю при выполнении условия, задается переменной $OUTPUT_TEXT. Переменная $USER_UIN служит для отображения UIN'а пользователя. Переменная $ADMIN_UIN содержит UIN, суказанный в главном файле конфигурации, в блоке <kill>, в директиве <uin>.

Пример простого PHP кода, который можно включить в Бота:

if(preg_match("#^считать\s+(.+)\s+(.+)\s+(.+)#is",$INPUT_TEXT,$vars))
{
   switch($vars[2])
   {
      case "+": $OUTPUT_TEXT = $vars[1] + $vars[3]; break;
      case "-": $OUTPUT_TEXT = $vars[1] - $vars[3]; break;
      case "*": $OUTPUT_TEXT = $vars[1] * $vars[3]; break;
      case "/": $OUTPUT_TEXT = $vars[1] / $vars[3]; break;
   }
}

Данный пример реализует простой калькулятор, обратиться к которому, можно отправив команду Боту, например "считать 5 + 5", в ответ Бот выведет число 10.

Как видно из данного примера, ничего сложного в синтаксисе нет. Достаточно просто адаптировать под Бот практически любую функцию. В синтаксисе также допустимы while, for, и другие стандартные операторы.

Функции в PHP-коде

Если вы используете в своем коде функции function, их следует указать в файле, указанном в директиве <functions>, в блоке <config> в файле конфигурации config.xml. Например:

<function>myfunction.php</function>

Данная строка включит в Бот файл myfunction.php.

ВАЖНО! Если вы укажите ваши функции в файле, описанном директивой <include>, в блоке <config> в файле конфигурации messages.xml, то Бот выдаст ошибку.