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
    • Navigation between items
    • In buffer evaluation of code
    • Interactions with REPLs
    • Interactions with Tests
      • For all languages
      • Depending on the language
    • Building and Compilation
    • Debugging
    • Code navigation
    • Getting Help or 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. Three keys bindings are not an issue (ie. SPC m h d) since SPC m can be accessed via ,.

Navigation between items

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.

In buffer evaluation of code

Live evaluation of code is under the prefix <SPC> e.

Key           |                 Description

------------------|------------------------------------------------------------ e $ | put the point at the end of the line and evaluate e b | evaluate buffer e e | evaluate last expression e f | evaluate function e l | evaluate line e r | evaluate region

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 s is the prefix for sending code. This allows fast interaction with the REPL whenever it is possible (don't forget that , is a shortcut for <SPC> m).
• 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

Building and Compilation

The base prefix for major mode specific compilation is SPC m c.

Key Binding      |                 Description

---------------------|------------------------------------------------------------ m c c | compile m c r | recompile

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 c | continue current process m d d | start debug process m d n | next breakpoint m d N | previous breakpoint

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).

Code navigation

Key           |                 Description

------------------|------------------------------------------------------------ m g | go to definition of thing under point

Getting Help or Documentation

The base prefix for help commands is SPC h. Documentation is considered as an help command.

Key           |                 Description

------------------|------------------------------------------------------------ m h d | documentation of thing under point

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 bindings for vertical movements.

Key         |                 Description

----------------|------------------------------------------------------------ C-j | go down C-k | go up

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