renamed most remaining .txt documentation files to .rst
This commit is contained in:
Araq
parent
4812d41376
commit
eed0128916
20 changed files with 13 additions and 13 deletions
|
|
@ -1,174 +0,0 @@
|
|||
================================
|
||||
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 available as a Nimble package but currently does not install
|
||||
properly via Nimble. As nimsuggest is part of the compiler it also doesn't make
|
||||
too much sense as a Nimble package. Instead we will do the building manually::
|
||||
|
||||
cd compiler/nimsuggest
|
||||
nim c -d:release nimsuggest
|
||||
cp nimsuggest ../../bin
|
||||
# OR: copy the nimsuggest binary to where your 'nim' binary is
|
||||
cd ../..
|
||||
|
||||
|
||||
|
||||
Nimsuggest invocation
|
||||
=====================
|
||||
|
||||
Run it via ``nimsuggest --stdin 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.
|
||||
|
||||
|
||||
Specifying the location of the query
|
||||
------------------------------------
|
||||
|
||||
Nimsuggest than 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`` 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 ``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 **1**.
|
||||
|
||||
|
||||
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#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. Full qualitifed 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 **1**.
|
||||
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``).
|
||||
Loading…
Add table
Add a link
Reference in a new issue