Руководство по интеграции Nim IDE

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

Этот документ поможет вам ознакомиться с доступными вариантами. Если вы хотите посмотреть практические примеры поддержки nimsuggest, вы можете изучить уже доступные различные интеграции с редакторами.

Установка

Nimsuggest является частью ядра Nim. Скомпилируйте его с помощью:

koch nimsuggest

Вызов nimsuggest

Запустите его с помощью nimsuggest --stdin --debug myproject.nim. Nimsuggest — это сервер, который обрабатывает запросы, относящиеся к myproject. Есть некоторая поддержка, позволяющая отправлять случайные файлы .nim, которые не являются частью myproject, в Nimsuggest, но обычно запрос относится к модулям/файлам, которые являются частью myproject.

--stdin означает, что Nimsuggest читает запрос из stdin. Это отлично подходит для тестирования и работы с ним, но для коммуникации с редактором через сокеты более разумно, поэтому это значение по умолчанию. По умолчанию он прослушивает порт 6000.

Указание местоположения запроса

Затем Nimsuggest ожидает запросов для обработки. Запрос состоит из загадочной 3-буквенной "команды" def или con или sug или use , за которой следует местоположение. Местоположение запроса состоит из:

file.nim

Это имя модуля или файла подключаемого файла, на который ссылается запрос.

dirtyfile.nim

Это необязательно.

Параметр file достаточен для статического анализа, но IDE обычно имеют несохраненные буферы, где пользователь может все еще находиться в процессе ввода строки. В таких ситуациях IDE может сохранить текущее содержимое в временный файл, а затем использовать опцию dirtyfile.nim , чтобы указать Nimsuggest, что foobar.nim следует брать из temporary/foobar.nim.

line: Целое число с номером строки, которую вы собираетесь запросить. Для компилятора строки начинаются с 1.
col: Целое число со столбцом, который вы собираетесь запросить. Для компилятора столбцы начинаются с 0.

Определения

Команда def Nimsuggest выполняет запрос об определении конкретного символа. Если доступно, Nimsuggest ответит типом, файлом исходного кода, информацией о строке/столбце и другими дополнительными данными, если они доступны, такими как строка документации. С этой информацией IDE может предоставить типичное действие Перейти к определению, где пользователь помещает курсор на символ или выбирает его мышкой, и переходит к месту, где расположен символ.

Поскольку Nim реализован на Nim, одним из приятных аспектов этой функции является то, что любой пользователь с IDE, поддерживающей ее, может быстро переходить по реализации стандартной библиотеки и точно видеть, что делает процедура, изучать язык и видеть реальные примеры написания/реализации конкретных функций.

Nimsuggest всегда отвечает одним определением или ничем, если не может найти соответствующий символ в запрошенной позиции.

Предложения

Команда sug Nimsuggest выполняет запрос о возможных символах завершения в какой-то точке файла.

Типичный сценарий использования для этого варианта заключается в том, чтобы вызвать его после того, как пользователь ввел точку для синтаксиса вызова методов объектно-ориентированного программирования. Nimsuggest попытается вернуть предложения, отсортированные сначала по области видимости (от внутренней к внешней), а затем по имени элемента.

Контекст вызова

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

Использование символов

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

Для этого типа запроса IDE, скорее всего, проигнорирует всю информацию о типе/подписи, предоставленную Nimsuggest, и сконцентрируется на имени файла, строке и столбце позиции множества возвращенных ответов.

Парсинг вывода nimsuggest

Вывод Nimsuggest всегда возвращается в строках, разделенных символами табуляции (\t). Значения каждого столбца:

Три символа, указывающие тип возвращенного ответа (например, def для определения, sug для предложения и т. д.).
Тип символа. Это может быть skProc, skLet, и практически любой из перечислений, определенных в модуле compiler/ast.nim.
Полный квалифицированный путь к символу. Если вы запрашиваете символ, определенный в файле proj.nim, это будет иметь вид proj.symbolName.
Тип/подпись. Для переменных и перечислений это будет содержать тип символа, для процедур, методов и шаблонов это будет содержать полную уникальную подпись (например, proc (File)).
Полный путь к файлу, содержащему символ.
Строка, где находится символ в файле. Номера строк начинаются с 1.
Столбец, где находится символ в файле. Номера столбцов начинаются с 0.
Строка документации для символа, если она доступна, или пустая строка. Чтобы отличить строку документации от конца ответа, строка документации всегда предоставляется в двойных кавычках, и если строка документации занимает несколько строк, все последующие строки строки документации будут начинаться с пробела для визуального выравнивания с открывающей кавычкой.

Кроме того, вы не найдете символов \n без нарушения формата одного ответа на строку. Вместо этого вам нужно будет разобрать последовательности в формате \xHH, где HH — шестнадцатеричное значение (например, новые строки генерируют последовательность \x0A).