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]]
 - [[#disable-auto-start][Disable 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 [[https://github.com/ensime][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
[[https://github.com/ensime][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
Configure the ENSIME sbt plugin by adding the following to
=~/.sbt/0.13/plugins/plugins.sbt=:

#+BEGIN_SRC scala
  addSbtPlugin("org.ensime" % "ensime-sbt" % "0.2.3")
#+END_SRC

Please go to [[https://github.com/ensime/ensime-sbt][ensime-sbt Github Page]] to check the latest version of =ensime-sbt= plugin.

Please note your projects' =project/build.properties= need to use a version
newer that =0.13.5= of sbt.
#+BEGIN_SRC scala
  sbt.version=0.13.9
#+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://flycheck.readthedocs.org/en/latest/guide/languages.html#el.flycheck-checker.scala-scalastyle][Scalastyle]] provides style-checking and linting. The Emacs functionality is
provided by Flycheck.

To use scalastyle,

1. Download the [[https://oss.sonatype.org/content/repositories/releases/org/scalastyle/scalastyle_2.11/0.6.0/][scalastyle jar]] and put it somewhere sensible
2. Customise the =flycheck-scalastyle-jar= variable and set it to the path of
   the jar.

See the [[http://flycheck.readthedocs.org/en/latest/guide/languages.html#el.flycheck-checker.scala-scalastyle][flycheck documentation]] 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

* Disable auto-start
If you prefer not to have Ensime start when you load a scala file, you can
disable it with

#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(
    (scala :variables scala-auto-start-ensime nil)))
#+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 c~ | compile command     |
| ~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= |