spacemacs/layers/+lang/ruby/README.org

Ruby layer

• Description
  • Features:
• Install
  • Choosing a backend
    • Robe
    • Language Server Protocol
  • Prerequisites
  • Ruby version management
  • Test runner
  • Formatting
• Key bindings
  • Ruby (enh-ruby-mode, robe, inf-ruby, ruby-tools)
  • Debugger
  • Bundler
  • RuboCop
  • Tests
    • RSpec-mode
    • Ruby-test-mode
    • minitest-mode
  • Toggles
  • Rake
  • Refactor
  • Seeing is believing
• Configuration
  • Layer options
  • Disabling the automatic insertion of encoding comment

Description

This layer provides support for the Ruby programming language.

Features:

• Version manager (rbenv, rvm or chruby)
• Integration with bundler
• Test runner (ruby-test and rspec)
• Rake runner
• Linter (rubocop)
• Formatter (prettier)
• Interactive REPL and code navigation (robe)
• Interactive debugger using dap-mode

Install

To use this configuration layer, add it to your ~/.spacemacs. You will need to add ruby to the existing dotspacemacs-configuration-layers list in this file.

This layer supports two different Ruby modes: Emacs's built-in Ruby Mode and enh-ruby-mode. By default the built-in Ruby mode is enabled. To switch to the enh-ruby-mode set ruby-enable-enh-ruby-mode to t:

  (defun dotspacemacs-configuration-layers ()
     '((ruby :variables ruby-enable-enh-ruby-mode t)))

Choosing a backend

To choose a default backend set the layer variable ruby-backend:

  (ruby :variables ruby-backend 'robe)

Alternatively the lsp backend will be automatically chosen if the layer lsp is used and you did not specify any value for ruby-backend.

Backend can be chosen on a per project basis using directory local variables (files named .dir-locals.el at the root of a project), an example to use the lsp backend:

  ;;; Directory Local Variables
  ;;; For more information see (info "(emacs) Directory Variables")

  ((ruby-mode (ruby-backend . lsp)))

Note: you can easily add a directory local variable with SPC f v d.

Robe

The default Ruby-mode backend. See Prerequisites for the necessary Gems to support Robe.

Language Server Protocol

IDE-like backend for Ruby. The only prerequisite gem is solargraph which can be installed globally with:

  gem install solargraph

LSP also supports the DAP debugger which will be automatically configured upon using the LSP backend. Dap-mode can be setup here: https://github.com/emacs-lsp/dap-mode#ruby

Prerequisites

Some of the advanced features supported by this layer depend on external gems that need to be installed in the context of your project (see below for guidance based on your version manager):

• pry and pry-doc are required for jump to definition and code documentation (robe-mode)
• ruby_parser is required for goto-step_definition in feature-mode
• rubocop is required for rubocop integration
• prettier is required for formatter
• seeing_is_believing helps you evaluate code inline
• solargraph is required for using the language server protocol in ruby-mode

You can install the gems in the context of your current project by adding them to the Gemfile, e.g.:

  gem 'pry'

or on the command line (please refer to your ruby version manager specific documentation for details and caveats):

  gem install pry

Ruby version management

This layer supports RVM, Rbenv, and Chruby. You can choose the default version manager by setting the variable ruby-version-manager in your dotfile, for example:

  (defun dotspacemacs-configuration-layers ()
     '((ruby :variables ruby-version-manager 'rvm)))

When a version manager is enabled it will use the currently activated ruby except if a .ruby-version file exists in which case the ruby version of this file is used. rvm will also try to look for a .rvmrc and gemfile, the priority order is .rvmrc then .ruby-version then gemfile.

Note: Only one version manager at a time can be enabled.

Test runner

This layer supports RSpec, ruby-test and minitest test runners (frameworks). By default ruby-test is used, to change to another frameworks set the layer variable ruby-test-runner.

Example to set the test runner to RSpec:

  (defun dotspacemacs-configuration-layers ()
     '((ruby :variables ruby-test-runner 'rspec)))

Tip: You can enable different test runners for different projects by using directory local variables.

Formatting

If you'd like to use prettier/plugin-ruby to format on save:

  (defun dotspacemacs-configuration-layers ()
     '((ruby :variables ruby-prettier-on-save t)))

Note that the prettier binary must be available in the project's node_modules/.bin/ or on exec-path.

Key bindings

Ruby (enh-ruby-mode, robe, inf-ruby, ruby-tools)

Key binding	Description
SPC m g g	go to definition (robe-jump)
SPC m h h	show documentation for method at point (robe-doc)
SPC m s b	send buffer
SPC m s B	send buffer and switch to REPL
SPC m s f	send function definition
SPC m s F	send function definition and switch to REPL
SPC m s i	start REPL
SPC m s l	send line
SPC m s L	send line and switch to REPL
SPC m s r	send region
SPC m s R	send region and switch to REPL
SPC m s s	switch to REPL
SPC m x '​	Change symbol or " string to '
SPC m x "​	Change symbol or ' string to "
SPC m x :	Change string to symbol
SPC m x h	toggle hash syntax in active region
SPC m = =	format buffer using prettier
%	evil-matchit jumps between blocks

Debugger

Using the dap layer you'll get access to all the DAP key bindings, see the complete list of key bindings on the dap layer description.

Bundler

Key binding	Description
SPC m b c	run bundle check
SPC m b i	run bundle install
SPC m b s	run bundle console
SPC m b u	run bundle update
SPC m b x	run bundle exec
SPC m b o	run bundle open

RuboCop

Key binding	Description
SPC m = r	Format the current buffer using RuboCop
SPC m R r f	Runs RuboCop on the currently visited file
SPC m R r F	Runs auto-correct on the currently visited file
SPC m R r d	Prompts from a directory on which to run RuboCop
SPC m R r D	Prompts for a directory on which to run auto-correct
SPC m R r p	Runs RuboCop on the entire project
SPC m R r P	Runs auto-correct on the project

Tests

RSpec-mode

When ruby-test-runner equals rspec.

Key binding	Description
SPC m t a	run all specs
SPC m t b	run current spec file
SPC m t c	run the current spec file and subsequent ones
SPC m t d	run tests in a directory
SPC m t e	mark example as pending
SPC m t f	run method
SPC m t l	run last failed spec
SPC m t m	run specs related to the current buffer
SPC m t r	re-run last spec
SPC m t t	run spec at pointer
SPC m t TAB	toggle between spec's and target's buffer
SPC m t ~	toggle between spec's and target's buffer find example

Ruby-test-mode

When ruby-test-runner equals ruby-test.

Key binding	Description
SPC m t b	run test file
SPC m t t	run test at pointer

minitest-mode

When ruby-test-runner equals minitest.

Key binding	Description
SPC m t a	run all tests
SPC m t b	run current file
SPC m t r	repeat last test command
SPC m t s	run test for current file

Toggles

Key binding	Description
SPC m T '	Toggle quotes of current string (only built-in mode)
SPC m T {	Toggle style of current block (only built-in mode)

Rake

Key binding	Description
SPC m k k	Runs rake
SPC m k r	Re-runs the last rake task
SPC m k R	Regenerates the rake cache
SPC m k f	Finds definition of a rake task

Refactor

Key binding	Description
SPC m r e m	Extract to method
SPC m r e v	Extract local variable
SPC m r e c	Extract constant
SPC m r e l	Extract to let (rspec)

Seeing is believing

Key binding	Description
<SPC> m @ @	Run seeing is believing
<SPC> m @ c	Clear seeing is believing output

Configuration

Layer options

Variable	Default value	Description
ruby-enable-enh-ruby-mode	nil	If non-nil, use enh-ruby-mode package instead of the built-in Ruby Mode.
ruby-version-manager	nil	If non nil, defines the Ruby version manager.Possible values are rbenv, rvm or chruby.
ruby-test-runner	ruby-test	Test runner to use. Possible values are ruby-test, minitest or rspec.
ruby-highlight-debugger-keywords	t	If non-nil, enable highlight for debugger keywords.
ruby-backend	robe	Defines the backend for IDE feature. Possible values are robe or lsp.

Disabling the automatic insertion of encoding comment

Note that ruby-mode and enh-ruby-mode will automatically insert the encoding comment # coding: utf-8 at the top of a `.rb file, if it contains UTF-8 characters. This might not be desired in Ruby 2.0+, since UTF-8 has become the default encoding. In fact, this will trigger an error with Robocop.

The fix is to set the variable ruby-insert-encoding-magic-comment (ruby-mode) or enh-ruby-add-encoding-comment-on-save (enh-ruby-mode) to nil, e.g.

  (defun dotspacemacs-configuration-layers ()
     '((ruby :variables ruby-insert-encoding-magic-comment nil)))