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

#+TITLE: Purescript layer

[[file:img/purescript-logo.png]]

* Table of Contents                                         :TOC_4_gh:noexport:
- [[#description][Description]]
- [[#install][Install]]
- [[#configuration][Configuration]]
  - [[#add-import-on-completion][Add import on completion]]
  - [[#error-popup][Error popup]]
- [[#key-bindings][Key bindings]]
  - [[#purescript][Purescript]]
    - [[#imports][Imports]]
    - [[#psc-ide][psc-ide]]
  - [[#repl][REPL]]

* Description
This layer provides basic Purescript editing support for spacemacs
thanks to the following packages:
- [[https://github.com/dysinger/purescript-mode][purescript-mode]]
- [[https://github.com/ardumont/emacs-psci][psci]]
- [[https://github.com/epost/psc-ide-emacs][psc-ide-emacs]]

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

You'll also need to make sure the PureScript compiler and its associated
binaries (psc-ide-server, psci,...) are on your path. Installation instructions
can be found [[https://github.com/purescript/documentation/blob/master/guides/Getting-Started.md][here]].

* Configuration
** Add import on completion
Set =purescript-add-import-on-completion= to nil to make =psc-ide= stop adding
imports on completion. Default value it =t=.

** Error popup
If you set =purescript-enable-rebuild-on-save= to non-nil, you will get a popup
buffer showing you your current warnings/errors one at a time. This is primarily
meant as an alternative to using flycheck. Default value is nil.

* Key bindings
** Purescript
*** Imports

| Key Binding | Description                                                   |
|-------------+---------------------------------------------------------------|
| ~SPC m i =~ | Format imports                                                |
| ~SPC m i \~ | Return to where you were editing before navigating to imports |
| ~SPC m i a~ | Align imports                                                 |
| ~SPC m i n~ | Navigate to the imports                                       |

*** psc-ide
=psc-ide= command are available under ~SPC m m~:

| Key Binding   | Description                                                               |
|---------------+---------------------------------------------------------------------------|
| ~SPC m m s~   | Start psc-ide-server                                                      |
| ~SPC m m l~   | Load definitions for the modules inside your project                      |
| ~SPC m h t~   | Show type at point                                                        |
| ~SPC m g g~   | Goto definition for identifier at point                                   |
| ~SPC m m b~   | Rebuilds the current file and displays any warnings or errors             |
| ~SPC m m i a~ | Add an import for the identifier at the current cursor position           |
| ~SPC m m i s~ | Inserts a suggestion for the warning/error at the current cursor position |
| ~SPC m m t~   | Add a new clause for the function signature at point                      |
| ~SPC m m c s~ | Casesplits on the identifier at the current cursor position               |
| ~SPC m m q~   | Quit the current psc-ide-server                                           |
| ~SPC m m L~   | Load a specific module (This is mostly used for troubleshooting)          |

** REPL
[[https://github.com/ardumont/emacs-psci][psci]] provides a very basic REPL for purescript. The following key
bindings are available:

| Key Binding | Description                                                                      |
|-------------+----------------------------------------------------------------------------------|
| ~SPC m s b~ | Equivalent of =:m /path/to/current/module/file.purs= - Load <file> for importing |
| ~SPC m s i~ | Launch a psci console buffer                                                     |
| ~SPC m s m~ | Equivalent of =:i your.current.module.name= - Import <module> for use in PSCI    |
| ~SPC m s p~ | Load or reload files defined in the project file .psci                           |