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

Ruby layer

• Description
  • Features:
• Install
  • Prerequisites
  • Ruby version management
  • Test runner
• Key bindings
  • Ruby (enh-ruby-mode, robe, inf-ruby, ruby-tools)
  • Bundler
  • RuboCop
  • Tests
    • RSpec-mode
    • Ruby-test-mode
    • minitest-mode
  • Rake
  • Refactor
• Layer options

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)
• Interactive REPL and code navigation (robe)

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

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

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.

Key bindings

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

Key binding	Description
SPC m '​	toggle quotes of current string (only built-in mode)
SPC m {	toggle style of current block (only built-in mode)
SPC m g g	go to definition (robe-jump)
SPC m h h	show documentation for method at point (robe-doc)
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 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
%	evil-matchit jumps between blocks

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

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 R m	Extract to method
SPC m r R v	Extract local variable
SPC m r R c	Extract constant
SPC m r R l	Extract to let (rspec)

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.