417b90a7e5
- add additional parameters parsing (other implementations will just
ignore them). E.g. if in RST we have:
.. code:: nim
:test: "nim c $1"
...
then in Markdown that will be:
```nim test="nim c $1"
...
```
- implement Markdown interpretation of additional indentation which is
less than 4 spaces (>=4 spaces is a code block but it's not
implemented yet). RST interpretes it as quoted block, for Markdown it's
just normal paragraphs.
- add separate `md2html` and `md2tex` commands. This is to separate
Markdown behavior in cases when it diverges w.r.t. RST significantly —
most conspicously like in the case of additional indentation above, and
also currently the contradicting inline rule of Markdown is also turned
on only in `md2html` and `md2tex`. **Rationale:** mixing Markdown and
RST arbitrarily is a way to nowhere, we need to provide a way to fix the
particular behavior. Note that still all commands have **both** Markdown
and RST features **enabled**. In this PR `*.nim` files can be processed
only in Markdown mode, while `md2html` is for `*.md` files and
`rst2html` for `*.rst` files.
- rename `*.rst` files to `.*md` as our current default behavior is
already Markdown-ish
- convert code blocks in `docgen.rst` to Markdown style as an example.
Other code blocks will be converted in the follow-up PRs
- fix indentation inside Markdown code blocks — additional indentation
is preserved there
- allow more than 3 backticks open/close blocks (tildas \~ are still not
allowed to avoid conflict with RST adornment headings) see also
https://github.com/nim-lang/RFCs/issues/355
- better error messages
- (other) fix a bug that admonitions cannot be used in sandbox mode; fix
annoying warning on line 2711
6.3 KiB
================================ Nim IDE Integration Guide
:Author: Unknown :Version: |nimversion|
.. default-role:: code .. include:: rstcommon.rst .. 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:cmd: 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:
.. code:: cmd koch nimsuggest
Nimsuggest invocation
Run it via nimsuggest --stdin --debug myproject.nim:cmd:. 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:option: 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:option: 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:cmd:.
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:
-
Three characters indicating the type of returned answer (e.g.
deffor definition,sugfor suggestion, etc). -
Type of the symbol. This can be
skProc,skLet, and just about any of the enums defined in the modulecompiler/ast.nim. -
Fully qualified path of the symbol. If you are querying a symbol defined in the
proj.nimfile, this would have the formproj.symbolName. -
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)). -
Full path to the file containing the symbol.
-
Line where the symbol is located in the file. Lines start to count at 1.
-
Column where the symbol is located in the file. Columns start to count at 0.
-
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
\ncharacters 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).