# 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) - [Reserved prefix](#reserved-prefix) - [User prefix](#user-prefix) - [Major mode prefix](#major-mode-prefix) - [Micro-state key binding](#micro-state-key-binding) - [Evilify buffers](#evilify-buffers) - [Navigation](#navigation) - [n and N](#n-and-n) - [Code Navigation](#code-navigation) - [`insert state` buffers](#insert-state-buffers) - [Evaluation](#evaluation) - [REPLs](#repls) - [Send code](#send-code) - [In terminal](#in-terminal) - [Building and Compilation](#building-and-compilation) - [Debugging](#debugging) - [Tests](#tests) - [All languages](#all-languages) - [Language specific](#language-specific) - [Refactoring](#refactoring) - [Help or Documentation](#help-or-documentation) ## 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 ### Reserved prefix #### User prefix SPC o must not be used by any layer. It is reserved for the user. #### Major mode prefix SPC m is reserved for the current major mode. Three keys bindings are not an issue (ie. SPC m h d) since SPC m can be accessed via ,. #### Micro-state Whenever possible a micro-state should be enabled with C-SPC. For instance micro-states dedicated to special buffers like `helm` or `ido` buffers are good candidates to be put on C-SPC. **Important Note** Due to terminal limitation the micro-states _must_ also be bound to C-@. It is recommended to add q to leave the micro-state. ### 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` - add yank (copy) with `y` - 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 #### n and N To be consistent with the Vim way, n and N are favored over Emacs n and p. Ideally a micro-state should be provided to smooth the navigation experience. A micro-state allows to repeat key bindings without entering each time the prefix commands. More info on micro-states in the [documentation](DOCUMENTATION.md#micro-states). #### Code Navigation The prefix for going to something is ` m g`. Key | Description ------------------|------------------------------------------------------------ m g a | go to alternate file (i.e. `.h <--> .cpp`) m g g | go to things under point m g t | go to corresponding test file if any #### `insert state` buffers Navigation in buffers like `Helm` and `ido` which are in `insert state` should be performed with C-j and C-k bindings for vertical movements. Key | Description ----------------|------------------------------------------------------------ C-j | go down C-k | go up ### Evaluation Live evaluation of code is under the prefix ` m e`. Key | Description ------------------|------------------------------------------------------------ m e $ | put the point at the end of the line and evaluate m e b | evaluate buffer m e e | evaluate last expression m e f | evaluate function m e l | evaluate line m e r | evaluate region ### REPLs #### Send code 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 s` is the prefix for sending code. 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 i | start/switch to REPL inferior process 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. #### In terminal History navigation in shells or REPLs buffers should be bound as well to C-j and C-k. Key | Description ----------------|------------------------------------------------------------ C-j | next item in history C-k | previous item in history C-l | clear screen C-r | search backward in history ### Building and Compilation The base prefix for major mode specific compilation is SPC m c. Key Binding | Description ---------------------|------------------------------------------------------------ m c b | compile buffer m c c | compile m c r | clean and compile Note: we don't distinguish between the file and the buffer. We can implement an auto-save of the buffer before compiling the buffer. ### Debugging The base prefix for debugging commands is SPC d. Key Binding | Description ---------------------|------------------------------------------------------------ m d a | abandon current process m d b | toggle a breakpoint m d B | clear all breakpoints m d c | continue m d d | start debug session m d i | inspect value at point m d l | local variables m d n | next m d r | run m d s | step Notes: - Ideally a micro-state for breakpoint navigation should be provided. - If there is no toggle breakpoint function, then it should be implemented at the spacemacs level and ideally the function should be proposed as a patch upstream (major mode repository). ### 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). #### 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 of buffer. #### Language specific 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 ### Refactoring Refactoring prefix is SPC m r. ### Help or Documentation The base prefix for help commands is SPC h. Documentation is considered as an help command. Key | Description ------------------|------------------------------------------------------------ m h h | documentation of thing under point m h r | documentation of selected region