Приложение D: Шпаргалка

Для случая, когда вы знаете, чего хотите, и вам нужен синтаксис. Каждая строка — полная конструкция; главы и другие приложения связаны для полного контекста.

Модуль

service Orders {
    team: Commerce
    command Create
}                                                          // вид + имя + тело
service #ord001 Orders { ... }                        // со стабильным идентификатором
service AuthService in Platform { ... }               // привязать к родителю, объявленному в другом месте
service Notifications                                 // пустое тело, без фигурных скобок

См. гл. 4.

Интерфейс

command Authorize                                          // голый лист
command Authorize {                                        // с телом
    "Описание"
    timeout: "5s"
}
event PaymentEvents                                        // интерфейс события (async)
command Handler {                                          // подключение обработчика события
    subscribes: Orders.OrderEvents
}

См. гл. 5.

Фасет

facet OrdersResource {                                     // обобщённый фасет
    base: "/orders"
    command Post
}
resource OrdersResource { base: "/orders" }                // пользовательский вид фасета
facet Outer { facet Inner { ... } }                        // вложенные фасеты

resource — пользовательский вид, который команды определяют через type facet resource { ... }; стандартная библиотека поставляет только обобщённый facet. См. гл. 6 и гл. 16.

Процесс

process Checkout {
    Customer > Orders.Create                              // шаг: Caller > Callee.Interface
    Orders   > Payments.Authorize : "label"               // шаг с меткой

    if "stripe-customer" {                                // условие
        Payments > Stripe.Charge
    } else {
        Payments > PayPal.Charge
    }

    switch "outcome" {                                    // многопутевая ветвь
        ok       { Payments > Ledger.Record }
        declined { Orders   > Notifications.SendEmail }
    }

    parallel {                                            // параллельные ветви
        { Shipping > Notifications.SendEmail }
        { Shipping > Notifications.SendSMS  }
    }

    try {                                                 // путь ошибки
        Orders > Payments.Authorize
    } catch "declined" {
        Orders > Notifications.SendEmail
    }

    each item in Cart {                                   // итерация
        Cart > Inventory.Reserve
    }

    do SomeHelper(arg)                                    // вызов подпроцесса
}

process Checkout in Orders { ... }                        // привязать к модулю
subprocess EmitX(arg) { Orders > Ledger.Record }          // переиспользуемый помощник

См. гл. 7.

Проекция

view PaymentsLandscape {
    focus domain: Payments
    focus security.zone: PCI
    group by team
    layout elk                                             // elk | dagre | force | manual
    include "Payments.*", "Gateway.*"
    exclude "*.Internal"
    "Описание"
}

См. гл. 8.

Поля и метки

service X {
    team: Commerce                                         // значение-идентификатор
    repo.url: "https://..."                                // ключ через точку + строка
    version: 2                                             // число
    enabled: true                                          // логическое
    "Описание помещается здесь как голая строка."

    labels {
        domain: Orders
        security.zone: PCI
    }
}

См. гл. 9.

Описания

"Чистый markdown плюс два расширения.
**bold**, *italic*, ~~strike~~, `code`, [link](https://...), таблицы, списки.

[[#stable_id]] и [[Name]] ссылаются на другие декларации.
@labelPath подставляет значение метки из этого узла."

См. гл. 10.

Пакеты

name: acme.shop
version: "1.0.0"
widgets: "./widgets.js"

dependencies {
    acme.shared: "../shared"
}

use * from arch.modules
use database, frontend from arch.modules
use Database as ManagedDB from acme.shared
export use payments_provider from acme.payments

См. гл. 12.

Стабильные идентификаторы

service #pay001 Payments { ... }                      // ID модуля
type #t001 module service { ... }                     // ID типа
process #flow42 Checkout { ... }                           // ID процесса
view #v9 Landscape { ... }                                 // ID проекции
// Фасеты и интерфейсы НЕ несут ID.

См. гл. 13.

Декларации типов

type module service {
    required cascade team                                  // обязательное каскадирующее пустое поле
    required labels.domain                                 // обязательная пустая метка
    component metrics { command Emit }                     // преднаполненная под-декларация
    required database PrimaryStore                         // обязательная пустая под-декларация
    cascade widget: arch-service                      // каскадирующее поле по умолчанию
    append base                                            // поле в режиме append (составление пути/списка/объекта)
}

type service paymentsService { team: "Payments" }     // подтип
export type ...                                            // видим импортёрам

См. гл. 15-15.

Обязательные пустые слоты

// Два и только два способа закрыть унаследованный `required` слот:
field: value                                               // заполнить
drop field                                                 // удалить полностью

См. гл. 17.

Режимы распространения (задаются на типе)

Модификатор	Поведение
(нет) — локально	Остаётся там, где задано, не растекается
`cascade`	Растекается к потомкам; переопределение на ходу
`append`	Растекается и композируется (пути конкатенируются, списки добавляются, объекты сливаются)

Метки всегда каскадируют с семантикой переопределения; модификатор на метках не нужен (и не разрешён). См. гл. 18.

Уточнение / override / drop (единообразно на уровне типа и экземпляра)

// Уточнение — тот же вид или подтип, мёрджит:
component metrics { command EmitV2 }

// Override — переключение на вид не-подтип, нужно ключевое слово:
override database metrics { command Read }

// Drop — удалить полностью:
drop metrics
drop metrics.Emit                                          // удалить потомка

Набор операций против унаследованного required пустого слота:

Цель	Синтаксис
Уточнить до вида-подтипа, слот пустой	`required <subtype> Name`
Уточнить до вида-подтипа, заполнить	`<subtype> Name { ... }`
Переключить на вид не-подтип, слот пустой	`override required <new-kind> Name`
Переключить на вид не-подтип, заполнить	`override <new-kind> Name { ... }`
Заполнить, сохраняя унаследованный вид	`Name: value` или `Name { ... }`
Удалить полностью	`drop Name`

См. гл. 19.

Виджеты

widget: arch-service                                  // форма custom-element
widget.icon: server                                        // свойство виджета
widget.accent: "#34d399"

widget: "<div class='card'>{{name}}</div>"                 // форма встроенного шаблона
widget: """<archui-card>{{name}}</archui-card>"""          // тройные кавычки, сырая

См. гл. 20.

CLI

archlang validate <path>      # валидация; ненулевой код выхода при ошибках
archlang validate --watch <path>
archlang info <path>          # сводка по пакету
archlang check <path>         # валидация + производные проверки
archlang format <file.arch>   # каноническое форматирование (пробелы, отступы)
archlang format --check       # ненулевой код выхода, если форматирование что-то изменило бы
archlang format --diff        # вывести, что изменилось бы

См. гл. 21.

Встраивание просмотрщика

<archlang-viewer
    src="./diagram.arch"
    style="width: 100%; height: 480px"></archlang-viewer>

Размеры задаются через CSS (style, class); элемент не принимает атрибуты width/height. См. гл. 23.

Напоминание о раскладке файлов

my-project/
├── package.archspace                  # манифест (обязателен для именованного пакета)
├── widgets.js                         # регистрации custom-элементов (опционально)
├── kinds.arch                         # декларации типов
├── orders.arch                        # декларации экземпляров
└── packages/shared/                   # вложенный пакет (со своей границей)
    ├── package.archspace
    └── ...