Функции

Логические функции

defined

Данная функция полезна для проверки определено ли указанное выражение или нет. Возвращает true если выражение определено и false в противном случае.

{% if (defined([1, 2][5])) %}YES{% else %}NO{% endif %}

Предыдущий пример распечатает NO, так как индекс 5 списка [1, 2] не определен.

even

Эта функция очень простая, она ожидает число и возвращает true, если это число чётное и false, если нечётное.

{% if (even(2)) %}A{% else %}B{% endif %}

Предыдущий пример распечатает A, так как 2 — чётное число.

odd

Это противоположная even функция. Она ожидает число и возвращает true, если число нечётное и false, если чётное.

{% if (odd(2)) %}A{% else %}B{% endif %}

Предыдущий пример распечатает B, так как 2 — чётное число.

iterable

Эта функция позволяет проверить, является ли аргумент допустимым для итераций объектом (список или карта).

{% if (iterable(2)) %}A{% else %}B{% endif %}

Предыдущий пример распечатает B, так как 2 не список и не карта, а простое число.

number

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

{% if (number(2)) %}A{% else %}B{% endif %}

Предыдущий пример распечатает A, так как 2 является числом.

empty

Функция ожидает любой объект и возвращает true, если аргумент является:

• null
• Undefined
• Пустым списком
• Пустой картой
• Числом 0

{% if (empty([1, 2])) %}A{% else %}B{% endif %}

Предыдущий пример распечатает B, так как [1, 2] — не пустой список.

Математические функции

abs

Математическая функция, позволяющая получить модуль выражения. Например, {{ abs(-1) }} выведет 1. Ожидает только один аргумент-число.

round

Функция округления дробного числа к целому. Опционально можно указать стратегию округления вторым аргументом:

• 'CEIL' — округление до большего целого;
• 'FLOOR' — округление до меньшего целого.

{{ round(1.3, 'CEIL') }}

Предыдущий пример распечатает 2. Стратегия округления нечувствительна к регистру, поэтому можно написать как 'CEIL', так и 'ceil'. Если второй аргумент не указан, число округляется до ближайшего целого.

Операции над строками

number_format

Функция number_format позволяет форматировать указанное число с указанными символами для разделителей группы разрядов и дробной части, а также с указанным количеством дробных цифр. Эта функция ожидает как минимум один аргумент и до четырех. Список аргументов в том порядке, как они ожидаются функцией:

1. Число для форматирования;
2. Количество дробных цифр (опционально);
3. Разделитель дробной части (опционально);
4. Разделитель группы разрядов (опционально);

{{ number_format(11000.136, 2, '.', ' ') }}

Предыдущий пример распечатает 11 000.14.

capitalize

Эта функция капитализации строки ожидает один аргумент. В результате выполнения функции первое слово строки станет с заглавной буквы.

{{ capitalize('hello world') }}

Предыдущий пример распечатает Hello world.

format

Данная функция принимает строку-шаблон, форматируя её с помощью переданных последующих аргументов.

{{ format('hello %s! %s', 'world', 123) }}

Предыдущий пример распечатает hello world! 123.

lower

Преобразует переданную строку в нижний регистр.

{{ lower('JUNIPERBOT') }}

Предыдущий пример распечатает juniperbot.

upper

Преобразует переданную строку в верхний регистр.

{{ upper('juniperbot') }}

Предыдущий пример распечатает JUNIPERBOT.

replace

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

{{ replace('Hello %name%', { '%name%': 'world' }) }}

Предыдущий пример распечатает Hello world.

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

{{ replace('Hello %NAME%', { '%name%': 'world' }, true) }}

Предыдущий пример тоже распечатает Hello world несмотря на то, что регистр заменяемой строки отличается от регистра строки поиска.

split

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

{{ split('juniper-bot', '-') }}

Предыдущий пример распечатает [juniper, bot].

title

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

{{ title('hello world') }}

Предыдущий пример распечатает Hello World.

trim

Эта функция избавит входную строку от пробелов в начале и в конце этой строки.

{{ trim('  Hello World  ') }}

Предыдущий пример распечатает Hello World без пробелов.

startsWith

Эта функция проверяет, начинается ли одна строка с другой указанной строки.

{{ startsWith('hello', 'he') }}

Предыдущий пример вернет true, поскольку hello начинается с he.

Она также может принимать третий логический аргумент как признак того, нужно ли сравнивать строки без учета регистра:

{{ startsWith('HELLO', 'he', true) }}

Предыдущий пример вернет true, поскольку HELLO начинается с he без учета регистра.

endsWith

Эта функция проверяет, заканчивается ли одна строка другой указанной строкой.

{{ endsWith('hello', 'lo') }}

Предыдущий пример вернет true, поскольку hello заканчивается на lo.

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

{{ endsWith('hello', 'LO', true) }}

Предыдущий пример вернет true, поскольку hello заканчивается на LO без учета регистра.

contains

Эта функция проверяет, содержит ли одна строка другую подстроку.

{{ contains('Hey there!', 'there') }}

Предыдущий пример вернет true, поскольку строка Hey there! содержит подстроку there.

Вместо строки поиска можно указать целый список для поиска любого из перечисленных подстрок:

{{ contains('Hey there!', ['there', 'heh']) }}

Предыдущий пример вернет true, поскольку строка Hey there! содержит одну из указанных подстрок there.

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

{{ contains('Hey THERE!', 'there', true) }}

Предыдущий пример вернет true, поскольку строка Hey THERE! содержит подстроку there без учета регистра.

plural

Эта функция поможет правильно выбрать нужную количественную форму слова или словосочетания в зависимости от указанного числа и языка (количественные числительные). Команда принимает до восьми аргументов, набор которых зависит от выбранного языка.

Первые два аргумента постоянные: число и язык (en — Английский, ru — Русский). Остальные аргументы зависят от выбранного языка:

Для английского языка

• Форма в единственном числе
• Форма во множественном числе

2 {{ plural(2, 'en', 'day', 'days') }}

Предыдущий пример распечатает 2 days.

Для русского языка

• Форма для чисел вида 1, 21, 31, 41, 51, 61, 71, 81, 101, 1001 (1 день, 51 день)
• Форма для чисел вида 2~4, 22~24, 32~34, 42~44, 52~54, 62, 102, 1002 (2 дня, 33 дня)
• Форма для чисел вида 0, 5~19, 100, 1000, 10000, 100000, 1000000 (0 дней, 7 дней, 100 дней)
• Общая форма в родительном падеже (1.5 дня)

2 {{ plural(2, 'ru', 'день', 'дня', 'дней', 'дня') }}

Предыдущий пример распечатает 2 дня.

Смешанные функции

random

Эта функция возвращает произвольный элемент из переданного списка или произвольное число из указанного диапазона.

{{ random(['раз', 'два', 'три']) }}

Предыдущий пример распечатает один из элементов раз, два или три случайно.

Для элементов списка вторым аргументом можно передать список соответствующих им весов (вероятностей):

{{ random(['раз', 'два', 'три'], [10, 50, 40]) }}

Предыдущий пример распечатает один из элементов раз, два или три случайно с вероятностью 10%, 50% и 40% соответственно.

Информация

Если для элемента отсутствует вес или задан некорректно, то он считается как 0, другими словами элемент исключается из выборки.

Однако, если вообще все вероятности отсутствуют или заданы некорректно, все элементы считаются равнозначными (выбирается рандомный как без весов).

Для произвольного числа используется выборка из диапазона чисел:

{{ random(10, 20) }}

Предыдущий пример распечатает случайное целое число от 10 до 20 включительно.

При указании только одного числа, будет использован диапазон от 0 до указанного числа:

{{ random(10) }}

Предыдущий пример распечатает случайное целое число от 0 до 10 включительно.

first

Эта функция вернет первый элемент указанного списка или первый символ строки. Если переданный аргумент не список и не строка, функция просто вернет этот аргумент. Если указанный аргумент — пустой список или строка, тогда функция возвращает Undefined.

{{ first([1, 2]) }}

Предыдущий пример распечатает 1.

last

Эта функция вернет последний элемент указанного списка или последний символ строки. Если переданный аргумент не список и не строка, функция просто вернет этот аргумент. Если указанный аргумент — пустой список или строка, тогда функция возвращает Undefined.

{{ last([1, 2]) }}

Предыдущий пример распечатает 2.

reverse

Эта функция возвращает перевернутый в обратном порядке список или строку. Если переданный аргумент не список и не строка, функция просто вернет этот аргумент.

{{ reverse([1, 2]) }}

Предыдущий пример распечатает[2, 1].

default

Эта функция ожидает два аргумента. Она возвращает второй аргумент, если первый null или Undefined.

{{ default(null, 'Hello') }} {{ default(undefinedVariable, 'World') }}

Предыдущий пример распечатает Hello World, поскольку переменная undefinedVariable не объявлена.

length

Эта функция возвращает размер указанного списка или длину указанной строки. Если аргумент не является строкой или списком, она возвращает0 для null и Undefined, для остальных случаев 1.

{{ length([1, 2]) }}
{{ length(null) }}
{{ length(9) }}

Предыдущий пример распечатает 2, 0 и 1 соответственно.

typeof

Эта функция вернёт название типа данных для указанного значения.

{{ typeof("blabla") }}
{{ typeof(null) }}
{{ typeof(9) }}

Предыдущий пример распечатает String, null и Number соответственно.

Информация

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

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

batch

Эта функция разделяет переданный список на равные группы списков. Она ожидает два аргумента:

• Первый аргумент — сам список;
• Второй аргумент — размер группы, на которые будет поделен этот список;

{{ batch([1,2,3], 2) }}

Предыдущий пример распечатает [[1, 2], [3]].

concat or concatenate

Эта функция объединит множество строк в одну строку.

{{ concat('1', '+', '1', '=', '2') }}

Предыдущий пример распечатает 1+1=2.

join

Эта функция похоже на concat, но объединяет элементы переданного списка в одну строку через разделитель. Функция принимает один или два аргумента. Первый аргумент — сам список, а второй — разделитель, которым нужно объединить элементы этого списка в строку. Если второй аргумент не указан, используется , в качестве разделителя (запятая с пробелом).

{{ join([1, null, 2], '|') }}

Предыдущий пример распечатает 1|2. Обратите внимание, что функция игнорирует значение null.

keys

Эта функция возвращает значения ключей для указанной коллекции (списка или карты). Для списков ключами являются индексы элементов.

{{ keys(['A', 'B']) }}

Предыдущий пример распечатает [0, 1].

values

Эта функция возвращает значения для указанной коллекции (списка или карты). Для списков значениями являются сами элементы.

{{ values({'1':'one', '2':'two'}) }}

Предыдущий пример распечатает [one, two].

slice

Эта функция возвращает подстроку или часть списка и ожидает три аргумента, где первый аргумент — список или строка, а второй и третий — числа.

{{ slice("123", 1, 1) }}

{{ slice([1, 2, 3], 0, 2) }}

Второй аргумент — индекс позиции первого символа или элемента списка (включительно), а третий — длина ожидаемой подстроки или подсписка. Как показано на предыдущих двух примерах, они распечатают "2" и [1, 2] соответственно. Обратите внимание, что функция безопасна для выходящих за размеры значений, например:

{{ slice("123", 2, 3) }}

{{ slice("123", 5, 1) }}

Предыдущие примеры все еще распечатает подстроки "3" и "" соответственно.

sort

Эта функция сортирует указанный список и принимает до двух аргументов:

• Список для сортировки;
• (Опционально) Режим сортировки:
  • ASC - Сортировка по возрастанию (по-умолчанию);
  • DESC - Сортировка по убыванию;
  • NUM_ASC - Сортировка чисел по возрастанию;
  • NUM_DESC - Сортировка чисел по убыванию.

{{ sort(['2', '1', '10']) }}

Предыдущий пример использует сортировку по возрастанию ASC (по-умолчанию, если не указана другая) и распечатает [1, 10, 2].

Вы могли заметить, что результат предыдущего примера немного странный, но это потому, что сортируются строки, а не числа. Это основное отличие обычных типов сортировки от NUM_*. Обычные ASC/DESC отсортируют элементы списка без учета их типа данных, когда NUM_ASC/NUM_DESC отсортируют их числовые представления.

Элементы списка, которые не могут быть представлены числами, будут исключены из результата:

{{ sort(['2', '1', '10', 'NotANumber'], 'NUM_ASC') }}

Предыдущий пример распечатает [1, 2, 10].

shuffle

Эта функция произвольно перемешает указанный список.

{{ shuffle(['A', 'B', 'C', 'D']) }}

Предыдущий пример распечатает список с произвольной последовательностью из A, B, C, D.

Дата и время

date

Эта функция форматирует переданную дату в указанный формат. Функция принимает от одного до трёх аргументов:

• Объект даты, временная метка или строка 'now' если нужна текущая дата;
• (Опционально) Формат даты на базе SimpleDateFormat из языка Java. Более подробно можно ознакомиться здесь;
• (Опционально) Часовой пояс даты в формате TZ Database. Если не указан, используется часовой пояс сервера, настроенный в панели управления.

{{ date('now', 'EEE, d MMM yyyy HH:mm:ss z', 'Europe/Moscow') }}

Предыдущий пример распечатает текущую дату в московском времени, например сб, 11 апр. 2020 15:27:38 MSK.

calendar

Эта функция создает новый экземпляр DateTime. Принимает до двух опциональных аргументов:

1. Значение, преобразуемое в дату согласно правилам конвертации:

   • Строка 'now' для получения текущей даты;
   • Временная метка числом (Unix timestamp);
   • Строка даты в формате ISO 8601.

   Если параметр не указан, используется текущая дата.

2. Часовой пояс даты в формате TZ Database. Если не указан, используется часовой пояс сервера, настроенный в панели управления.

{{ calendar('now', 'Europe/Moscow') }}

Предыдущий пример распечатает текущую дату в московском времени, например сб, 11 апр. 2020 15:27:38 MSK.

Так как функция возвращает экземпляр DateTime, вы можете использовать его функциональность, например:

{% set currentDate = calendar('now', 'Europe/Moscow') %}
{% set fiveHours = currentDate.plusHours(5) %}
{{ currentDate }}
{{ fiveHours }}

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

сб, 11 апр. 2020 15:27:38 MSK
сб, 11 апр. 2020 20:27:38 MSK

duration

Эта функция форматирует указанный интервал времени в читаемый формат. Принимает до двух аргументов:

• Интервал в миллисекундах;
• (Опционально) Максимальное количество единиц времени. По умолчанию 2.

{{ duration(3650, 2) }}

Предыдущий пример распечатает 3 сек. 650 мс.

Взаимодействия

reaction

Эта функция добавит к результирующему сообщению шаблона реакцию с указанной эмоцией. Принимает единственный аргумент с эмоцией в следующих форматах:

• 🦊 — Unicode-символ эмоции;
• :fox_face: — название эмоции, включая стандартные и пользовательские на сервере;
• <a:foxwaggy:695917473874051112> — код пользовательской эмоции.

{% do reaction(':fox_face:') %}

Бонусная возможность

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

Компоненты сообщений

button

Эта функция добавит кнопку к результирующему сообщению шаблона. Принимает шесть строковых аргументов.

• Первый аргумент — стиль кнопки:
  • LINK — Кнопка-ссылка серого цвета, используется для открытия веб-страниц;
  • PRIMARY — Основная кнопка синего цвета, обычно используется для подтверждения какой-либо операции;
  • SECONDARY — Вторичная кнопка серого цвета, используется как отмена или для редко используемых операций;
  • SUCCESS — Кнопка зелёного цвета, используется для выполнения какой-либо положительной операции;
  • DANGER — Кнопка красного цвета, используется для выполнения какой-либо деструктивной операции;
• Второй аргумент — URL для кнопки-ссылки, для остальных видов кнопок уникальный идентификатор;
• Третий аргумент — наименование кнопки;
• Четвёртый аргумент — эмоция (опциональная, можно указать null);
• Пятый аргумент — UUID Действия для выполнения (для всех видов кнопок, кроме кнопки-ссылки);
• Шестой опциональный аргумент - логический признак того, отключена ли кнопка.

{% do button('LINK', 'https://juniper.bot/', 'Website', '🦊') %}
{% do button('PRIMARY', 'acceptBtn', 'Подтвердить', '✅', 'b39297ea-cc2d-4f88-a475-d4a9df94cb99') %}
{% do button('PRIMARY', 'acceptBtn', 'Accept (Disabled)', '✅', 'b39297ea-cc2d-4f88-a475-d4a9df94cb99', true) %}

Внимание

Кнопки, выполняющие Действия, то есть все стили кнопок, кроме кнопок-ссылок, доступны только в пользовательских командах.

select_menu

Эта функция добавит меню выбора к результирующему сообщению шаблона. Принимает пять строковых аргументов.

• Первый аргумент — тип меню выбора:
  • STRING — Меню выбора строк;
  • USER — Меню выбора участников;
  • ROLE — Меню выбора ролей;
  • MENTIONABLE — Меню выбора участников и ролей;
  • CHANNEL — Меню выбора каналов;
• Второй аргумент — уникальный идентификатор;
• Третий аргумент — текст-заглушка если ничего не указано;
• Четвёртый аргумент — UUID Действия для выполнения;
• Пятый опциональный аргумент - логический признак того, отключено ли меню.

{% do select_menu('CHANNEL', 'selectedChannels', 'Выбери каналы', 'b39297ea-cc2d-4f88-a475-d4a9df94cb99')
      .withMinValues(2)
      .withMaxValues(3)
      .withChannelTypes(['VOICE', 'TEXT']) %}

{% do select_menu('STRING', 'selectedSpecies', 'Кто ты?', 'b39297ea-cc2d-4f88-a475-d4a9df94cb99')
      .addOption('Выдра', 'otterOption', ':otter:')
      .addOption('Лиса', 'foxOption', ':fox_face:')
      .withDefaultOption('foxOption') %}

{% do select_menu('MENTIONABLE', 'selectedEntry', 'Выбери роль или участника', 'b39297ea-cc2d-4f88-a475-d4a9df94cb99', true)
      .withDefaultOptions(['310848622642069504']) %}

Бонусная возможность

Данная функция доступна только на сервере с бонусом за поддержку!

Внимание

Меню доступны только в пользовательских командах.

components_row

Эта функция добавит новый ряд компонентов сообщений для всех последующих вызовов функций button.