Функции

Описание всех глобальных функций шаблонного движка JuniperBot

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

`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 позволяет форматировать указанное число с указанными символами для разделителей группы разрядов и дробной части, а также с указанным количеством дробных цифр. Эта функция ожидает как минимум один аргумент и до четырех. Список аргументов в том порядке, как они ожидаются функцией:

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

{{ 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 включительно.

`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 соответственно.

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

`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].

`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. Принимает до двух аргументов:

(Опционально) Объект даты, временная метка или строка 'now' или не указывается если нужна текущая дата;
(Опционально) Часовой пояс даты в формате 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) %}

Внимание

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

Функции

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

defined#

even#

odd#

iterable#

number#

empty#

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

abs#

round#

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

number_format#

capitalize#

format#

lower#

upper#

replace#

split#

title#

trim#

startsWith#

endsWith#

contains#

plural#