Gopls: Пассивные функции

На этой странице описаны базовые функции LSP, которые могут быть описаны как «пассивные», поскольку многие редакторы используют их для непрерывного предоставления информации о ваших исходных файлах без необходимости в специальном действии.

См. также Code Lenses, некоторые из которых аннотируют ваш исходный код дополнительной информацией и могут быть также рассмотрены как пассивные функции.

Hover

Запрос LSP textDocument/hover возвращает описание кода, находящегося в данный момент под курсором, например его имя, тип, значение (для константы), сокращённое объявление (для типа), комментарий документации (если есть) и ссылку на документацию символа на pkg.go.dev. Клиент может запросить либо обычный текст, либо Markdown.

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

Ссылки в документации: комментарий документации может ссылаться на другой символ с использованием квадратных скобок, например [fmt.Printf]. Наведение курсора на одну из таких ссылок в документации показывает информацию о ссылочном символе.

Информация о размере/смещении структуры: для объявлений типов структур наведение курсора на имя показывает размер структуры в байтах:

А наведение курсора на каждое имя поля показывает размер и смещение этого поля:

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

Кроме того, Hover показывает:

• класс размера структуры, который представляет собой количество байтов, фактически выделенных средой выполнения Go для одного объекта этого типа; и
• процент потраченного пространства из-за неоптимального порядка полей структуры, если эта цифра составляет 20% или выше:

В приведённой выше структуре правила выравнивания требуют, чтобы каждое из двух логических полей (1 байт) занимало полное слово (8 байт), что приводит к потере (7 + 7) / (3 * 8) = 58%. Размещение двух логических полей вместе позволило бы сэкономить слово. (В большинстве структур ясность важнее компактности, поэтому следует переставлять поля для экономии места только в тех структурах данных, которые были показаны профилированием как очень часто выделяемые.)

Директивы embed: наведение курсора на шаблон имени файла в директиве //go:embed, например *.html, показывает список имён файлов, на которые раскрывается символ подстановки.

Директивы linkname: //go:linkname директива создаёт псевдоним на другой символ на уровне компоновщика. Наведение курсора на директиву показывает информацию о другом символе.

Информация о наведении для символов из стандартной библиотеки, добавленных после Go 1.0, указывает версию Go, в которой был добавлен символ.

Настройки:

• Настройка hoverKind управляет подробностью документации.
• Настройка linkTarget задаёт базовый URI для ссылок на пакеты Go

Особенности:

• К сожалению, ограничение LSP заключается в том, что запрос Hover в настоящее время включает только позицию, но не выделение. Это означает, что невозможно запросить информацию о типе и методах, например, части выражения f(x) в более крупном выражении f(x).y. Пожалуйста, проголосуйте за microsoft/language-server-protocol#1466, если вы хотите, чтобы эта проблема была решена.

Поддержка клиентами:

• VS Code: включена по умолчанию. Отображает отрендеренный Markdown в панели рядом с курсором.
• Emacs + eglot: включена по умолчанию. Отображает краткое описание в области эха.
• Vim + coc.nvim: ??
• CLI: gopls definition file.go:#start-#end включает информацию из запроса Hover.

Подсказка сигнатуры

Запрос textDocument/signatureHelp в LSP возвращает информацию о самой внутренней функции, вызванной в позиции курсора или выделения, включая сигнатуру функции и имена, типы и документацию каждого параметра.

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

Скобки вызова не требуются, если курсор находится внутри идентификатора, обозначающего функцию или метод. Например, подсказка сигнатуры в once.Do(initialize‸) будет описывать initialize, а не once.Do.

Поддержка клиентами:

• VS Code: включена по умолчанию. Также известна как “подсказки параметров” в настройках IntelliSense. Отображает сигнатуру и комментарий документации рядом с информацией о наведении.
• Emacs + eglot: включена по умолчанию. Отображает сигнатуру в области эха.
• Vim + coc.nvim: ??
• CLI: gopls signature file.go:#start-#end

Выделение документа

Запрос LSP textDocument/documentHighlight сообщает о наборе диапазонов исходного кода, которые должны быть выделены в зависимости от текущей позиции курсора или выделения, чтобы подчеркнуть их взаимосвязь.

Каждая из следующих частей синтаксиса образует набор, так что если вы выберете любой один элемент, gopls выделит весь набор:

• каждый идентификатор, который ссылается на тот же символ (как на снимке экрана ниже);
• именованная переменная результата и все соответствующие операнды инструкций return;
• токены for, break и continue одного и того же цикла;
• токены switch и break одного и того же оператора switch;
• ключевое слово func функции и все её инструкции return.

Более одного из этих правил может быть активировано одним и тем же выделением, например, идентификатором, который также является операндом возврата.

Различные вхождения одного и того же идентификатора могут быть окрашены по-разному, чтобы различать ссылки на переменную символа, которые являются «чтением» и «записью».

Поддержка клиентами:

• VS Code: включена по умолчанию. Активируется при перемещении курсора или одинарном щелчке. (Примечание: двойной щелчок активирует простое синтаксически независимое текстовое совпадение.)
• Emacs + eglot: включена по умолчанию. Активируется при перемещении курсора или выделении.
• Vim + coc.nvim: ??
• CLI: gopls signature file.go:#start-#end

Подсказка вставки

Запрос LSP textDocument/inlayHint возвращает набор аннотаций, которые вставляются в текущий файл, чтобы раскрыть скрытую информацию.

Примеры:

• В вызове функции f(1, 2) подсказки предоставляют имена параметров (parameterNames), как показано на снимке экрана выше.
• В вызове дженерической функции подсказки предоставляют аргументы типа (functionTypeParameters).
• В присваивании x, y = 1, 2 подсказки предоставляют типы переменных (assignVariableTypes).
• В литерале структуры, таком как Point2D{1, 2}, подсказки предоставляют имена полей (compositeLiteralFields).
• В вложенном составном литерале T{{...}} подсказка предоставляет тип внутреннего литерала, {...} (compositeLiteralTypes).
• В цикле for k, v := range x {} подсказки предоставляют типы переменных k и v (rangeVariableTypes).
• Для константного выражения (возможно, с использованием iota) подсказка предоставляет его вычисленное значение (constantValues).

См. Подсказки вставки для полного списка с примерами.

Настройки:

• Настройка hints указывает желаемый набор подсказок. Чтобы уменьшить отвлекающие факторы, её значение по умолчанию — пустая карта. Чтобы включить подсказки, добавьте один или несколько идентификаторов выше в карту подсказок. Например:

  <code class="language-json5">"hints": {"parameterNames": true}
  </code>

Поддержка клиентами:

• VS Code: кроме значения конфигурации hints, VS Code предоставляет графическое меню конфигурации (“Preferences: Open Settings (UI)” — найдите “Go Inlay Hints”) для каждого поддерживаемого типа подсказки вставки.
• Emacs + eglot: отключено по умолчанию. Требуется M-x eglot-inlay-hints-mode плюс конфигурация, описанная здесь
• Vim + coc.nvim: ??
• CLI: не поддерживается

Семантические токены

Запрос LSP textDocument/semanticTokens сообщает информацию обо всех токенах в текущем файле или его части. Клиент может использовать эту информацию для предоставления подсветки синтаксиса, которая передаёт семантические различия между, например, функциями и типами, константами и переменными, или функциями библиотеки и встроенными функциями.

Клиент должен указать наборы типов и модификаторов, представляющих интерес.

Gopls сообщает следующие типы токенов:

• "comment": комментарий
• "function": функция
• "keyword": ключевое слово
• "label": метка управления (не стандартный тип LSP)
• "macro": токены text/template
• "method": метод
• "namespace": имя импортированного пакета
• "number": числовой литерал
• "operator": оператор
• "parameter": переменная параметра
• "string": строковый литерал
• "type": имя типа (а также другие использования)
• "typeParameter": параметр типа
• "variable": var или const (см. модификатор readonly)

Gopls также сообщает следующие стандартные модификаторы:

• "defaultLibrary": предварительно объявленные символы
• "definition": объявляющий идентификатор символа
• "readonly": для констант

а также эти нестандартные модификаторы, каждый из которых представляет конструктор верхнего уровня для типа каждого символа:

• "array"
• "bool"
• "chan"
• "interface"
• "map"
• "number"
• "pointer"
• "signature"
• "slice"
• "string"
• "struct"

Настройки:

• Настройка semanticTokens определяет, будет ли gopls отвечать на запросы семантических токенов. Эта опция позволяет пользователям отключить семантические токены даже в том случае, если их клиент не предоставляет никакого управления этой функцией на стороне клиента. Поскольку алгоритм семантических токенов gopls зависит от проверки типов, что добавляет ощутимую задержку, эта функция в настоящее время отключена по умолчанию, чтобы избежать задержки в подсветке синтаксиса; см. https://go.dev/issue/#45313, https://go.dev/issue/#47465.
• Экспериментальные настройки noSemanticString и noSemanticNumber заставляют сервер исключать типы string и number из ответа, поскольку некоторые клиенты могут выполнять более цветную подсветку этих токенов; см. https://go.dev/issue/45753.

Поддержка клиентов:

• VS Code: См. Semantic Highlighting Guide.
• Emacs + eglot: Не поддерживается; см. joaotavora/eglot#615.
• Vim + coc.nvim: ??
• CLI: gopls semtok file.go

Folding Range

Запрос LSP textDocument/foldingRange сообщает список регионов в текущем файле, которые могут быть независимо свернуты или развернуты. Например, может быть удобно свернуть большие комментарии или функции при изучении некоторого кода, чтобы большая часть кода помещалась на одном экране.

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

Поддержка клиентов:

• VS Code: отображается в левом поле. Переключайте маркеры (∨ и >), чтобы свернуть или развернуть.
• Emacs + eglot: не поддерживается.
• Vim + coc.nvim: ??
• CLI: gopls folding_ranges file.go

Ссылка на документ

Запрос LSP textDocument/documentLink использует эвристику для извлечения URL-адресов из комментариев документации и строковых литералов в текущем файле, чтобы клиент мог отображать их как кликабельные ссылки.

Помимо явных URL-адресов, gopls также преобразует строковые литералы в инструкциях импорта в ссылки на документацию pkg.go.dev для импортируемого пакета.

Настройки:

• Настройка importShortcut определяет, какой тип ссылки возвращается для инструкции import.
• Настройка linkTarget указывает базовый URI для ссылок на Go-пакеты.

Поддержка клиентов:

• VS Code: При наведении курсора на ссылку отображается всплывающее окно «Follow link (cmd+click)».
• Emacs + eglot: в настоящее время не используется.
• Vim + coc.nvim: ??
• CLI: gopls links file.go

Исходные файлы этой документации можно найти в golang.org/x/tools/gopls/doc.