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

#+TITLE: Haskell contribution layer for Spacemacs

[[file:img/haskell.png]]

* Table of Contents                                                   :TOC@4:
 - [[#description][Description]]
   - [[#features][Features:]]
 - [[#install][Install]]
   - [[#layer][Layer]]
   - [[#dependencies][Dependencies]]
   - [[#setup-path][Setup PATH]]
   - [[#os-x][OS X]]
   - [[#optional-extras][Optional extras]]
     - [[#ghc-mod-support][ghc-mod support]]
     - [[#ghci-ng-support][GHCi-ng support]]
     - [[#structured-haskell-mode][structured-haskell-mode]]
     - [[#hindent][hindent]]
 - [[#key-bindings][Key bindings]]
   - [[#documentation][Documentation]]
   - [[#debug][Debug]]
   - [[#repl][REPL]]
   - [[#cabal-commands][Cabal commands]]
   - [[#cabal-files][Cabal files]]
 - [[#faq][FAQ]]
   - [[#repl-doesnt-work][REPL doesn't work]]
   - [[#repl-is-stuck][REPL is stuck]]
   - [[#i-am-using-stack-and-ghc-mod-but-ghc-mod-doesnt-work][I am using =stack= and =ghc-mod=, but =ghc-mod= doesn't work]]

* Description
This layer adds support for the [[https://www.haskell.org/][Haskell]] language.

** Features:
- auto-completion with [[https://github.com/iquiw/company-ghc][company-ghc]],
- syntax highlighting for [[https://github.com/bgamari/cmm-mode][C-- source]].

*This layer is in construction, it needs your contributions and bug reports.*

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

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

** Dependencies
This layer requires some [[https://www.haskell.org/cabal/][cabal]] packages:
- =hlint=
- =stylish-haskell=
- =hasktags=

You can install them using =cabal= or =stack=. =Cabal= users should use
following command:

#+BEGIN_SRC sh
  $ cabal install stylish-haskell hlint hasktags
#+END_SRC

=Stack= users should use following command:

#+BEGIN_SRC sh
  $ stack install stylish-haskell hlint hasktags
#+END_SRC

** Setup PATH
First of all make sure that your =$PATH= contains the installation path for
Haskell tools like =ghc=, =ghci= etc. It depends on how you have installed
=ghc=, but you can always check it by running =which ghc= in your terminal.
=Stack= users should add only the installation path of =stack= itself. Usually
it's =~/.local/bin=.

Then make sure that your =$PATH= contains the installation path for =cabal=
packages. If you are using =cabal= it should be =~/.cabal/bin= or
=/Users/<username>/Library/Haskell/bin= (for 'Haskell for Mac' users). If you
are using =stack= then it should be =~/.local/bin=.

For information about setting up =$PATH=, check out the corresponding section in
the FAQ (~SPC f e h $PATH RET~).

** OS X
Note that =emacs.app= for OS X does not pick up =$PATH= from =~/.bashrc= or
=~/.zshrc= when launched from outside a terminal.

** Optional extras
The Haskell layer supports some extra features that can be enabled through
layer variables.

*** ghc-mod support
[[http://www.mew.org/~kazu/proj/ghc-mod/][ghc-mod]] enhances =haskell-mode= with for example templates, case-splitting and
much more. In order to use it you need to install the executable with

#+BEGIN_SRC sh
  $ cabal install ghc-mod
#+END_SRC

=Stack= users should use following command:

#+BEGIN_SRC sh
  $ stack install ghc-mod --resolver nightly-2015-10-07
#+END_SRC

and set the layer variable:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((haskell :variables haskell-enable-ghc-mod-support t)))
#+END_SRC

=Stack= users also should make sure that =dist/setup-config= doesn't exist in
the project root. As it will confuse =ghc-mod=. For more troubleshooting,
checkout this [[https://github.com/kazu-yamamoto/ghc-mod/wiki#known-issues-related-to-stack][document]].

*** GHCi-ng support
[[https://github.com/chrisdone/ghci-ng][ghci-ng]] adds some nice features to =haskell-mode=, and is supported in
Spacemacs by a layer variable:

Follow the instructions to install [[https://github.com/chrisdone/ghci-ng][ghci-ng]] (remember to add =:set +c=
in =~/.ghci=, next set the layer variable:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((haskell :variables haskell-enable-ghci-ng-support t)))
#+END_SRC

Once ghci-ng is enabled, two of the old keybindings are overriden with
improved versions from ghci-ng, and a new keybinding available:

| Key Binding | Description                                                               |
|-------------+---------------------------------------------------------------------------|
| ~SPC m h t~ | gets the type of the identifier under the cursor or for the active region |
| ~SPC m g g~ | go to definition                                                          |
| ~SPC m u~   | finds uses of identifier                                                  |

*** structured-haskell-mode
[[https://github.com/chrisdone/structured-haskell-mode][structured-haskell-mode]], or shm, replaces default haskell-mode
auto-indentation and adds some nice functionalities.

To Install =shm= with cabal run following command:

#+BEGIN_SRC sh
  $ cabal install structured-haskell-mode
#+END_SRC

=Stack= users should use following command:

#+BEGIN_SRC sh
  $ stack install structured-haskell-mode
#+END_SRC

To enable =shm= set the layer variable:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((haskell :variables haskell-enable-shm-support t)))
#+END_SRC

After shm has been enabled, some of the evil normal state bindings are overridden:

| Key Binding | Description         |
|-------------+---------------------|
| ~D~         | =shm/kill-line=     |
| ~R~         | =shm/raise=         |
| ~P~         | =shm/yank=          |
| ~(~         | =shm/forward-node=  |
| ~)~         | =shm/backward-node= |

For a nice visualization of these functions, please refer to the github page
for [[https://github.com/chrisdone/structured-haskell-mode#features][structured-haskell-mode]].

*** hindent
[[https://github.com/chrisdone/hindent][hindent]] is an extensible Haskell pretty printer, which let's you
reformat your code. You need to install the executable with =cabal
install hindent= or =stack install hindent=

To enable it you have to set the variable =haskell-enable-hindent-style=
to a supported style. The available styles are:
- fundamental
- johan-tibell
- chris-done
- gibiansky

See examples [[https://github.com/chrisdone/hindent#example][here]]

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((haskell :variables haskell-enable-hindent-style "johan-tibell")))
#+END_SRC

* Key bindings
All Haskell specific bindings are prefixed with the major-mode leader
~SPC m~.

Top-level commands are prefixed by ~SPC m~:

| Key Binding | Description                                                         |
|-------------+---------------------------------------------------------------------|
| ~SPC m g g~ | go to definition or tag                                             |
| ~SPC m g i~ | cycle the Haskell import lines or return to point (with prefix arg) |
| ~SPC m f~   | format buffer using haskell-stylish                                 |
| ~SPC m F~   | format declaration using hindent (if enabled)                       |

** Documentation
Documentation commands are prefixed by ~SPC m h~

| Key Binding | Description                                                                |
|-------------+----------------------------------------------------------------------------|
| ~SPC m h d~ | find or generate Haddock documentation for the identifier under the cursor |
| ~SPC m h h~ | do a Hoogle lookup                                                         |
| ~SPC m h H~ | do a local Hoogle lookup                                                   |
| ~SPC m h i~ | gets information for the identifier under the cursor                       |
| ~SPC m h t~ | gets the type of the identifier under the cursor                           |
| ~SPC m h y~ | do a Hayoo lookup                                                          |

** Debug
Debug commands are prefixed by ~SPC m d~:

| Key Binding | Description                                |
|-------------+--------------------------------------------|
| ~SPC m d d~ | start debug process, needs to be run first |
| ~SPC m d b~ | insert breakpoint at function              |
| ~SPC m d n~ | next breakpoint                            |
| ~SPC m d N~ | previous breakpoint                        |
| ~SPC m d B~ | delete breakpoint                          |
| ~SPC m d c~ | continue current process                   |
| ~SPC m d a~ | abandon current process                    |
| ~SPC m d r~ | refresh process buffer                     |

** REPL
REPL commands are prefixed by ~SPC m s~:

| Key Binding | Description                                     |
|-------------+-------------------------------------------------|
| ~SPC m s b~ | load or reload the current buffer into the REPL |
| ~SPC m s c~ | clear the REPL                                  |
| ~SPC m s s~ | show the REPL                                   |
| ~SPC m s S~ | show and switch to the REPL                     |

** Cabal commands
Cabal commands are prefixed by ~SPC m c~:

| Key Binding | Description                                                |
|-------------+------------------------------------------------------------|
| ~SPC m c a~ | cabal actions                                              |
| ~SPC m c b~ | build the current cabal project, i.e. invoke =cabal build= |
| ~SPC m c c~ | compile the current project, i.e. invoke =ghc=             |
| ~SPC m c v~ | visit the cabal file                                       |

** Cabal files
This commands are available in a cabal file.

| Key Binding | Description                                 |
|-------------+---------------------------------------------|
| ~SPC m d~   | add a dependency to the project             |
| ~SPC m b~   | go to benchmark section                     |
| ~SPC m e~   | go to executable section                    |
| ~SPC m t~   | go to test-suite section                    |
| ~SPC m m~   | go to exposed modules                       |
| ~SPC m l~   | go to libary section                        |
| ~SPC m n~   | go to next subsection                       |
| ~SPC m p~   | go to previous subsection                   |
| ~SPC m N~   | go to next section                          |
| ~SPC m P~   | go to previous section                      |
| ~SPC m f~   | find or create source-file under the cursor |

* FAQ
** REPL doesn't work
Usually =haskell-mode= is great at figuring out which interactive process to
bring up. But if you are experiencing problems with it you can help
=haskell-mode= by setting =haskell-process-type= as in following code:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers
    '((haskell :variables haskell-process-type 'stack-ghci)))
#+END_SRC

Available options are:

- ghci
- cabal-repl
- cabal-dev
- cabal-ghci
- stack-ghci

** REPL is stuck
Make sure that when you are typing anything in REPL there is a space between
what you type and =λ>=. When there is no space - REPL will behave as it's stuck.
Usually, when you enter normal state, cursor is moved back, so there is no
required space when you switch to insert mode. There is possible workaround -
just add following snippet to your =dotspacemacs/user-config= function:

#+BEGIN_SRC emacs-lisp
  (when (configuration-layer/layer-usedp 'haskell)
    (add-hook 'haskell-interactive-mode-hook
              (lambda ()
                (setq-local evil-move-cursor-back nil))))
#+END_SRC

It will make cursor stay at the right place in the REPL buffer when you enter
normal state. Which in most cases helps you to avoid the problem with 'stuck'
REPL.

Also, some users might want to start REPL in insert mode. For this to happen you
could place following snippet in your =dotspacemacs/user-config= function:

#+BEGIN_SRC emacs-lisp
(when (configuration-layer/layer-usedp 'haskell)
    (defadvice haskell-interactive-switch (after spacemacs/haskell-interactive-switch-advice activate)
      (when (eq dotspacemacs-editing-style 'vim)
        (call-interactively 'evil-insert))))
#+END_SRC

** I am using =stack= and =ghc-mod=, but =ghc-mod= doesn't work
Make sure that =dist= directory doesn't exist in your project root. So if it
exists, just remove it and try again.