mirror of
https://github.com/nim-lang/Nim.git
synced 2025-12-29 17:34:43 +00:00
175 lines
6.2 KiB
ReStructuredText
175 lines
6.2 KiB
ReStructuredText
.. default-role:: code
|
|
|
|
================================
|
|
Nim IDE Integration Guide
|
|
================================
|
|
|
|
:Author: Unknown
|
|
:Version: |nimversion|
|
|
|
|
.. contents::
|
|
|
|
|
|
Nim differs from many other compilers in that it is really fast,
|
|
and being so fast makes it suited to provide external queries for
|
|
text editors about the source code being written. Through the
|
|
`nimsuggest` tool, any IDE
|
|
can query a `.nim` source file and obtain useful information like
|
|
definition of symbols or suggestions for completion.
|
|
|
|
This document will guide you through the available options. If you
|
|
want to look at practical examples of nimsuggest support you can look
|
|
at the
|
|
`various editor integrations <https://github.com/Araq/Nim/wiki/Editor-Support>`_
|
|
already available.
|
|
|
|
|
|
Installation
|
|
============
|
|
|
|
Nimsuggest is part of Nim's core. Build it via::
|
|
|
|
koch nimsuggest
|
|
|
|
|
|
Nimsuggest invocation
|
|
=====================
|
|
|
|
Run it via `nimsuggest --stdin --debug myproject.nim`. Nimsuggest is a
|
|
server that takes queries that are related to `myproject`. There is some
|
|
support so that you can throw random `.nim` files which are not part
|
|
of `myproject` at Nimsuggest too, but usually the query refer to modules/files
|
|
that are part of `myproject`.
|
|
|
|
`--stdin` means that Nimsuggest reads the query from `stdin`. This is great
|
|
for testing things out and playing with it but for an editor communication
|
|
via sockets is more reasonable so that is the default. It listens to port 6000
|
|
by default.
|
|
|
|
Nimsuggest is basically a frontend for the nim compiler so `--path` flags and
|
|
`config files <https://nim-lang.org/docs/nimc.html#compiler-usage-configuration-files>`_
|
|
can be used to specify additional dependencies like
|
|
`nimsuggest --stdin --debug --path:"dependencies" myproject.nim`.
|
|
|
|
|
|
Specifying the location of the query
|
|
------------------------------------
|
|
|
|
Nimsuggest then waits for queries to process. A query consists of a
|
|
cryptic 3 letter "command" `def` or `con` or `sug` or `use` followed by
|
|
a location. A query location consists of:
|
|
|
|
|
|
`file.nim`
|
|
This is the name of the module or include file the query refers to.
|
|
|
|
`dirtyfile.nim`
|
|
This is optional.
|
|
|
|
The `file` parameter is enough for static analysis, but IDEs
|
|
tend to have *unsaved buffers* where the user may still be in
|
|
the middle of typing a line. In such situations the IDE can
|
|
save the current contents to a temporary file and then use the
|
|
`dirtyfile.nim` option to tell Nimsuggest that `foobar.nim` should
|
|
be taken from `temporary/foobar.nim`.
|
|
|
|
|
|
`line`
|
|
An integer with the line you are going to query. For the compiler
|
|
lines start at **1**.
|
|
|
|
`col`
|
|
An integer with the column you are going to query. For the
|
|
compiler columns start at **0**.
|
|
|
|
|
|
Definitions
|
|
-----------
|
|
|
|
The `def` Nimsuggest command performs a query about the definition
|
|
of a specific symbol. If available, Nimsuggest will answer with the
|
|
type, source file, line/column information and other accessory data
|
|
if available like a docstring. With this information an IDE can
|
|
provide the typical *Jump to definition* where a user puts the
|
|
cursor on a symbol or uses the mouse to select it and is redirected
|
|
to the place where the symbol is located.
|
|
|
|
Since Nim is implemented in Nim, one of the nice things of
|
|
this feature is that any user with an IDE supporting it can quickly
|
|
jump around the standard library implementation and see exactly
|
|
what a proc does, learning about the language and seeing real life
|
|
examples of how to write/implement specific features.
|
|
|
|
Nimsuggest will always answer with a single definition or none if it
|
|
can't find any valid symbol matching the position of the query.
|
|
|
|
|
|
Suggestions
|
|
-----------
|
|
|
|
The `sug` Nimsuggest command performs a query about possible
|
|
completion symbols at some point in the file.
|
|
|
|
The typical usage scenario for this option is to call it after the
|
|
user has typed the dot character for `the object oriented call
|
|
syntax <tut2.html#object-oriented-programming-method-call-syntax>`_.
|
|
Nimsuggest will try to return the suggestions sorted first by scope
|
|
(from innermost to outermost) and then by item name.
|
|
|
|
|
|
Invocation context
|
|
------------------
|
|
|
|
The `con` Nimsuggest command is very similar to the suggestions
|
|
command, but instead of being used after the user has typed a dot
|
|
character, this one is meant to be used after the user has typed
|
|
an opening brace to start typing parameters.
|
|
|
|
|
|
Symbol usages
|
|
-------------
|
|
|
|
The `use` Nimsuggest command lists all usages of the symbol at
|
|
a position. IDEs can use this to find all the places in the file
|
|
where the symbol is used and offer the user to rename it in all
|
|
places at the same time.
|
|
|
|
For this kind of query the IDE will most likely ignore all the
|
|
type/signature info provided by Nimsuggest and concentrate on the
|
|
filename, line and column position of the multiple returned answers.
|
|
|
|
|
|
|
|
Parsing nimsuggest output
|
|
=========================
|
|
|
|
Nimsuggest output is always returned on single lines separated by
|
|
tab characters (``\t``). The values of each column are:
|
|
|
|
1. Three characters indicating the type of returned answer (e.g.
|
|
`def` for definition, `sug` for suggestion, etc).
|
|
2. Type of the symbol. This can be `skProc`, `skLet`, and just
|
|
about any of the enums defined in the module `compiler/ast.nim`.
|
|
3. Fully qualified path of the symbol. If you are querying a symbol
|
|
defined in the `proj.nim` file, this would have the form
|
|
`proj.symbolName`.
|
|
4. Type/signature. For variables and enums this will contain the
|
|
type of the symbol, for procs, methods and templates this will
|
|
contain the full unique signature (e.g. `proc (File)`).
|
|
5. Full path to the file containing the symbol.
|
|
6. Line where the symbol is located in the file. Lines start to
|
|
count at **1**.
|
|
7. Column where the symbol is located in the file. Columns start
|
|
to count at **0**.
|
|
8. Docstring for the symbol if available or the empty string. To
|
|
differentiate the docstring from end of answer,
|
|
the docstring is always provided enclosed in double quotes, and
|
|
if the docstring spans multiple lines, all following lines of the
|
|
docstring will start with a blank space to align visually with
|
|
the starting quote.
|
|
|
|
Also, you won't find raw ``\n`` characters breaking the one
|
|
answer per line format. Instead you will need to parse sequences
|
|
in the form ``\xHH``, where *HH* is a hexadecimal value (e.g.
|
|
newlines generate the sequence ``\x0A``).
|