1 of 26

Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

Университет ИТМО

Санкт-Петербург, 2023

Студент:

Руководитель:

Бережко Екатерина Игоревна

Пости Иван Маркович

2 of 26

Mermaid.js

[1] GitLab, GitHub, GitBook, MS Azure, Confluence - https://mermaid.js.org/ecosystem/integrations.html

  • Mermaid.js - язык для построения диаграмм
  • Широко используется в процессе разработки ПО[1]
  • Имеет официальный редактор - Mermaid Live Editor
  • Отображается в превью Markdown Plugin для IntelliJ IDE

2/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

3 of 26

Примеры диаграмм Mermaid.js

3/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

flowchart

A --> B

C -.-> D

sequenceDiagram

A ->> B: Text

B -->> A: Text

4 of 26

Поддержка в IntelliJ IDE

  • Поддерживается отображение диаграмм в превью Markdown
  • Отсутствуют автодополнение, подсветка и другая стандартная для IDE функциональность
  • Не поддерживаются форматы .mmd и .mermaid
  • Отсутствует возможность поддержки актуальной версии

​

4/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

5 of 26

Поддержка языка в плагине для IntellIJ

  • Лексический анализатор (лексер)
    • Реализуется с помощью JFlex
  • Синтаксический анализатор (парсер)
    • Реализуется с помощью Grammar-Kit[2]
  • PSI (Program Structure Interface) - синтаксическая и семантическая модель кода

[2] https://github.com/JetBrains/Grammar-Kit

5/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

6 of 26

Подсветка синтаксиса и ошибок

  • Подсветка токенов
  • Подсветка синтаксических ошибок
  • Инспекции и аннотаторы
    • Анализ семантики кода
    • Предоставляют исправления

​

6/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

7 of 26

Разрешение ссылок

  • Идентификаторы Mermaid.js могут иметь ноль и более деклараций
  • Symbol API
    • Символ - это семантический элемент языковой модели
  • Поддерживается
    • Переименование
    • Поиск
    • Быстрая навигация

​

​

7/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

classDiagram

Animal <|-- Duck

class Duck {

+String color

+swim()

+quack()

}

Any <|-- Duck

class Duck {

+int size

}

8 of 26

Дополнение, форматирование и сворачивание кода

  • Контекстное автодополнение по:
    • ключевым словам
    • шаблонным конструкциям языка
    • идентификаторам
  • Сворачивание
    • задает регионы сворачивания для семантических блоков
  • Форматирование
    • задается построением дерева блоков с атрибутами
    • ограничивает пробельные символы между элементами

8/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

9 of 26

Лексер и парсер Mermaid.js

  • Не весь текст покрыт токенами
  • Пробельные символы не всегда выделены в отдельные токены
  • Использование магических чисел
  • Грамматика не всегда отражает синтаксическую структуру
  • Лексер и парсер используют неподдерживаемые в Grammar-Kit конструкции

stateDiagram

State1: The state

note right of State1 : The note

9/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

10 of 26

Цель и задачи

Цель: Реализовать поддержку языка Mermaid.js с помощью плагина для IDE на базе платформы IntelliJ

​

Задачи:

  • Переработать лексер и парсер Mermaid.js
  • Реализовать функциональность, присущую языковым плагинам
  • Поддержать отображение диаграмм в файлах .mmd и .mermaid и улучшить отображение в Markdown файлах
  • Разработать тесты для проверки реализованной функциональности

10/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

11 of 26

Переработка лексера и парсера

  • Лексер:
    • Реализован с помощью JFlex
    • Правила для выделения токенов были переработаны на основе выявленных требований
    • Восстанавливается от ошибок
  • Парсер:
    • Использует парсер-генератор Grammar-Kit
    • Генерирует синтаксические деревья с единообразной структурой для всех диаграмм

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

11/14

12 of 26

Реализация подсветки синтаксиса и ошибок

  • Реализованы подсветка токенов и синтаксических ошибок
  • Выявлено более 20 случаев требующих аннотирования, например:
    • Верификация Git диаграмм
    • Проверка отображения generic типов в диаграмме классов

​

12/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

13 of 26

Функциональность реализованного плагина

  • Подсветка синтаксиса и ошибок
  • Автодополнение кода
    • > 150 дополнений ключевых слов
    • > 30 дополнений по шаблонам
  • Форматирование кода
  • Сворачивание кода
  • Инспекции кода и предлагаемые исправления
  • Поиск, навигация и переименование идентификаторов
  • Отображение в Markdown и .mmd файлах

13/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

14 of 26

Результаты

  • Переработаны лексер и парсер Mermaid.js
  • Реализована функциональность, присущая языковым плагинам
    • Подсветка синтаксиса и ошибок
    • Автодополнение
    • Форматирование и сворачивание кода
    • Инспекции
    • Поиск, навигация и переименование идентификаторов
  • Поддержано отображение диаграмм в файлах .mmd и .mermaid и улучшено отображение в Markdown файлах
  • Разработаны тесты для проверки реализованной функциональности
  • Плагин был опубликован и широко используется

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

14/14

15 of 26

Mermaid IntelliJ IDE Plugin

15/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

Mermaid IntelliJ IDE Plugin on JetBrains Marketplace

https://plugins.jetbrains.com/plugin/20146-mermaid

16 of 26

Поддержка в Mermaid Live Editor

  • Подсветка синтаксиса без парсинга
  • Автодополнение не зависит от контекста
  • Отсутствуют автоматическое форматирование и другие “умные” функции ожидаемые от редактора

flowchart

direction LR

A --> LR

1

2

3

16/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

17 of 26

Реализация отображения диаграмм

  • Java Chromium Embedded Framework (JCEF) - фреймворк для встраивания браузеров на основе Chromium в другие JVM приложения[1]
  • Вместо встроенной функциональности предоставляется интерфейс для отображения в Markdown

17/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

[1] https://github.com/JetBrains/jcef

18 of 26

Лексер и парсер Mermaid.js

Реализованы с помощью Jison, который имеет ряд особенностей[1]:

  • Лексер будет использовать первое правило, которое соответствует входной строке (а не правило с самым длинным совпадением)
  • Jison поддерживает опережающие проверки:
    • Опережающая проверка (positive lookahead) (?=PATTERN)
    • Негативная опережающая проверка (negative lookahead) (?!PATTERN)
  • Поддерживает ленивые квантификаторы
  • Парсер поддерживает левую рекурсию

[1] https://github.com/zaach/jison/wiki/Deviations-From-Flex-Bison

18/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

19 of 26

Лексер Mermaid.js

<TEXT>\s*":"[^:\n;]+ {

this.popState();

yytext = yytext.substr(2).trim();

return 'TEXT';

}

note left of State1 : This is the note to the left

Входная строка:

Результат:

Правило:

19/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

20 of 26

Лексер Mermaid.js

<TEXT>\s*":"[^:\n;]+ {

this.popState();

yytext = yytext.substr(2).trim();

return 'TEXT';

}

note left of State1 : This is the note to the left

Входная строка:

Результат:

Правило:

20/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

21 of 26

Лексер Mermaid.js

note left of State1 : This is the note to the left

Входная строка:

Старый результат:

Новый результат:

21/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

22 of 26

Лексер Mermaid.js

actor A as Alice

22/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

23 of 26

Лексер Mermaid.js

A as Alice .

[^\->:\n,;]+?([\-]*[^\->:\n,;]+?)*?(?=((?!\n)\s)+as(?!\n)\s|[#\n;]|$)

MATCH 1: A

MATCH 2: as Alice .

23/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

24 of 26

Лексер Mermaid.js

A as Alice .

[^\->:\s,;]+?([\-]*[^\->:\s,;]+?)*?(?=((?!\n)\s)+as(?!\n)\s|[#\n;]|$)

MATCH 1: A

24/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

25 of 26

Лексер Mermaid.js

A as Alice .

[^\->:\s,;]+?([\-]*[^\->:\s,;]+?)*?

MATCH 1: A

MATCH 2: a

MATCH 3: s

MATCH 4: A

MATCH 5: l

MATCH 6: i …

​

25/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ

26 of 26

Лексер Mermaid.js

A as Alice .

[^\->:\s,;]+([\-]*[^\->:\s,;]+)*

MATCH 1: A

MATCH 2: as

MATCH 3: Alice

​

26/14

Бережко Екатерина | Реализация поддержки языка Mermaid.js для IDE на базе платформы IntelliJ