Разработка основных режимов с tree-sitter

В этом разделе приведены общие рекомендации по разработке интеграции tree-sitter для основного режима.

Основной режим с поддержкой функций tree-sitter должен примерно соответствовать следующему шаблону:

(define-derived-mode woomy-mode prog-mode "Woomy"
  "A mode for Woomy programming language."
  (when (treesit-ready-p 'woomy)
    (setq-local treesit-variables ...)
    ...
    (treesit-major-mode-setup)))

treesit-ready-p автоматически выводит предупреждение, если условия для включения tree-sitter не выполнены.

Если основной режим tree-sitter использует общую настройку со своим «обычным» аналогом, можно создать «базовый режим», содержащий общую настройку, например:

(define-derived-mode woomy--base-mode prog-mode "Woomy"
  "An internal mode for Woomy programming language."
  (common-setup)
  ...)

(define-derived-mode woomy-mode woomy--base-mode "Woomy"
  "A mode for Woomy programming language."
  (native-setup)
  ...)

(define-derived-mode woomy-ts-mode woomy--base-mode "Woomy"
  "A mode for Woomy programming language."
  (when (treesit-ready-p 'woomy)
    (setq-local treesit-variables ...)
    ...
    (treesit-major-mode-setup)))

Функция: treesit-ready-p language &optional quiet

Эта функция проверяет выполнение условий для активации tree-sitter. Она проверяет, была ли Emacs собрана с поддержкой tree-sitter, не слишком ли велик размер буфера для обработки tree-sitter и доступна ли в системе грамматика для language (см. Грамматика языка Tree-sitter).

Эта функция выводит предупреждение, если tree-sitter не удаётся активировать. Если quiet равно message, предупреждение преобразуется в сообщение; если quiet равно t, предупреждение или сообщение не выводится.

Если выполнены все необходимые условия, функция возвращает не-nil; в противном случае она возвращает nil.

Функция: treesit-major-mode-setup

Эта функция активирует некоторые функции tree-sitter для основного режима.

В настоящее время она настраивает следующие функции:

• Если treesit-font-lock-settings (см. Раскраска шрифта на основе синтаксического анализатора) не равно nil, функция настраивает раскраску текста.
• Если treesit-simple-indent-rules или treesit-indent-function (см. Отступы на основе синтаксического анализатора) не равно nil, функция настраивает отступы.
• Если treesit-defun-type-regexp не равно nil, функция настраивает функции навигации для beginning-of-defun и end-of-defun. См. Перемещение по сбалансированным выражениям.
• Если treesit-defun-name-function не равно nil, функция настраивает функции add-log, используемые add-log-current-defun.
• Если treesit-simple-imenu-settings (см. Imenu) не равно nil, функция настраивает Imenu.
• Если treesit-outline-predicate (см. Вспомогательный режим Outline) не равно nil, функция настраивает вспомогательный режим Outline.
• Если sexp и/или sentence определены в treesit-thing-settings (см. Определяемые пользователем «вещи» и навигация), функция включает команды навигации для перемещения соответственно по sexp и предложениям, определяя такие переменные, как forward-sexp-function и forward-sentence-function.

Подробнее о встроенных функциях tree-sitter см. в разделах Раскраска шрифта на основе синтаксического анализатора, Отступы на основе синтаксического анализатора и Перемещение по сбалансированным выражениям.

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

Помимо beginning-of-defun и end-of-defun, Emacs предоставляет несколько дополнительных функций для работы с defun: treesit-defun-at-point возвращает узел defun в точке, а treesit-defun-name возвращает имя узла defun.

Функция: treesit-defun-at-point

Эта функция возвращает узел defun в точке или nil, если такой узел не найден. Она учитывает treesit-defun-tactic: если его значение равно top-level, функция возвращает defun верхнего уровня, а если его значение равно nested, возвращает непосредственно охватывающий defun.

Для работы этой функции требуется treesit-defun-type-regexp. Если оно равно nil, функция просто возвращает nil.

Функция: treesit-defun-name node

Эта функция возвращает имя defun узла node. Она возвращает nil, если у node нет имени defun, если node не является узлом defun или если node равен nil.

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

Если treesit-defun-name-function равно nil, эта функция всегда возвращает nil.

Переменная: treesit-defun-name-function

Если значение не равно nil, оно должно быть функцией, которая вызывается с узлом в качестве аргумента и возвращает имя defun этого узла. Функция должна иметь ту же семантику, что и treesit-defun-name: если узел не является узлом defun, если узел является узлом defun, но не имеет имени, или если узел равен nil, функция должна возвращать nil.