#+TITLE: Ruby contribution layer for Spacemacs
#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../../../css/readtheorg.css" />

[[file:img/ruby.png]]

* Table of Contents                                         :TOC_4_org:noexport:
 - [[Description][Description]]
 - [[Install][Install]]
   - [[Prerequisites][Prerequisites]]
   - [[Ruby version management][Ruby version management]]
   - [[Test runner][Test runner]]
 - [[Key bindings][Key bindings]]
   - [[Ruby (enh-ruby-mode, robe, inf-ruby, ruby-tools)][Ruby (enh-ruby-mode, robe, inf-ruby, ruby-tools)]]
   - [[RuboCop][RuboCop]]
   - [[Tests][Tests]]
     - [[RSpec-mode][RSpec-mode]]
     - [[Ruby-test-mode][Ruby-test-mode]]

* Description
This layer provides support for the Ruby language with [[https://github.com/zenspider/enhanced-ruby-mode][enh-ruby-mode]] and [[https://github.com/dgutov/robe][robe-mode]].
Optionally Enh Ruby Mode can be replaced with the built-in Emacs Ruby Mode.

* Install
To use this contribution add it to your =~/.spacemacs=

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(ruby))
#+END_SRC

This layer supports two different Ruby modes: Emacs' built-in Ruby Mode and
[[https://github.com/zenspider/enhanced-ruby-mode][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:

#+BEGIN_SRC emacs-lisp
  (defun dotspacemacs-configuration-layers ()
     '((ruby :variables ruby-enable-enh-ruby-mode t)))
#+END_SRC

** 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.:

#+BEGIN_SRC ruby
  gem 'pry'
#+END_SRC

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

#+BEGIN_SRC sh
  gem install pry
#+END_SRC

** Ruby version management
This layer supports the use of [[https://rvm.io/][RVM]] and [[https://github.com/sstephenson/rbenv][Rbenv]].
To enable it, set the =ruby-version-manager= var in your =~/.spacemacs=:

#+BEGIN_SRC emacs-lisp
  (defun dotspacemacs-configuration-layers ()
     '((ruby :variables ruby-version-manager 'rbenv)))
#+END_SRC

Possible values are =rbenv= and =rvm=.

** Test runner
This layer supports both =RSpec= and =ruby-test= 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=:

#+BEGIN_SRC emacs-lisp
  (defun dotspacemacs-configuration-layers ()
     '((ruby :variables ruby-test-runner 'rspec)))
#+END_SRC

=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 d~ | go to Documentation                                  |
| ~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                              |
| ~%~         | [[https://github.com/redguardtoo/evil-matchit][evil-matchit]] jumps between blocks                    |

** 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 l~ | run last failed spec |
| ~SPC m t r~ | re-run last spec     |
| ~SPC m t t~ | run spec at pointer  |

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