nim-mode
nim-mode copied to clipboard
An emacs major mode for the Nim programming language
nim-mode
A major mode for editing Nim source code
This package provides (and requires Emacs 24.4 or higher version):
- Syntax highlighting for
*.nim
,*.nims
,*.nimble
andnim.cfg
files -
nim-compile
command (C-c C-c), with error matcher for the compile buffer - Nimsuggest (alpha):
- on the fly linter using flycheck, or flymake (from Emacs 26)
- auto-completion with company-mode ("C-M-i" for manual completion)
- jump-to-definition (M-., and M-, keys)
- find-references (M-? key)
- eldoc or help on hover in term of LSP
- Automatic indentation and line breaking (alpha)
- Outline by procedures (
hs-hide-all
,hs-show-all
etc.)
Installation
- ensure packages from MELPA can be installed
- Install
nim-mode
(e.g.M-x package-install RET nim-mode RET
)
nimsuggest (alpha)
At the time of writing this it should be mentioned that both nimsuggest and nimsuggest-mode have problems that could cause emacs to be much less responsive, or even freeze. Apart from that is is non trivial to configure nimsuggest with the right parameters so that you also get correct results. So you have been warned.
Nimsuggest is the compilation server for Nim, it runs in its own
process, pretty much independent of emacs. nimsuggest-mode
is an emacs minor mode that comes with nim-mode
. It is
responsible to create the nimsuggest instance and connect emacs with it.
nimsuggest-mode
doesn't do anything visual in emacs yet. There are
other minor modes such as flycheck
,flymake
(linting) and
company
(completion) that are responsible for editor integration.
-
flycheck
andflymake
are two alternative linting engines. Before emacs version26.1
flymake
was pretty much outdated and the recommended linting engine was the externalflycheck
. But from version26.1
onward,flymake
is a good linting engine that comes with emacs. But you should not use both at the same time. -
flycheck-nimsuggest
is a backend for flycheck. It builds the bridge tonimsuggest-mode
so that flycheck can visualize the linting information that nimsuggest provides. -
flycheck-nim
is an alternative backend for flycheck that does not interact with nimsuggest at all. Instead it uses thenim check
command and parses the output of that command. -
flymake-nimsuggest
is the backend forflymake
to build the bridge tonimsuggest-mode
. It comes withnim-mode
, and it is activated automatically in nim files, whenflymake-mode
is on. -
company-mode
is a minor mode for auto completion (company - complete anything) -
company-nimsuggest
is the backend forcompany-mode
that builds the bridge tonimsuggest-mode
. -
eldoc-mode
is a minor mode for emacs that is responsible to show the documentation of emacs lisp symbols at point, hence the name. Buteldoc-mode
has been extended to work for other programming languages as well.nimsuggest-mode
has integration foreldoc-mode
so you can see documentation of nim symbols at point whennimsuggest-mode
is active.
For nimsuggest-mode
to work, emacs needs to be able to find the nimsuggest binary, when it
is on the path, it should just work, if not you can customize
nimsuggest-path
. Since it is completely optional to use
nimsuggest
, you have to activate nimsuggest-mode
manually.
Install nimsuggest
-
Use stable version: See official download instruction at "Installation based on generated C code" section.
-
Use latest version: This way may or may not work (depending on Nim or nimsuggest's state and we can't support all the way), so use above way if you prefer stable.
# assuming you already installed Nim cd /path/to/Nim_repository ./koch tools
Keyboard Shortcuts (with nimsuggest)
- Completion feature -- C-M-i and M-TAB keys and auto-complete feature if you install company-mode
- Jump to Definition -- M-. to find the definition for symbol at poisition and M-, to go back.
- Show Doc -- C-c C-d Show documentation of symbol at current
position in the dedicated
*nim-doc*
buffer. - Show Short Doc -- (automatically) Shows the short documentation of the symbol at point in the minibuffer
Grammar and Indentation
In nim-smie.el
there are nim grammar rules for smie
(Simple Minded Indentation Engine). These rules give emacs a basic
understanding of the Nim grammar. They are used to calculate a "correct"
indentation level for code, and to fill (distribute line endings at
margin) comments, multiline strings and other parts of the code.
electric-indent-mode
, a global minor mode that is turned on by
default, uses the rules from nim-smie.el
to automatically reindent
the current line, before a new line is started on RET. The rules
sometimes can really make the emacs behave sluggish up to freezing for
several seconds. The problem is most noticeable when the grammar gets
confused with incomplete statements or the grammar becomes very
uncommon through the usage of untyped macros for embedded domain
language. Just as an example writing patterns for the nim library
ast-pattern-matching
really confuses smie and you might have to
manually fix a lot of indentation that electric-indent-mode
breaks
automatically.
My recommendation is to turn off electric indentation for Nim
files. This can be done locally with
(electric-indent-local-mode 0)
, or globally (not just Nim files) with
(electric-indent-mode 0)
. Nim has semantic whitespace, therefore
it might be better if the indentation is something that is inserted manually.
auto-fill-mode
, a minor mode, uses the rules to break lines
automatically. At the moment it is also not recommend to enable
auto-fill-mode
for Nim files. But using fill-paragraph
(M-q) on
comments does work reliably and it is very useful.
Example Configuration
You can copy and adjust the following configuration into your local
init.el
file.
;; The `nimsuggest-path' will be set to the value of
;; (executable-find "nimsuggest"), automatically.
(setq nimsuggest-path "path/to/nimsuggest")
(defun my--init-nim-mode ()
"Local init function for `nim-mode'."
;; Just an example, by default these functions are
;; already mapped to "C-c <" and "C-c >".
(local-set-key (kbd "M->") 'nim-indent-shift-right)
(local-set-key (kbd "M-<") 'nim-indent-shift-left)
;; Make files in the nimble folder read only by default.
;; This can prevent to edit them by accident.
(when (string-match "/\.nimble/" (or (buffer-file-name) "")) (read-only-mode 1))
;; If you want to experiment, you can enable the following modes by
;; uncommenting their line.
;; (nimsuggest-mode 1)
;; Remember: Only enable either `flycheck-mode' or `flymake-mode' at the same time.
;; (flycheck-mode 1)
;; (flymake-mode 1)
;; The following modes are disabled for Nim files just for the case
;; that they are enabled globally.
;; Anything that is based on smie can cause problems.
(auto-fill-mode 0)
(electric-indent-local-mode 0)
)
(add-hook 'nim-mode-hook 'my--init-nim-mode)
Other convenience packages for editing Nim source code
Those packages are convenience packages and can be installed same way as nim-mode (M-x list-packages ...)
- indent-guide: show visible indent levels
- quickrun: emacs port of vim's quickrun
- company-mode: auto-complete feature
- ob-nim: org-mode integration focused on Nim
- wgrep: Writable grep buffer and apply the changes to files (maybe convenient for refactor stuff)
- suggestion-box-el: show argument info on the cursor
Other editors/IDEs
You can also find other editor/IDE plugins for Nim language here