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

Аргументы — это все, что участник написал после команды. В !выдать @anna 100 за турнир аргументы — это @anna, 100, за и турнир. Шаблон получает их в переменной arguments.

Слова по номерам

Бот делит текст после команды на слова по пробелам и нумерует их с единицы.

Пусть участник написал:

!выдать @anna 100 за турнир

Запись	Результат	Что это
arguments.get(1)	@anna	Первое слово
arguments.get(2)	100	Второе слово
arguments.get(5)	пусто	Такого слова нет
arguments.after(3)	за турнир	Все, начиная с третьего слова
arguments.before(2)	@anna 100	Все до второго слова включительно
arguments.range(2, 3)	100 за	Со второго по третье
arguments.value	@anna 100 за турнир	Все одной строкой
arguments.args	[@anna, 100, за, турнир]	Список слов
arguments.args | length	4	Сколько слов

Числа приходят текстом

arguments.get(2) — это текст «100», но бот сам превратит его в число, когда вы будете сравнивать или считать: arguments.get(2) > 50 сработает правильно. Проверить, что написали именно число, можно так: arguments.get(2) is number.

Кому адресована команда

arguments.targetMember — участник, к которому обращена команда. Бот ищет его в таком порядке:

1. Ответ на сообщение — участник, на чье сообщение ответили командой. Самый надежный способ.
2. Упоминание по имени — когда вы выбираете человека из списка при вводе @ и Telegram вставляет ссылку на него.
3. Числовой ID первым аргументом: !профиль 123456789.
4. @username — если бот уже видел этого участника в чате.

{% set target = arguments.targetMember %}
{% require target returning 'Ответь командой на сообщение участника или упомяни его' %}
Профиль {{ target }}: уровень {{ target.rank.level }}

Почему @username не всегда находится

Telegram не дает ботам находить пользователей по username. Бот узнает username, только когда человек пишет в чат при боте. Поэтому надежнее отвечать командой на сообщение нужного участника.

Срок и причина

Для команд в духе модерации есть готовый разбор срока и причины — как у встроенных /mute и /ban:

Запись	Что вернет
arguments.duration	Срок из аргументов в миллисекундах: первое слово, похожее на срок
arguments.reason	Остаток текста — причина

Сроки пишутся так: 30s, 10m, 2h, 1d, 1w, 1mo, 1y или по-русски 10м, 2ч, 1д, 1нед, 1мес, а также составные: 1ч30м.

{% set target = arguments.targetMember %}
{% require target returning 'Кого наказываем?' %}
{% set ms = arguments.duration ?: 3600000 %}
{{ target }} отправлен подумать на {{ duration(ms) }}.
Причина: {{ arguments.reason ?: 'не указана' }}

Функция duration(ms) превращает миллисекунды в понятный текст: «1 ч.», «30 мин.».

Проверяем аргументы

Всегда проверяйте, что участник написал нужное, — иначе команда выдаст непонятный результат. Удобнее всего тег require: если условие не выполнено, бот остановится и ответит вашим текстом.

{% set target = arguments.targetMember %}
{% set amount = arguments.get(2) %}
{% require target returning 'Укажи участника: !выдать @anna 100' %}
{% require amount is number returning 'Укажи сумму числом: !выдать @anna 100' %}
{% require amount > 0 returning 'Сумма должна быть больше нуля' %}
{% set balance = target.getAttribute('coins').increment(amount) %}
{{ target }} получил {{ amount }} 🪙. Баланс: {{ balance }}

Что не поддерживается

В Telegram нет параметров slash-команд, поэтому getOption и getOptionsByType всегда возвращают пустое значение. Вместо них есть duration и reason.

Полный список — в справочнике Arguments.