Olical / Conjure

++++

== https://oli.me.uk/conversational-software-development/[Conversational software development] for https://neovim.io[Neovim] + https://conjure.fun/discord[image:https://img.shields.io/discord/732957595249410108.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2[Discord]]

Conjure is an interactive environment for evaluating code within your running program.

The core features of Conjure are language agnostic (although it's targeted at Lisps for now), with each language client providing their own extra tools. Here's the currently supported languages, contributions and 3rd party plugins that add clients are highly encouraged!

• https://clojure.org/[Clojure] over https://nrepl.org/[nREPL] (https://github.com/Olical/conjure/wiki/Quick-start:-Clojure[quickstart])
• https://fennel-lang.org/[Fennel] inside Neovim via Lua and https://github.com/Olical/aniseed[Aniseed] (https://github.com/Olical/conjure/wiki/Quick-start:-Fennel-(Aniseed)[quickstart])
• https://fennel-lang.org[Fennel] outside of Neovim within any Lua process through an stdio REPL (https://github.com/Olical/conjure/wiki/Quick-start:-Fennel-(stdio)[quickstart])
• https://janet-lang.org/[Janet] over https://github.com/janet-lang/spork/#networked-repl[spork/netrepl] (https://github.com/Olical/conjure/wiki/Quick-start:-Janet-(netrepl)[quickstart])
• https://racket-lang.org/[Racket] over stdio (https://github.com/Olical/conjure/wiki/Quick-start:-Racket-(stdio)[quickstart])
• https://docs.hylang.org[Hy] over stdio (https://github.com/Olical/conjure/wiki/Quick-start:-Hy-(stdio)[quickstart])
• https://www.gnu.org/software/mit-scheme/[Scheme] (MIT by default) over stdio (https://github.com/Olical/conjure/wiki/Quick-start:-Scheme-(stdio)[quickstart])
• https://www.gnu.org/software/guile/[Guile] over a socket file (https://github.com/Olical/conjure/wiki/Quick-start:-Guile-(socket)[quickstart])

== User experience

What does wielding Conjure actually look like? What can you do with it?

• YouTube: https://youtu.be/ZSwbiZhvMdQ[How I use Conjure and Neovim to interact with Clojure (and more!)]
• Asciinema (see below)

https://asciinema.org/a/325517[image:https://asciinema.org/a/325517.svg[asciicast]]

• Open a file of a supported file type such as clojure or racket.
• Some languages, such as Clojure, will automatically connect to your REPL or give you the commands and mappings to do so yourself.
• Use various mappings to execute the code you're interested in such as the current form, file, buffer or even form at a Neovim mark.
• Every result is kept in a log buffer that you can access at any time.
• Support for multiple asynchronous autocompletion frameworks, with https://github.com/Shougo/deoplete.nvim/[deoplete] built in (<C-x><C-o> also works!).

Conjure allows you to send the right part of your code off for evaluation, see the results, wrap the results in more code and evaluate that. It keeps a log of your actions and results so you don't have to remember them, that context is extremely helpful when you're down the rabbit hole of a bug hunt.

The goal is to give you a tool that lets you effortlessly run whatever you need to while keeping out of your way (but there with context and more information if you need it).

== Try without installing

You can trial run Conjure with the interactive :ConjureSchool tutorial without actually installing it! The only prerequisites are curl and an up to date nvim.

[source,bash]

curl -fL conjure.fun/school | sh

This will temporarily download the plugin, launch Neovim with :ConjureSchool running and then clean up after itself. You get to try out what Conjure has to offer without having to edit your Neovim configuration.

== Installation

Use your favourite plugin manager, mine is https://github.com/junegunn/vim-plug[vim-plug] but any will do. Be sure to pin it to a tag and subscribe to releases through GitHub to avoid any surprises in the future.

[source,viml]

Plug 'Olical/conjure', {'tag': 'v4.16.0'}

You'll need to be on the latest stable Neovim for all of the features (such as floating windows) to work. If you see errors, please check your Neovim version before raising an issue.

Note: Some issues have been reported when using https://github.com/wbthomason/packer.nvim[packer] to install Conjure and Aniseed. Work has been done to mitigate this, but https://github.com/Olical/conjure/issues/159#issuecomment-757384128[this comment] should help you out if you run into issues.

== Getting started

• https://github.com/Olical/conjure/wiki/Quick-start:-Clojure[Clojure (JVM)]
• https://github.com/Olical/conjure/wiki/Quick-start:-Clojure-(babashka)[Clojure (babashka)]
• https://github.com/Olical/conjure/wiki/Quick-start:-ClojureScript-(shadow-cljs)[ClojureScript (shadow-cljs)]
• https://github.com/Olical/conjure/wiki/Quick-start:-Janet-(netrepl)[Janet (netrepl)]
• https://github.com/Olical/conjure/wiki/Quick-start:-Fennel-(Aniseed)[Fennel (Aniseed)]
• https://github.com/Olical/conjure/wiki/Quick-start:-Fennel-(stdio)[Fennel (stdio)]
• https://github.com/Olical/conjure/wiki/Quick-start:-Racket-(stdio)[Racket (stdio)]
• https://github.com/Olical/conjure/wiki/Quick-start:-Hy-(stdio)[Hy (stdio)]
• https://github.com/Olical/conjure/wiki/Quick-start:-Scheme-(stdio)[Scheme (stdio)]
• https://github.com/Olical/conjure/wiki/Quick-start:-Guile-(socket)[Guile (socket)]
• https://github.com/Olical/conjure/wiki/Frequently-asked-questions[Frequently asked questions]

All further documentation is found within link:doc/conjure.txt[:help conjure]. You can also use :ConjureSchool to get an interactive introduction to the workflow and mappings Conjure provides.

Please do get in touch via https://conjure.fun/discord[Discord] or https://twitter.com/OliverCaldwell[Twitter] if you have any questions or issues.

Broader documentation can be found in the https://github.com/Olical/conjure/wiki[Conjure wiki], there you'll find blog posts and guides that will help you get common workflows up and running. Contributions are encouraged!

== Clients of tomorrow

These are clients I intend to build eventually or encourage another community member to build and maintain on my behalf. Every language we add creates another bridge between communities, I would like Conjure to be common ground between all of our beloved esoteric REPL based languages.

• http://lfe.io/[Lisp Flavoured Erlang]
• Common Lisp (https://github.com/Olical/conjure/issues/97[#97])
• Minimal https://clojure.org/[Clojure] sans nREPL+CIDER over https://oli.me.uk/clojure-socket-prepl-cookbook/[prepl] (or socket REPL)
• Non-Lisp languages and beyond! (when Neovim has tree-sitter)

== Behind the curtain

Conjure is written entirely in Lua (no VimL or external processes!) which is compiled from https://fennel-lang.org/[Fennel] by https://github.com/Olical/aniseed[Aniseed] ahead of time. Check out link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] for more on how to work on Conjure using itself.

Historically, Conjure was Clojure specific with an entirely different implementation, you can still find that version on the https://github.com/Olical/conjure/tree/legacy-jvm[legacy-jvm branch].

== Unlicenced

Find the full http://unlicense.org/[unlicense] in the UNLICENSE file, but here's a snippet.

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.