Препроцессор

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

Переменные

Имя переменной начинается с $. Значение — строка, число или JSON.

@startuml
!$service = "Сервис заказов"
!$timeout = 30
participant Клиент
participant "$service" as S
Клиент -> S : запрос (тайм-аут $timeout с)
@enduml

!$x ?= "значение" присваивает значение, только если переменная ещё не задана.

Условия

@startuml
!$detailed = %true()
Клиент -> API : POST /orders
!if ($detailed)
API -> DB : INSERT order
API -> Kafka : OrderCreated
!endif
API --> Клиент : 201 Created
@enduml

Также доступны !elseif, !else; !ifdef и !ifndef проверяют, задана ли переменная.

Циклы

!foreach $x in $массив … !endfor перебирает элементы JSON-массива, !while условие … !endwhile — цикл с условием.

@startuml
!$services = ["Заказы", "Оплата", "Доставка"]
!foreach $s in $services
component "$s"
!endfor
!$i = 1
!while $i <= 3
note "Шаг $i" as N$i
!$i = $i + 1
!endwhile
@enduml

Процедуры и функции

Процедура (!procedure) выводит строки диаграммы, функция (!function) возвращает значение (!return). Параметры могут иметь значения по умолчанию; аргументы с пробелами и не латинскими буквами пишутся в кавычках.

@startuml
!procedure $call($from, $to, $message = "запрос")
$from -> $to : $message
$to --> $from : ответ на «$message»
!endprocedure

!function $upper($text)
!return %upper($text)
!endfunction

$call("Клиент", "API")
$call("API", "БД", "SELECT")
note over Клиент : $upper("готово")
@enduml

Встроенные функции

Функция	Результат
%date("yyyy-MM-dd")	текущая дата в формате
%strlen($s), %substr($s, 0, 3), %strpos($s, "x")	работа со строками
%upper($s), %lower($s)	регистр
%newline()	перенос строки
%true(), %false(), %not($x)	логические значения
%intval("42"), %string(42)	преобразования
%size($json), %get_json_attribute(…)	работа с JSON

Подключение стандартной библиотеки

!include <папка/файл> подключает файл стандартной библиотеки (C4, ArchiMate, наборы значков). Подключение своих файлов и адресов (!include файл, !includeurl, !import) в «Помощнике SA» недоступно — общие куски оформляйте процедурами внутри диаграммы.

Устаревший синтаксис

Макросы !define и !definelong по-прежнему работают, но для новых диаграмм лучше использовать переменные и процедуры.