Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/emacsmirror/fennel-mode

A major-mode for editing Fennel code
https://github.com/emacsmirror/fennel-mode

Last synced: 8 days ago
JSON representation

A major-mode for editing Fennel code

Awesome Lists containing this project

README 

        
# Fennel Mode



Font-lock, indentation, navigation, documentation, and REPL support for the

[Fennel](https://fennel-lang.org) programming language.



Supports `M-x imenu` for quick navigation to local definitions.



## Installation



Add this to your config:



```lisp

(autoload 'fennel-mode "/path/to/fennel-mode/fennel-mode" nil t)

(add-to-list 'auto-mode-alist '("\\.fnl\\'" . fennel-mode))

```



Note that `fennel-mode` doesn't inherit from `lisp-mode` since 0.4.0, and

instead switched to `prog-mode`.  This means that there is no longer any way to

declare shared functionality (such as paredit) that you want to be applied to every

lisp you use; you have to add hooks specifically to `fennel-mode-hook`.



You'll also probably want to use [fennel-ls][8], which works great

with [eglot][9]. In Emacs 30+, it will work automatically once

`fennel-ls` is installed; in earlier versions you need to add this to

your config:



```lisp

(with-eval-after-load 'eglot

  (add-to-list 'eglot-server-programs '(fennel-mode . ("fennel-ls"))))

```



## Interactivity



Run `M-x fennel-repl RET` to open a REPL buffer.  Once a REPL is open,

you can send code from a `fennel-mode` buffer to be evaluated.



### Bindings for `fennel-mode`



* `M-.`        - Jump to the definition of a globally-visible function

* `M-,`        - Jump back to where you were before jumping to definition

* `M-'`        - Jump to the definition of a function in a module

* `C-c C-k`    - Reload the module for the current file (requires `fennel.seacher`)

* `C-c C-l`    - Display compilation output for the current file

* `C-c C-z`    - Start or switch to REPL buffer

* `C-c C-t`    - Reformat current buffer with [fnlfmt][1] (separate install)

* `C-c C-d`    - Ask for a value and show its docstring in the REPL (also `C-c C-f`)

* `C-c C-v`    - Show docstring of variable at point

* `C-c C-p`    - Print macro expansion of expression at point in the REPL

* `C-x C-e`    - Evaluate last expression before the point

* `C-c C-e`    - Evaluate current top-level form (also `C-M-x`)

* `C-c C-n`    - Evaluate current top-level form, then move to the next

* `C-c C-r`    - Evaluate the region

* `C-c C-z`    - Start or switch to REPL buffer



### Bindings for `fennel-repl-mode`



* `TAB`        - Completion at point

* `C-c M-o`    - Clear the REPL output

* `C-c C-d`    - Ask for a value and show its docstring in the REPL (also `C-c C-f`)

* `C-c C-v`    - Show docstring of variable at point

* `M-.`        - Jump to the definition of a globally-visible function

* `C-c C-z`    - Toggle back to previous `fennel-mode` buffer

* `C-c C-q`    - Quit the REPL



These functions assume a `fennel` executable is present on your

path.  You can override the location by setting `inferior-lisp-program`

or invoking `C-u M-x fennel-repl`.  For instance, if you have [a stdio

REPL][2] in a [LÖVE][3] game, you can set this to `love .`.



Note that finding the definition of a function with `M-.` only works when the

function is in scope for the REPL, which means it's usually best to

load a module and set it as a global if you want to use it this way.



## Antifennel



This repo also contains `antifennel.el` which allows you to compile

Lua code to Fennel straight from a `lua-mode` buffer.  It requires

installing [antifennel][6] first.  Install it with:



```lisp

(autoload 'antifennel-mode "/path/to/fennel-mode/antifennel.el" nil t)

(add-hook 'lua-mode-hook 'antifennel-mode)

```



Now when `antifennel-mode` is active in a Lua buffer, you can press

`C-c C-f` to open a new buffer containing the Fennel equivalent of the

Lua code.



## Protocol-based REPL



A separate REPL integration is provided via the `fennel-proto-repl`

module.  This module provides a client that can connect to a regular

Fennel REPL, *upgrade* it with the [protocol][7] code, and provides a

more robust interactive experience.  Advantages over the default

`fennel-repl` are:



* IO and evaluation results are separated.

* Stack traces in Errors can be used to jump to the error location.

* Evaluation results are shown in the echo area - no need to keep the

  REPL window open.

* Running multiple REPLs is easier, and different buffers can be

  linked to different REPLs.

* Synchronous and Asynchronous API.

* Support for Eldoc and Xref.



Installation is similar to the other modules:



```lisp

(autoload 'fennel-proto-repl "/path/to/fennel-mode/fennel-proto-repl.el" nil t)

(add-hook 'fennel-mode-hook 'fennel-proto-repl-minor-mode)

```



The `fennel-proto-repl-minor-mode` re-binds all of the default REPL

interaction keys available in `fennel-mode` to use `fennel-proto-repl`

instead of a regular `fennel-repl`.  In addition to the usual

`fennel-mode` mappings listed above, additional commands are

available:



* `C-c C-S-l` - link the current buffer to a specific REPL session

* `C-c C-b`   - Evaluate the whole buffer

* `C-c C-a`   - Ask for a function and show its argument list in the REPL



Starting the REPL or switching to the existing one is done via the

same `C-c C-z` shortcut, and the new REPL session can be started at

any moment with the `fennel-proto-repl` command.  The buffer is

automatically linked to the newly created REPL.



Note that `fennel-proto-repl` requires a Fennel version recent enough

to include the `___repl___` variable.  If the Fennel doesn't have the

`___repl___` variable the Proto REPL won't be started.



## Org Babel support



Installation is similar to the other modules:



```lisp

(autoload 'ob-fennel "/path/to/fennel-mode/ob-fennel.el" nil t)

```



Then, the support for Fennel in Org buffers can be activated by adding

the following code to the Emacs init file:



```lisp

(with-eval-after-load 'org

  (require 'ob-fennel))

```



After that, the `#+begin_src fennel` code blocks can be executed in

Org buffers.  The integration requires the `fennel-proto-repl` module

to be available and operational.



The `ob-fennel` module supports evaluating code from the regular "src

blocks", and "inline src blocks" (`src_fennel[]{...}`), with the

ability to access variables and tables defined elsewhere in the file.

Multiple sessions can be used, and a different command to start the

REPL process can be passed via the `:fennel-cmd` header argument.



## Contributing



Send patches to the [Fennel mailing list][4]. If you prefer not to

use email you can send a pull request on the [Codeberg mirror][5].

Please byte-compile to check for warnings.



### Testing



This package has tests stored in the `test/` directory.  When

developing new functionality consider writing a test for it.



You can run the tests with `make`. By default this runs the tests for

`fennel-mode` alone; for `fennel-proto-repl` and `ob-fennel` you can

override the `TESTS` argument.



Use `make EMACS=emacs29` to test against a different Emacs version.



During development it may be more convenient to use `M-x

ert-run-tests-interactively` but try to make sure the tests pass with

a fresh Emacs using `make` before committing.



## Copyright



Copyright © 2018-2024 Phil Hagelberg and contributors



Licensed under the same license as Emacs (GPL v3 or later); see LICENSE



[1]: https://git.sr.ht/~technomancy/fnlfmt

[2]: https://gitlab.com/alexjgriffith/min-love2d-fennel/blob/master/lib/stdio.fnl

[3]: https://love2d.org

[4]: https://lists.sr.ht/%7Etechnomancy/fennel

[5]: https://codeberg.org/technomancy/fennel-mode

[6]: https://git.sr.ht/~technomancy/antifennel

[7]: https://gitlab.com/andreyorst/fennel-proto-repl-protocol

[8]: https://git.sr.ht/~xerool/fennel-ls

[9]: https://www.gnu.org/software/emacs/manual/html_mono/eglot.html