| Author: | Britney Spears |
|---|---|
| Version: | 1.4.2 |
"yes, I'm the creator" -- Araq, 2013-07-26 19:28:32.
Note: this is mostly outdated, see instead nimsuggest
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 idetools command of the compiler, 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 idetools support you can look at the test files found in the Test suite or various editor integrations already available.
Idetools invocation
Specifying the location of the query
All of the available idetools commands require you to specify a query location through the --track or --trackDirty switches. The general idetools invocations are:
nim idetools --track:FILE,LINE,COL <switches> proj.nim
Or:
nim idetools --trackDirty:DIRTY_FILE,FILE,LINE,COL <switches> proj.nim
- proj.nim
- This is the main project filename. Most of the time you will pass in the same as FILE, but for bigger projects this is the file which is used as main entry point for the program, the one which users compile to generate a final binary.
- <switches>
- This would be any of the other idetools available options, like --def or --suggest explained in the following sections.
- COL
- An integer with the column you are going to query. For the compiler columns start at zero, so the first column will be 0 and the last in an 80 column terminal will be 79.
- LINE
- An integer with the line you are going to query. For the compiler lines start at 1.
- FILE
- The file you want to perform the query on. Usually you will pass in the same value as proj.nim.
- DIRTY_FILE
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 --trackDirty switch.
Dirty files are likely to contain errors and they are usually compiled partially only to the point needed to service the idetool request. The compiler discriminates them to ensure that a) they won't be cached and b) they won't invalidate the cached contents of the original module.
The other reason is that the dirty file can appear anywhere on disk (e.g. in tmpfs), but it must be treated as having a path matching the original module when it comes to usage of relative paths, etc. Queries, however, will refer to the dirty module name in their answers instead of the normal filename.
Definitions
The --def idetools switch performs a query about the definition of a specific symbol. If available, idetools 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.
Idetools 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 --suggest idetools switch performs a query about possible completion symbols at some point in the file. IDEs can easily provide an autocompletion feature where the IDE scans the current file (and related ones, if it knows about the language being edited and follows includes/imports) and when the user starts typing something a completion box with different options appears.
However such features are not context sensitive and work simply on string matching, which can be problematic in Nim especially due to the case insensitiveness of the language (plus underscores as separators!).
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. Idetools will try to return the suggestions sorted first by scope (from innermost to outermost) and then by item name.
Invocation context
The --context idetools switch is very similar to the suggestions switch, 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.