spacemacs/doc/CONVENTIONS.md

Spacemacs conventions

Table of Contents

• Spacemacs conventions
  • Code guidelines
    • Spacemacs core and layer
    • All layers
  • Key bindings conventions
    • Prefix reserved to the user
    • Prefix reserved to the current major mode
    • Interactions with REPLs
    • Interactions with Tests
      • For all languages
      • Depending on the language
    • Debugging
    • Code navigation
    • Documentation
    • Evilify 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 <layer>/init-xxx where:

• <layer> is the layer name
• xxx is the package name

Key bindings conventions

Prefix reserved to the user

<SPC> o must not be used by any layer. It is reserved for the user.

Prefix reserved to the current major mode

<SPC> 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:

• <SPC> m is the prefix for sending code if there is any conflict with other bindings then <SPC> 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:

• <SPC> m t is the prefix for test execution.
• <SPC> 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.