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 already available.
Nimsuggest is part of Nim's core. Build it via:
Run it via
nimsuggest --stdin --debug --v2 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
--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 than waits for queries to process. A query consists of a cryptic 3 letter "command"
use followed by a location. A query location consists of:
This is optional.
file paramater 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
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.
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. Nimsuggest will try to return the suggestions sorted first by scope (from innermost to outermost) and then by item name.
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.
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.
Nimsuggest output is always returned on single lines separated by tab characters (
\t). The values of each column are:
sugfor suggestion, etc).
skLet, and just about any of the enums defined in the module
proj.nimfile, this would have the form
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
© 2006–2017 Andreas Rumpf
Licensed under the MIT License.