search

justinbarclay / parinfer-rust-mode

Simplifying how you write Lisp
https://shaunlebron.github.io/parinfer/
GNU General Public License v3.0
227 stars 16 forks source link

readme

+ATTR_HTML: :alt "Github Actions"

[[https://github.com/justinbarclay/parinfer-rust-mode/actions/workflows/test.yml/badge.svg][https://github.com/justinbarclay/parinfer-rust-mode/actions/workflows/test.yml/badge.svg]] [[https://melpa.org/#/parinfer-rust-mode][file:https://melpa.org/packages/parinfer-rust-mode-badge.svg]] [[https://stable.melpa.org/#/parinfer-rust-mode][file:https://stable.melpa.org/packages/parinfer-rust-mode-badge.svg]]

[[file:https://raw.githubusercontent.com/ocodo/parinfer-logo/master/pngs/parinfer-org-logo-128x128.png]]

+begin_quote

[!WARNING] Version 0.9 and greater of ~parinfer-rust-mode~ only supports my fork of ~parinfer-rust~, ~parinfer-rust-emacs~. My primary reason for forking was to add better support for ~parinfer-rust~ options, which will allow ~parinfer-rust-mode~ to work better with non-clojure-like lisps. You can read more [[https://github.com/justinbarclay/parinfer-rust/discussions/9][here]].

For those wanting to continue using ~parinfer-rust~, you should pin your install to version 0.8.5.

+end_quote

** Capabilities:

After that add it to your load path and go wild.

+BEGIN_SRC emacs-lisp

(add-to-list 'load-path "/path/to/parinfer-rust-mode") (require 'parinfer-rust-mode) (add-hook 'emacs-lisp-mode 'parinfer-rust-mode)

+END_SRC

**** Use Package Alternatively, you can tell something like [[https://github.com/quelpa/quelpa-use-package][use-package]] to manage it for you.

+BEGIN_SRC emacs-lisp

(use-package parinfer-rust-mode :hook emacs-lisp-mode)

+END_SRC

* parinfer-rust library You'll also need to have the library installed on your system for you somewhere. ** Option 1: Let Parinfer Rust install it for you That's it. There are no instructions here. When parinfer-rust-mode prompts you to download the library, say yes. ~parinfer-rust-mode~ will then use curl to download ~parinfer-rust~ and save it in ~${EMACS_DIRECTORY}/parinfer-rust/~.

/Supported OS & Arch[fn:1]/

+NAME: Supported OS

| Operating System | Architecture | | Windows | x86_64 | | Darwin | aarch64 | | Linux | x86_64 | | Freebsd | x86_64 |

+BEGIN_QUOTE

List of supported operating systems and the architecture for which libraries are prebuilt

+END_QUOTE

If you're curious, you can find the library files that parinfer-rust-mode downloads as release artifacts for [[https://github.com/eraserhd/parinfer-rust/releases][parinfer-rust-emacs]].

If you would always like parinfer-rust-mode to keep the library version in sync for you, automatically download it, then add the following line into your config:

+BEGIN_SRC emacs-lisp

(setq parinfer-rust-auto-download t)

+END_SRC

If you are using the ==use-package== snippet from above, that would look like:

+BEGIN_SRC emacs-lisp

(use-package parinfer-rust-mode :hook emacs-lisp-mode :init (setq parinfer-rust-auto-download t))

+END_SRC

[fn:1] Don't see your OS/Arch on here? Feel free to open up a PR at [[https://github.com/justinbarclay/parinfer-rust][parinfer-rust-emacs]] and add your OS to the GitHub actions. ** Option 2: Building library from sources For the more adventurous, you can also download and compile the ~parinfer-rust~ library from source. *** Step 1: Build the Parinfer Rust Emacs library When manually compiling the library, the file name differs from platform to platform. Additionally, Emacs expects that these libraries have specific file extensions when first loading them up. This is a problem for MacOS because Rust compiles it as ~.dylib~, and we'll need to give the file an ~.so~ extension when we copy it to its final location.

 | Platform | File name              | Required extension |
 |----------+------------------------+--------------------|
 | Linux    | libparinfer_rust.so    | .so                |
 | MacOS    | libparinfer_rust.dylib | .so                |
 | Windows  | parinfer_rust.dll      | .dll               |

 #+BEGIN_SRC shell
   git clone https://github.com/justinbarclay/parinfer-rust-emacs.git
   cd parinfer-rust
   cargo build --release
   cp ./target/release/${library-name} ~/.emacs.d/parinfer-rust/${lib-name}
 #+END_SRC

***** Step 2: Configure parinfer-rust-mode Once you have compiled the libraries from source code you'll need to tell ~parinfer-rust-mode~ how to find these libraries

+BEGIN_SRC elisp

   (setq parinfer-rust-library "/path/to/parinfer-rust-library.so")
 #+END_SRC

** Modes Parinfer can operate under three different modes when writing lisp. *** Paren Paren Mode gives you full control of parens, while Parinfer corrects indentation. You can still adjust indentation, but you won't be able to indent/dedent past certain boundaries set by parens on previous lines.

[[./videos/paren-mode.gif]]

*** Indent Indent Mode gives you full control of indentation, while Parinfer corrects or inserts close-parens where appropriate. Specifically, it only touches the groups of close-parens at the end of each line.

[[./videos/indent-mode.gif]]

*** Smart Smart Mode is like Indent Mode, but it tries to preserve the structure too.

[[./videos/smart-mode.gif]]

** Commands | Command | Description | |---------------------------------+-------------------------------------------------------| | parinfer-rust-switch-mode | Quickly switch between paren, indent, and smart modes | | parinfer-rust-toggle-disable | Toggle parinfer-rust-mode mode on or off | | parinfer-rust-toggle-paren-mode | Toggle between paren mode and current mode |

These commands are no longer bound to the ~C-c C-p~ prefix keys by default. If you prefer to use the old bindings, add this to your configuration (keep in mind it may clash with some major mode bindings):

+begin_src elisp

 (define-key parinfer-rust-mode-map (kbd "C-c C-p t") #'parinfer-rust-toggle-paren-mode)
 (define-key parinfer-rust-mode-map (kbd "C-c C-p s") #'parinfer-rust-switch-mode)
 (define-key parinfer-rust-mode-map (kbd "C-c C-p d") #'parinfer-rust-toggle-disable)

+end_src

** Customizations parinfer-rust-mode is purposefully light on option, but it does give a few options to tweak behavior.

Options:

~parinfer-rust-mode~ relies on [[https://github.com/cask/cask][Cask]] to manage development libraries and to set-up the tests themselves.

Then after you have made some changes just run:

+BEGIN_SRC shell

PARINFER_RUST_TEST=true make test

+END_SRC

And you should get something like:

+BEGIN_SRC shell

✦ ❯ PARINFER_RUST_TEST=true make test emacs --version GNU Emacs 28.0.50 Copyright (C) 2020 Free Software Foundation, Inc. GNU Emacs comes with ABSOLUTELY NO WARRANTY. You may redistribute copies of GNU Emacs under the terms of the GNU General Public License. For more information about these matters, see the file named COPYING. cask build Compiling /home/justin/dev/parinfer-rust-mode/parinfer-helper.el... Compiling /home/justin/dev/parinfer-rust-mode/parinfer-rust-mode-autoloads.el... Compiling /home/justin/dev/parinfer-rust-mode/parinfer-rust-mode.el...

In toplevel form: parinfer-rust-mode.el:72:1: Error: Symbol’s value as variable is void: parinfer-rust-library Compiling /home/justin/dev/parinfer-rust-mode/test-helper.el... cask exec ert-runner test/**.el --quiet ...............................................................................................................................................

Ran 143 tests in 0.061 seconds

+END_SRC

** Thanks