more cleanups for 0.11.0
This commit is contained in:
Araq
parent
01f625f75c
commit
3905cfeace
9 changed files with 218 additions and 57 deletions
47
doc/lib.txt
47
doc/lib.txt
|
|
@ -37,7 +37,7 @@ Core
|
|||
|
||||
* `unsigned <unsigned.html>`_
|
||||
This module implements basic arithmetic operators for unsigned integers.
|
||||
To discourage users from using unsigned integers, it's not part
|
||||
To discourage users from using unsigned integers, it's not part
|
||||
of ``system``, but an extra import.
|
||||
|
||||
* `threads <threads.html>`_
|
||||
|
|
@ -45,7 +45,7 @@ Core
|
|||
import it explicitly.
|
||||
|
||||
* `channels <channels.html>`_
|
||||
Nim message passing support for threads. **Note**: This is part of the
|
||||
Nim message passing support for threads. **Note**: This is part of the
|
||||
system module. Do not import it explicitly.
|
||||
|
||||
* `locks <locks.html>`_
|
||||
|
|
@ -55,7 +55,7 @@ Core
|
|||
Contains the AST API and documentation of Nim for writing macros.
|
||||
|
||||
* `typeinfo <typeinfo.html>`_
|
||||
Provides (unsafe) access to Nim's run time type information.
|
||||
Provides (unsafe) access to Nim's run time type information.
|
||||
|
||||
* `typetraits <typetraits.html>`_
|
||||
This module defines compile-time reflection procs for working with types.
|
||||
|
|
@ -110,9 +110,9 @@ String handling
|
|||
|
||||
* `unicode <unicode.html>`_
|
||||
This module provides support to handle the Unicode UTF-8 encoding.
|
||||
|
||||
|
||||
* `encodings <encodings.html>`_
|
||||
Converts between different character encodings. On UNIX, this uses
|
||||
Converts between different character encodings. On UNIX, this uses
|
||||
the ``iconv`` library, on Windows the Windows API.
|
||||
|
||||
* `pegs <pegs.html>`_
|
||||
|
|
@ -159,7 +159,7 @@ Generic Operating System Services
|
|||
may provide other implementations for this standard stream interface.
|
||||
|
||||
* `marshal <marshal.html>`_
|
||||
Contains procs for serialization and deseralization of arbitrary Nim
|
||||
Contains procs for serialization and deseralization of arbitrary Nim
|
||||
data structures.
|
||||
|
||||
* `terminal <terminal.html>`_
|
||||
|
|
@ -168,7 +168,7 @@ Generic Operating System Services
|
|||
sequences and does not depend on any other module.
|
||||
|
||||
* `memfiles <memfiles.html>`_
|
||||
This module provides support for memory mapped files (Posix's ``mmap``)
|
||||
This module provides support for memory mapped files (Posix's ``mmap``)
|
||||
on the different operating systems.
|
||||
|
||||
* `fsmonitor <fsmonitor.html>`_
|
||||
|
|
@ -228,7 +228,7 @@ Internet Protocols and Support
|
|||
This module implements a simple HTTP client.
|
||||
|
||||
* `smtp <smtp.html>`_
|
||||
This module implement a simple SMTP client.
|
||||
This module implement a simple SMTP client.
|
||||
|
||||
* `ftpclient <ftpclient.html>`_
|
||||
This module implements an FTP client.
|
||||
|
|
@ -346,7 +346,7 @@ XML Processing
|
|||
This module parses an HTML document and creates its XML tree representation.
|
||||
|
||||
* `htmlgen <htmlgen.html>`_
|
||||
This module implements a simple XML and HTML code
|
||||
This module implements a simple XML and HTML code
|
||||
generator. Each commonly used HTML tag has a corresponding macro
|
||||
that generates a string with its HTML representation.
|
||||
|
||||
|
|
@ -381,7 +381,7 @@ Miscellaneous
|
|||
|
||||
* `oids <oids.html>`_
|
||||
An OID is a global ID that consists of a timestamp,
|
||||
a unique counter and a random value. This combination should suffice to
|
||||
a unique counter and a random value. This combination should suffice to
|
||||
produce a globally distributed unique ID. This implementation was extracted
|
||||
from the Mongodb interface and it thus binary compatible with a Mongo OID.
|
||||
|
||||
|
|
@ -453,12 +453,8 @@ Other
|
|||
* `zipfiles <zipfiles.html>`_
|
||||
This module implements a zip archive creator/reader/modifier.
|
||||
|
||||
* `web <web.html>`_
|
||||
This module contains simple high-level procedures for dealing with the
|
||||
Web like loading the contents of a Web page from an URL.
|
||||
|
||||
* `ssl <ssl.html>`_
|
||||
This module provides an easy to use sockets-style
|
||||
This module provides an easy to use sockets-style
|
||||
Nim interface to the OpenSSL library.
|
||||
|
||||
* `rdstdin <rdstdin.html>`_
|
||||
|
|
@ -513,25 +509,6 @@ Regular expressions
|
|||
Wrapper for the TRE library.
|
||||
|
||||
|
||||
Graphics libraries
|
||||
------------------
|
||||
|
||||
* `sdl <sdl.html>`_
|
||||
Part of the wrapper for SDL.
|
||||
* `sdl_gfx <sdl_gfx.html>`_
|
||||
Part of the wrapper for SDL.
|
||||
* `sdl_image <sdl_image.html>`_
|
||||
Part of the wrapper for SDL.
|
||||
* `sdl_mixer <sdl_mixer.html>`_
|
||||
Part of the wrapper for SDL.
|
||||
* `sdl_net <sdl_net.html>`_
|
||||
Part of the wrapper for SDL.
|
||||
* `sdl_ttf <sdl_ttf.html>`_
|
||||
Part of the wrapper for SDL.
|
||||
* `smpeg <smpeg.html>`_
|
||||
Part of the wrapper for SDL.
|
||||
|
||||
|
||||
GUI libraries
|
||||
-------------
|
||||
|
||||
|
|
@ -591,7 +568,7 @@ Data Compression and Archiving
|
|||
Scientific computing
|
||||
--------------------
|
||||
|
||||
* `libsvm <libsvm.html>`_
|
||||
* `libsvm <libsvm.html>`_
|
||||
Low level wrapper for `lib svm <http://www.csie.ntu.edu.tw/~cjlin/libsvm/>`_.
|
||||
|
||||
Nimble
|
||||
|
|
|
|||
174
doc/nimsuggest.txt
Normal file
174
doc/nimsuggest.txt
Normal file
|
|
@ -0,0 +1,174 @@
|
|||
================================
|
||||
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