Перейти к содержанию

Синтаксис

Описание синтаксиса шаблонного движка JuniperBot.

Островки кода#

В самом простом виде шаблон представляет собой текст, который будет отправлен сообщением в исходном виде как есть.

Однако, вся суть шаблонизатора в возможности форматировать этот текст заданным образом, использовать внутри него управляющие конструкции (условия или циклы) и даже выполнять некоторые действия. Для этого используются так называемые "островки кода".

Код#

Островки кода всегда начинаются с {% и заканчиваются %}, очень просто. Внутри таких островков кода используются теги, в числе которых есть управляющие конструкции (условия, циклы), объявление переменных и многое другое.

{% tag %}

Каждый островок кода может выполнять только одну какую-либо операцию или объявлять часть управляющей конструкции.

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

Контроль символов пробела#

С синтаксисом островков кода связана еще одна синтаксическая возможность, называемая контролем символов пробела. Эта возможность позволяет убрать все пробелы и переводы строк перед или после островков кода. Для достижения этого, добавьте символ минуса - в начало или конец островка кода. Например:

{% if (1 == 1) -%}     текст     {%- endif %}

Такой код генерирует сообщение текст без пробелов вокруг этого слова.

Вывод выражений#

В шаблонном движке JuniperBot существует только один способ вывести значение переменной или результат вычисления какого-либо выражения. Это достигается с помощью операции вывода, как показано ниже:

{{ выражение }}

Обратите внимание, что островки вывода также поддерживают контроль символов пробела:

{{- выражение -}}

Комментарии#

В шаблонном движке JuniperBot можно добавить комментарий, который не будет распечатан в результирующем сообщении:

{# Это содержимое комментария.
И оно может быть многострочным. #}

Опять же, здесь также поддерживается контроль символов пробела:

{#- Ваш замечательный комментарий -#}

Выражения#

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

Идентификаторы#

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

Доступ к значениям списков и карт#

Всякий раз, когда нужно получить доступ к какому-либо элементу списка или значению какого-то ключа карты, используется выражение доступа по индексу элемента списка или названию ключа. Помните, что индексы списков всегда начинаются с 0.

list[0]
map["key1"]

Ключевые слова#

В шаблонном движке JuniperBot есть набор зарезервированных ключевых слов. Данные ключевые слова используются для построения более сложных конструкций в шаблонах. Ниже перечислены все зарезервированные ключевые слова:

  • set
    		•
  • in
    		•
  • global
    		•
  • as
    		•
  • if
    		•
  • do
    		•
  • elseif
    		•
  • verbatim
    		•
  • else
    		•
  • filter
    		•
  • endif
    		•
  • endfilter
    		•
  • for
    		•
  • null
    		•
  • endfor
    		•
  • is
    		•
  • true
    		•
  • not
    		•
  • false
    		•
  • with
    		•
  • empty
    		•
  • require
    		•
  • return
    		•
  • returning
    		•

    Унарные операторы#

    Унарные операторы по определению нуждаются только в одном аргументе, шаблонизатор JuniperBot содержит только два встроенных унарных оператора: not и -.

    Символ Описание Приоритет1 Пример
    - Меняет знак 5 -(-1) выводит 1
    not Отрицание 10 not false выводит true
    not true выводит false

    Логические операторы#

    Шаблонный движок JuniperBot поддерживает следующие логические операторы:

    Символ Приоритет1 Описание Пример
    . 1 Получение доступа к свойствам объектов member.id выводит идентификатор участника
    ^ 3 Возводит чило в степень 2 ^ 3 выводит 8
    * 5 Умножение двух значений 2.2 * 2.2 выводит 4.84
    ** 5 Целочисленное умножение двух значений 2.2 ** 2.2 выводит 4
    / 5 Деление двух значений 5.0 / 2.0 выводит 2.5
    // 5 Деление двух значений с округлением до целого 5.0 // 2.0 выводит 3
    % 5 Получение остатка от деления 5 % 2 выводит 1
    + 10 Суммирует два значения 5 + 2 выводит 7
    - 10 Вычитает два значения 5 - 2 выводит 3
    ~ 12 Объединяет две строки "5" ~ "2" выводит "52"
    < 15 Сравнивает два значения, проверяя меньше ли первое значение второе 1 < 2 выводит true 1 < 1 выводит false
    <= 15 Сравнивает два значения, проверяя меньше или равно ли первое значение второму 2 <= 2 выводит true 2 < 1 выводит false
    > 15 Сравнивает два значения, проверяя больше ли первое значение второго 2 > 1 выводит true 2 > 2 выводит false
    >= 15 Сравнивает два значения, проверяя больше или равно ли первое значение второму 2 >= 2 выводит true 2 >= 3 выводит false
    in 15 Проверяет, содержится ли значение в списке 5 in [2] выводит false
    == 20 Проверяет два значения на их равенство true == false выводит false false == false выводит true
    != 20 Проверяет два значения на их неравенство true != false выводит true false != false выводит false
    and 25 Оператор конъюнкции (И) true and false выводит false true and true выводит true
    or 25 Оператор дизъюнкции (ИЛИ) true or false выводит true false or false выводит false
    | 30 Использует первый аргумент как параметр к названию функции во втором аргументе -5 | abs выводит 5

    Тернарный оператор#

    Поддерживается стандартный тернарный оператор, позволяющий выбрать одно из двух значений в зависимости от результата вычисления логического выражения. Например:

    {{ <выражение> ? 1 : 2 }}

    Такой блок выведет 1, если результат вычисления выражения равен true и 2, если false.

    Оператор Элвиса#

    Оператор Элвиса возвращает результат вычисления первого выражения в случае, если оно имеет значение истины согласно Конвертации типов, в противном случае возвращает результат вычисления второго выражения.

    {{ <выражение A> ?: <выражение Б> }}

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

    Оператор присваивания#

    Оператор присваивания (так называемый моржовый оператор :=) позволяет одновременно присвоить значение переменной и вернуть его. 

    {{ <переменная> := <выражение> }}
    Моржик вычисляет значение выражения, записывает его в переменную и возвращает это же значение.

    {{ result := 1 + 2 }}
{{ result }}

    Пример выше распечатает "3" два раза. Первая тройка - результат вычисления выражения присваивания, а вторая - значение переменной result в результате вычисления этого выражения.

    Этот оператор очень полезен для сокращения кода в некоторых ситуациях. Например, представим простой шаблон с использованием обычного тэга set для присваивания переменной: 

    {% set amount = 5 %}
{% if amount > 0 %}
У Пети есть целых {{ amount }} яблок!
{% endif %}

    Этот шаблон можно сократить таким образом: 

    {% if (amount := 5) > 0 %}
У Пети есть целых {{ amount }} яблок!
{% endif %}

    Приоритет

    У оператора присваивания самый низкий приоритет и это следует учитывать.

    Если выражение сравнения в примере выше было бы записано как amount := 5 > 0, то значение переменной amount было бы не 5, а true, поскольку у оператора сравнения более высокий приоритет и он вычисляется первым. Именно поэтому для изолирования выражения присваивания используются скобки.

    Сам по себе оператор присваивания не может объявлять глобальные переменные, но если переменная с указанным названием уже существует и она является глобальной, то оператор присваивания обновит значение этой переменной, оставив её при этом глобальной.

    Тестовые выражения#

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

    Название Описание Пример
    Null Проверяет, является ли значение 1 is null выводит false
    Divisible Проверяет, можно ли поделить первое значение на второе 2 is divisible by 1 выводит true
    Same As Проверяет, являются ли два объекта буквально одним и тем же объектом 1 is same as 2 выводит false
    Function based Проверяет результат вычисления этой функции над аргументом. Допустимые названия функций перечислены.
    Полезно при использовании совместно с функциями, для проверки типа.    		 4 is defined выводит true;
    'test' is number выводит false.
    Is Not В любых конструкциях выше можно использовать отрицание is not. 4 is not defined выводит false

    Оператор выбора#

    Оператор выбора используется для получения доступа к свойству какого-либо объекта или вызова функции этого объекта. Допустимые свойства и функции описаны в разделах Переменные и Типы данных.

    guild.name
channel.sendMessage('моё сообщение!')

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

    1. Приоритет оператора определяет в какой последовательности оператор вычисляется в составе выражений. Чем ниже значение, тем выше приоритет. ↩↩