#+TITLE: Ruby contribution layer for Spacemacs

[[file:img/ruby.png]]

* Table of Contents                                                   :TOC@4:
 - [[#description][Description]]
 - [[#install][Install]]
   - [[#prerequisites][Prerequisites]]
   - [[#ruby-version-management][Ruby version management]]
 - [[#key-bindings][Key bindings]]
   - [[#ruby-enh-ruby-mode-robe-inf-ruby-ruby-tools][Ruby (enh-ruby-mode, robe, inf-ruby, ruby-tools)]]
   - [[#ruby-test-mode][ruby-test-mode]]

* Description

This layer aims at providing support for the Ruby language using
[[https://github.com/zenspider/enhanced-ruby-mode][enh-ruby-mode]] and [[https://github.com/dgutov/robe][robe-mode]].

* Install

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

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(ruby))
#+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=

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/user-init ()
    (setq-default ruby-version-manager 'rbenv)
  )
#+END_SRC

Possible values are =rbenv= and =rvm=.

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

** ruby-test-mode

ruby-test-mode comes bundled with spacemacs, but this contribution adds
a couple of useful keybindings:

| Key binding | Description         |
|-------------+---------------------|
| ~SPC m t b~ | run test file       |
| ~SPC m t t~ | run test at pointer |