This minor mode provides structured editing operations based on the syntax of Haskell. In short-hand it's called SHM and throughout the codebase, too. It acts a bit like, and is heavily inspired by, paredit-mode for Emacs.
In using structured-haskell-mode you will find that your layout style will change and become more regular as the editor does the menial work for you. Given that, some assumptions about style are made in structured-haskell-mode and are best described by this style guide.
Its features work by parsing the current declaration with an
structured-haskell-mode, and then creates marks
for all the nodes' positions in the buffer.
In paredit-mode, manipulation of the tree is so enjoyable because all the boundaries of nodes are explicitly specified by parentheses. Not so, in Haskell. To get around this limitation, we have a “current” node, which is always highlighted with a background color. With that in place, one is able to do all of the operations that paredit can do.
Feature | Explanation
--- | --- | ---
C-j) takes the current node and its type into consideration giving very predictable and useful behaviour.
| Going to parent:
M-a) jumps to the start of the parent.
| Going to parent end:
)) jumps to the end of the parent.
| Adding a list item:
C-j) will automatically add a comma when inside a list.
| Adding operands:
C-+) will look at the current node and add another operand in the direction the cursor is leaning towards.
| Auto-reindenting: Typing and deleting will automatically re-indent dependent code blocks.
M-r) raises the current node to replace its parent. If its direct parent is not the same expression type, it continues up the tree.
M-^) allow you to bring nodes inwards or outwards relative to the parent.
| Record syntax: Creating new elements with record syntax, like lists (and tuples) automatically adds the right separators.
C-M-t) will swap two sibling nodes. Currently removed
C-y) take indentation into account, and automatically normalize so that re-inserting will indent properly.
| Killing lines:
C-y) also take indentation into account for killing and pasting, working with multiple lines at once happily.
shm.el for other keybindings. You might want to disable or
change some of the bindings to suit your tastes.
How to enable
Clone the project:
$ git clone https://github.com/chrisdone/structured-haskell-mode.git
You need to install the structured-haskell-mode executable which does the parsing.
$ cd structured-haskell-mode $ cabal install
Add the elisp library to your
load-path and require the library.
(add-to-list 'load-path "/path/to/structured-haskell-mode/elisp") (require 'shm)
Then add it to your haskell-mode-hook:
(add-hook 'haskell-mode-hook 'structured-haskell-mode)
Turn off haskell-indentation-modes. They are incompatible with structured-haskell-mode. It has its own indentation functionality.
You'll want to customize these two variables:
shm-current-face to something that better suites your color
The following are apparently pretty good for solarized-light.
(set-face-background 'shm-current-face "#eee8d5") (set-face-background 'shm-quarantine-face "lemonchiffon")
Checking it works
Some users have trouble with the executable being in their PATH properly. That's fine, here's how to check that you're setup.
Open a Haskell file and go to a syntactically valid declaration, e.g.
main = return ().
Check that your modeline contains
SHM!means a parse error.
SHM?means it hasn't been able to parse anything yet.
Both in this scenario should not appear, if they do, see the next steps.
If your modeline is not
SHM and the current declaration doesn't have
a grey box anywhere in it, then you have a problem.
Go back to the declaration and try
M-x shm/test-exe. You should be
taken to a
*shm-scratch-test* buffer containing a vector of source
spans. If you don't, and you have something more like "program not
found", then you need to make sure it's findable.
You can try:
Set the Emacs
(setenv "PATH" (shell-command-to-string "echo $PATH"))
Set the binary path that SHM calls:
(setq shm-program-name "/absolute/path/to/structured-haskell-mode")
exec-path-from-shellpackage here and try that.
After that, disable and re-enable
emacs -Q --batch shm.el --eval "(progn (add-to-list 'load-path \".\") (emacs-lisp-byte-compile))"
You can run the tests with the following command line:
emacs -l shm-ast-documentation.el \ -l shm.el \ -l shm-test.el \ -l shm-tests.el \ --eval '(shm-test/run-all)' \ --debug
To write tests there's a script for making them. Run
M-x shm-test/new and follow the instructions that look something like
-- Steps to create a test -- -- 1. Insert the test-case setup code. -- 2. Move the cursor to the starting point. -- 3. Hit C-c C-c to record cursor position. -- 4. Press F3 to begin recording the test actions. -- 5. Do the action. -- 6. Hit F4 to complete the action and run C-c C-c.
Then copy the resulting elisp to shm-tests.el and run the tests to check it works properly.
What does it use to parse?
It uses haskell-src-exts to parse code. It could just as easily use GHC as a backend, but from benchmarks, GHC is only twice as fast. When it's the difference between 15ms and 30ms for a 400 line module, it really does not matter. We're parsing declarations and individual nodes. Plus the GHC tree is more annoying to traverse generically due to its partiality.
Reporting a bug
To get extra useful information, always run:
M-: (setq debug-on-error t)
And then re-run the same thing that gave you the problem. It will give you a backtrace that you can paste into the issue.
When reporting a bug, please write in the following format:
[Any general summary/comments if desired] Steps to reproduce: Type blah in the buffer. Hit x key. See some change z. Hit y key. Expected: What I expected to see and happen. Actual: What actually happened.