# Spacemacs conventions **Table of Contents** - [Spacemacs conventions](#spacemacs-conventions) - [Code guidelines](#code-guidelines) - [Spacemacs core and layer](#spacemacs-core-and-layer) - [All layers](#all-layers) - [Key bindings conventions](#key-bindings-conventions) - [Prefix reserved to the user](#prefix-reserved-to-the-user) - [Prefix reserved to the current major mode](#prefix-reserved-to-the-current-major-mode) - [Interactions with REPLs](#interactions-with-repls) - [Interactions with Tests](#interactions-with-tests) - [For all languages](#for-all-languages) - [Depending on the language](#depending-on-the-language) - [Debugging](#debugging) - [Code navigation](#code-navigation) - [Documentation](#documentation) - [Evilify buffers](#evilify-buffers) - [Navigation in `insert state` buffers](#navigation-in-insert-state-buffers) ## Code guidelines ### Spacemacs core and layer Function names follow these conventions: - `spacemacs/xxx` is an interactive function called `xxx` - `spacemacs//xxx` is a private function called `xxx` (implementation details) - `spacemacs|xxx` is a _macro_ called `xxx` Variables follow these conventions: - `spacemacs-xxx` is a variable - `spacemacs--xxx` is a private variable (implementation details) ### All layers A package is initialized in a function with name `/init-xxx` where: - `` is the layer name - `xxx` is the package name ## Key bindings conventions ### Prefix reserved to the user ` o` must not be used by any layer. It is reserved for the user. ### Prefix reserved to the current major mode ` m` is reserved for the current major mode. ### Interactions with REPLs A lot of languages can interact with a REPL. To help keeping a consistent behavior between those languages the following conventions should be followed: - ` m` is the prefix for sending code if there is any conflict with other bindings then ` m s` is the prefered prefix. This allows fast interaction with the REPL whenever it is possible. - lower case key bindings keep the focus on the current buffer - upper case key bindings move the focus to the REPL buffer Key | Description --------------------|------------------------------------------------------------ m (s) b | send buffer m (s) B | send buffer and switch to REPL m (s) d | first key to send buffer and switch to REPL to debug (step) m (s) D | second key to send buffer and switch to REPL to debug (step) m (s) f | send function m (s) F | send function and switch to REPL m (s) l | send line m (s) L | send line and switch to REPL m (s) r | send region m (s) R | send region and switch to REPL Note: we don't distinguish between the file and the buffer. ### Interactions with Tests A lot of languages have their own test frameworks. These frameworks share common actions that we can unite under the same key bindings: - ` m t` is the prefix for test execution. - ` m T` is the prefix for test execution in debug mode (if supported). #### For all languages Key | Description ------------------|------------------------------------------------------------ m t a | execute all the tests of the current project m t b | execute all the tests of the current buffer m t t | execute the current test (thing at point, function) Note: we don't distinguish between the file and the buffer. We can implement an auto-save of the buffer before executing the tests. #### Depending on the language Key | Description ------------------|------------------------------------------------------------ m t m | execute the tests of the current module m t s | execute the tests of the current suite Note that there are overlaps, depending on the language we will choose one or more bindings for the same thing ### Debugging Key | Description ------------------|------------------------------------------------------------ m b | toggle a breakpoint ### Code navigation Key | Description ------------------|------------------------------------------------------------ m g | go to definition of thing under point ### Documentation Key | Description ------------------|------------------------------------------------------------ m d | documentation of thing under point **TBD** ### Evilify buffers `Spacemacs` offers convenient functions to _evilify_ a buffer. _Evilifying_ a buffer is to: - add `hjkl` navigation - add incremental search with `/`, `n` and `N` - add `visual state` and `visual line state` - activate evil-leader key - fix all bindings shadows by the above additions To fix the shadowed bindings we capitalize them, for instance: shadowed `h` is transposed to `H`, if `H` is taken then it is transposed to `C-h` and so on... Example of _evilified_ buffers are `magit status`, `paradox buffer`. The related functions are: - `spacemacs/activate-evil-leader-for-maps` and `spacemacs/activate-evil-leader-for-map` - `spacemacs/evilify` ### Navigation in `insert state` buffers Navigation in buffers like `Helm` and `ido` which are in `insert state` should be performed with C-j and C-k for vertical movements. History navigation in shells or REPLs buffers should be bound as well to C-j and C-k.