Руководство по интеграции 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 — это по сути фронтенд для компилятора Nim, поэтому --path флаги и файлы конфигурации могут использоваться для указания дополнительных зависимостей, таких как nimsuggest --stdin --debug --path:"dependencies" myproject.nim.

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

Затем 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.

Определения

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

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

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

Предложения

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

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

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

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

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

Команда Nimsuggest use перечисляет все использования символа в заданной позиции. 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).