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

#+TITLE: Scala layer

[[file:img/scala.png]] with [[file:img/ensime.png]]

* Table of Contents                                         :TOC_4_gh:noexport:
 - [[#description][Description]]
 - [[#layer-installation][Layer Installation]]
 - [[#ensime][Ensime]]
   - [[#installation][Installation]]
   - [[#usage][Usage]]
 - [[#scalastyle][Scalastyle]]
   - [[#use-java-doc-style][Use Java doc-style]]
 - [[#automatically-show-the-type-of-the-symbol-under-the-cursor][Automatically show the type of the symbol under the cursor]]
 - [[#automatically-insert-asterisk-in-multiline-comments][Automatically insert asterisk in multiline comments]]
 - [[#automatically-replace-arrows-with-unicode-ones][Automatically replace arrows with unicode ones]]
 - [[#auto-start][Auto-start]]
 - [[#key-bindings][Key bindings]]
   - [[#ensime-key-bindings][Ensime key bindings]]
     - [[#search][Search]]
     - [[#sbt][sbt]]
     - [[#typecheck][Typecheck]]
     - [[#debug][Debug]]
     - [[#errors][Errors]]
     - [[#goto][Goto]]
     - [[#print-and-yank-types][Print and yank types]]
     - [[#documentation-inspect][Documentation, Inspect]]
     - [[#server][Server]]
     - [[#refactoring][Refactoring]]
     - [[#tests][Tests]]
     - [[#repl][REPL]]

* Description
This layer adds support for the Scala language using the excellent [[http://ensime.github.io/][ENSIME]]
client/server.

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

* Ensime
[[http://ensime.github.io/][ENSIME]] provides IDE-like features, such as refactoring, incremental compilation
and project-wide type-checking.

ENSIME requires a configuration file at the root of each Scala project. It
provides an SBT plugin to generate these files.

** Installation
Refer to the [[https://ensime.github.io/build_tools/sbt/][Ensime installation instructions]] to install the =sbt-ensime=
plugin.

Please note you have to use a version newer than =0.13.5= of =sbt= in your
project's =project/build.properties=. For example,

#+BEGIN_SRC scala
  sbt.version=0.13.11
#+END_SRC

** Usage
1. Create a =.ensime= file at the root of your Scala project using =sbt
   ensimeConfig= and =sbt ensimeConfigProject= at the shell.
2. Run =M-x ensime= within Emacs to start an ENSIME session.

Each Scala project uses a dedicated ENSIME session, so you only need to run =M-x
ensime= once per project. Any Scala files you create or visit within the project
will automatically use ENSIME for the remainder of your editing session.

* Scalastyle
[[http://www.scalastyle.org/][Scalastyle]] provides style-checking and linting. The Emacs functionality is
provided by Flycheck.

To use scalastyle,

1. Download the [[http://www.scalastyle.org/#download][scalastyle jar]] and put it somewhere sensible
   - If you are a brew user in OSX you can do: =brew install scalastyle=
2. Customise the =flycheck-scalastyle-jar= and =flycheck-scalastylerc= variables
   in your =dotspacemacs/user-config= i.e.:
#+BEGIN_SRC emacs-lisp
   (setq flycheck-scalastyle-jar
         "/usr/local/Cellar/scalastyle/0.8.0/libexec/scalastyle_2.11-0.8.0-batch.jar")
   (setq flycheck-scalastylerc
         "/usr/local/etc/scalastyle_config.xml")
#+END_SRC

See the [[http://www.flycheck.org/en/latest/languages.html?highlight=scala#syntax-checker-scala-scalastyle][flycheck documentation]] and [[http://www.scalastyle.org/configuration.html][scalastyle configuration]] for up-to-date
configuration instructions.

** Use Java doc-style
To enable =java-doc-style=, set the variable =scala-indent:use-javadoc-style= to
=t=

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-indent:use-javadoc-style t)))
#+END_SRC

* Automatically show the type of the symbol under the cursor
To enable the feature =ensime-print-type-at-point= when cursor moves, set the
variable =scala-enable-eldoc= to =t=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-use-java-doc-style t)))
#+END_SRC

Enabling this option can cause slow editor performance.

* Automatically insert asterisk in multiline comments
To insert a leading asterisk in multiline comments automatically, set the
variable =scala-auto-insert-asterisk-in-comments= to =t=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-auto-insert-asterisk-in-comments t)))
#+END_SRC

* Automatically replace arrows with unicode ones
To replace ~=>~, =->= and =<-= with unicode arrows =⇒=, =→= and =←=, set the
variable =scala-use-unicode-arrows= to =t=.

If in some occasions you don't want the arrows replaced (for example when
defining compound operators like ~=>>~), you can always undo the change and get
the ascii arrows back.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-use-unicode-arrows t)))
#+END_SRC

* Auto-start
If you prefer to have Ensime start when you load a scala file, you can enable it
with

#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-auto-start-ensime t)))
#+END_SRC

* Key bindings
** Ensime key bindings
*** Search

| Key Binding | Description                                         |
|-------------+-----------------------------------------------------|
| ~SPC m /~   | incremental search using =ensime-scalex= major mode |
| ~SPC m ?~   | incremental search in all live buffers              |

*** sbt

| Key Binding | Description         |
|-------------+---------------------|
| ~SPC m b .~ | sbt transient state |
| ~SPC m b b~ | sbt command         |
| ~SPC m b c~ | compile             |
| ~SPC m b C~ | clean command       |
| ~SPC m b i~ | switch to sbt shell |
| ~SPC m b p~ | package command     |
| ~SPC m b r~ | run command         |

*** Typecheck

| Key Binding | Description                     |
|-------------+---------------------------------|
| ~SPC m c t~ | type check the current file     |
| ~SPC m c T~ | type check all the open buffers |

*** Debug

| Key Binding | Description                 |
|-------------+-----------------------------|
| ~SPC m d A~ | Attach to a remote debugger |
| ~SPC m d b~ | set breakpoint              |
| ~SPC m d B~ | clear breakpoint            |
| ~SPC m d C~ | clear all breakpoints       |
| ~SPC m d c~ | continue                    |
| ~SPC m d d~ | start a debug session       |
| ~SPC m d i~ | inspect value at point      |
| ~SPC m d l~ | list local variables        |
| ~SPC m d n~ | next                        |
| ~SPC m d o~ | step out                    |
| ~SPC m d q~ | quit                        |
| ~SPC m d r~ | run                         |
| ~SPC m d s~ | step                        |
| ~SPC m d t~ | backtrace                   |

*Note:* These key bindings need a transient-state, PR welcome :-)

*** Errors

| Key Binding | Description                                        |
|-------------+----------------------------------------------------|
| ~SPC m e e~ | print error at point                               |
| ~SPC m e l~ | show all errors and warnings                       |
| ~SPC m e s~ | switch to buffer containing the stack trace parser |

*** Goto

| Key Binding | Description          |
|-------------+----------------------|
| ~SPC m g g~ | go to definition     |
| ~SPC m g i~ | go to implementation |
| ~SPC m g t~ | go to test           |

*** Print and yank types
|-------------+--------------------------------|
| ~SPC m h T~ | print full type name at point  |
| ~SPC m h t~ | print short type name at point |
| ~SPC m y T~ | yank full type name at point   |
| ~SPC m y t~ | yank short type name at point  |

*** Documentation, Inspect

| Key Binding | Description                            |
|-------------+----------------------------------------|
| ~SPC m h h~ | show documentation for symbol at point |
| ~SPC m h u~ | show uses for symbol at point          |
| ~SPC m i i~ | inspect type at point                  |
| ~SPC m i I~ | inspect type in other frame            |
| ~SPC m i p~ | inspect project package                |

*** Server

| Key Binding | Description                                            |
|-------------+--------------------------------------------------------|
| ~SPC m n F~ | reload open files                                      |
| ~SPC m n s~ | start ensime server                                    |
| ~SPC m n S~ | regenerate the =.ensime= and restart the ensime server |

*** Refactoring

| Key Binding | Description                                                          |
|-------------+----------------------------------------------------------------------|
| ~SPC m r a~ | add type annotation                                                  |
| ~SPC m r f~ | format source                                                        |
| ~SPC m r d~ | get rid of an intermediate variable (=ensime-refactor-inline-local=) |
| ~SPC m r D~ | get rid of an intermediate variable (=ensime-undo-peek=)             |
| ~SPC m r i~ | organize imports                                                     |
| ~SPC m r m~ | extract a range of code into a method                                |
| ~SPC m r r~ | rename a symbol project wide                                         |
| ~SPC m r t~ | import type at point                                                 |
| ~SPC m r v~ | extract a range of code into a variable                              |
| ~SPC m z~   | expand/contract region                                               |

*** Tests

| Key Binding | Description              |
|-------------+--------------------------|
| ~SPC m t a~ | test command (sbt)       |
| ~SPC m t r~ | test quick command (sbt) |
| ~SPC m t t~ | test only (sbt)          |

*** REPL

| Key Binding | Description                                                         |
|-------------+---------------------------------------------------------------------|
| ~SPC m s a~ | ask for a file to be loaded in the REPL                             |
| ~SPC m s b~ | send buffer to the REPL                                             |
| ~SPC m s B~ | send buffer to the REPL and focus the REPL buffer in =insert state= |
| ~SPC m s i~ | start or switch to the REPL inferior process                        |
| ~SPC m s r~ | send region to the REPL                                             |
| ~SPC m s R~ | send region to the REPL and focus the REPL buffer in =insert state= |