NOTE: THIS IS A MIRROR

Please submit issues, feature requests and PRs to https://gitlab.com/gopiandcode/gopcaml-mode

Gopcaml Ocaml Emacs Major Mode

The ultimate ocaml editing mode.

Features

• AST-based code navigation - C-M-n, C-M-p, C-M-u, C-M-d, C-M-f, C-M-b

• AST-based code transformation -C-M-N, C-M-P, C-M-F, C-M-B

• Fixed move-to-defun, move-to-end-defun -C-M-a, C-M-e

• Jump to type hole - TAB

• Automatic let binding expansion (i.e adds in automatically if defining let inside a let)

• Mark exp - C-M-SPC

• Move to nearest parameter - C-c C-p

• Move to nearest let def - C-c C-o

• Extract expression into letdef - C-c C-e

Installation

Gopcaml mode is implemented using a mixture of ocaml and elisp.

Make sure your emacs is compiled with dynamic modules support (you may need to build emacs from source with the --with-modules option).

Note: If you get an error about ELF headers this means that your emacs doesn't support dynamic modules - you'll need to build emacs from source (takes ~5 minutes usually).

• Install the project via opam:

opam install gopcaml-mode

• install merlin, ocp-indent and tuareg mode
• load the project in your init.el

 (let ((opam-share (ignore-errors (car (process-lines "opam" "config" "var" "share")))))
	   (when (and opam-share (file-directory-p opam-share))
	     ;; Register Gopcaml mode
	     (add-to-list 'load-path (expand-file-name "emacs/site-lisp" opam-share))
         (autoload 'gopcaml-mode "gopcaml-mode" nil t nil)
         (autoload 'tuareg-mode "tuareg" nil t nil)
         (autoload 'merlin-mode "merlin" "Merlin mode" t)
	     ;; Automatically start it in OCaml buffers
	     (setq auto-mode-alist
		   (append '(("\\.ml[ily]?$" . gopcaml-mode)
			     ("\\.topml$" . gopcaml-mode))
			   auto-mode-alist))
	     ))

Enjoy your ultimate editing experience.

Extras

• For some additional features that aren't included in the main release, see the extras folder

Development

If you want to tinker with this project/extend it/build your own version, see below:

Project Structure

The core project laid out as follows:

├── gopcaml.ml
├── gopcaml_state.ml
├── ast_zipper.ml
├── ast_analysis.ml
├── ast_transformer.ml
├── gopcaml-mode.el
├── gopcaml-multiple-cursors.el
└── gopcaml-smartparens.el

The purpose of each file is defined as follows (in the order in which you'd probably want to look at them):

• gopcaml.ml

  • defines the main entrypoint for the module
  • this is where all the functions bindings to emacs are setup

• gopcaml_state.ml

  • defines functions to parse and track a copy of the AST for use in other components

• ast_zipper.ml

  • defines a huet-style scarred zipper for the OCaml AST.
  • the zipper operates in a lazy fashion - i.e the AST is only expanded into the zipper type when the user expicitly requests it

• ast_analysis.ml

  • contains functions that perform analysis over the AST (i.e things like finding the free variables in an expression, etc.)
  • ast_transformer.ml should be moved into here at some point

• gopcaml-mode.el

  • main elisp plugin file
  • takes the functions exported by gopcaml.ml and provides wrappers to make them more robust

• gopcaml-*.el

  • optional features that are loaded in when the required packages are also loaded
  • allows for better compatibility with other emacs packages (i.e for example, disabling ast-movement when at the start of a parens so smartparens can work )

Architecture

• There are two main interesting components to gopcaml-mode
• Tracking OCaml Ast
  • in order to work, gopcaml mode needs to have a copy of the ocaml ast that (typically*) needs to be up to date with the buffer contents
  • to achieve this while maintaining a fluid user experience this is achieved through to measures:
    • invalidating on changes:
      • when any change is made to the buffer, the state is invalidiated (see gopcaml_state.ml/State/DirtyRegion/update)
      • if the user runs a command that requires the ast and the ast is invalidated, then we try and rebuild the ast (see gopcaml_state.ml/State/Validated/of_state.ml).
    • periodic rebuilding:
      • when gopcaml-mode is started, an idle timer is setup to periodically check if the AST is out of date and rebuild it when the user doesn't perform any changes for a while
      • this just means that we can perform AST reconstruction during idle time, and reduces the cost of moving after changes *sometimes we don't care if the ast is out of date/we're doing analysis during a time when we know the ast will not be constructable (i.e for example if implementing a function to check whether we are writing text inside a letbinding (see gopcaml_state.ml/inside_let_def)) - in this case we can try and retrieve an old copy of the state (see gopcaml_state.ml/State/Validated/of_state_immediate)
• Zipper-mode
  • zipper-mode is the terminology given to the transient mode that is entered when the user performs strucutural movement.
  • when a structural command is run for the first time, we retrieve the ast and create a zipper and store it in a buffer-local-varaible (see gopcaml_state.ml/build_zipper_enclosing_point)
  • all subsequent movement commands retrieve the zipper from this variable and use it to move the emacs cursor and the overlay highlighting the selected item
  • transformation operations also use the zipper to update the buffer, but have to take extra care to ensure that they also update the state of the zipper to reflect the changes in the ast (as the zipper, unlike the ast isn't periodically updated) (see ast_zipper.ml/move_(left|right|up|down))
  • when any command that isn't a structural editing one is pressed, the transient mode ends, and the zipper variable is cleared.
  • Note: the fact that the zipper is in a separate variable from the ast deliberately means that the zipper may become desynchronized from the ast - for example, if we perform an AST transformation using the zipper, then the original ast will not be up to date. This is mainly just to avoid unnecassary work - rather than writing transformation functions twice for the ast and zipper, we write them once for the zipper (taking sure to ensure that the meta-information stored in the zipper is kept up to date), and then let the automatic rebuilding functionality handle updating the original ast.

Setting up the development environment

Being an emacs plugin, the development environment setup is tailored for emacs.

• Clone the repo from gitlab https://gitlab.com/gopiandcode/gopcaml-mode
• Build the project with dune build
• in your init.el where gopmacs is loaded, add the following:

(add-to-list
	'command-switch-alist
	(cons "gopdev"  (lambda (__) nil)))
	
(if (member "-gopdev" command-line-args) (setq gopcaml-dev-mode t))

(if (or (not (boundp 'gopcaml-dev-mode)) (not gopcaml-dev-mode))
   ... ;; run normal gopcaml initialization code (i.e from the install instructions)
)

• Now launch emacs passing the flag -gopdev and open any file inside the project directory.
• When prompted press y or ! to setup the development variables for the file.
• Now this instance of emacs will use your local branch to load gopcaml-mode (It's quite nice developing in this way, as any changes you make will be reflected in your editor, and can quickly be tried out**.

Note: My typical development setup is to have a command prompt open in the background and execute dune build && emacs -gopdev ./<some-file>.ml. I make some changes, use merlin to ensure there are no issues, exit and press up on my terminal to reload the prior command and press enter.

Note*: The reason for the complicated setup is that gopcaml-mode uses dynamic modules to call out to ocaml mode from emacs, and dynamic modules can only be loaded into an emacs instance once - thus each time you make a change, you'll need to restart emacs.