GitHub - nim-lang/nim-mode: An emacs major mode for the Nim programming language
source link: https://github.com/nim-lang/nim-mode
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
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-compilecommand (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 (
- ensure packages from MELPA can be installed
M-x package-install RET nim-mode RET)
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.
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
flymake (linting) and
company (completion) that are responsible for editor integration.
flymakeare two alternative linting engines. Before emacs version
flymakewas pretty much outdated and the recommended linting engine was the external
flycheck. But from version
flymakeis a good linting engine that comes with emacs. But you should not use both at the same time.
flycheck-nimsuggestis a backend for flycheck. It builds the bridge to
nimsuggest-modeso that flycheck can visualize the linting information that nimsuggest provides.
flycheck-nimis an alternative backend for flycheck that does not interact with nimsuggest at all. Instead it uses the
nim checkcommand and parses the output of that command.
flymake-nimsuggestis the backend for
flymaketo build the bridge to
nimsuggest-mode. It comes with
nim-mode, and it is activated automatically in nim files, when
company-modeis a minor mode for auto completion (company - complete anything)
company-nimsuggestis the backend for
company-modethat builds the bridge to
eldoc-modeis a minor mode for emacs that is responsible to show the documentation of emacs lisp symbols at point, hence the name. But
eldoc-modehas been extended to work for other programming languages as well.
nimsuggest-modehas integration for
eldoc-modeso you can see documentation of nim symbols at point when
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
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
- Show Short Doc -- (automatically) Shows the short documentation of the symbol at point in the minibuffer
Grammar and Indentation
nim-smie.el there are nim grammar rules for
(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
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.
You can copy and adjust the following configuration into your local
;; 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
You can also find other editor/IDE plugins for Nim language here
Aggregate valuable and interesting links.
Joyk means Joy of geeK