Quick start: Clojure (basilisp)

Basilisp - A Clojure-compatible(-ish) Lisp dialect targeting Python 3

Conjure supports Basilisp evaluation using the Clojure client communicating over an nREPL connection. Some parts of Conjure's Clojure support won't work with it because it's not Clojure on the JVM. You can read about the differences between Clojure and Basilisp at Differences from Clojure.

Prerequisites

• Install the latest Neovim.
• Install the Conjure plugin.
• Install Python 3.
• Install Basilisp.
• Associate Basilisp files (*.lpy) with the Clojure filetype in Neovim.

Associate Basilisp files with the Clojure filetype

Add this to your Neovim config using Lua:

vim.filetype.add({extension = {lpy = "clojure"}})

or using Fennel (Thanks @lost22git! See his comment on Issue #746](https://github.com/Olical/conjure/issues/746#issuecomment-3708789837)):

(vim.filetype.add {:extension {:lpy :clojure}})

or using Vimscript (see :he new-filetype):

au BufRead,BufNewFile *.lpy set filetype=clojure

Start an nREPL server from the command line

The Start an nREPL Session says:

$ basilisp nrepl-server

This will create a .nrepl-port file which the Clojure client will read to connect to the Basilisp nREPL server.

Caution: auto-started Babashka nREPL server

If you always remember to start a Basilisp nREPL server before editing Basilisp files, you can skip this.

If you don't start up a Clojure nREPL server, by default, Conjure will automatically start up a Babashka nREPL server.

To avoid this, add this to your Neovim config in Vimscript:

let g:conjure#client#clojure#nrepl#connection#auto_repl#enabled = v:false

or in Lua:

vim.g['conjure#client#clojure#nrepl#connection#auto_repl#enabled'] = false

Or start a Basilisp nREPL server from within Neovim

You might find it more convenient to be able to start a Basilisp nREPL server once you're in Neovim.

In his comment on Issue #746](https://github.com/Olical/conjure/issues/746#issuecomment-3708789837)), @lost22git suggests creating a Neovim user command named Basilisp to start a Basilisp nREPL in a Neovim tab.

Here's his suggestion in Fennel:

;; add usercmd to start basilisp nrepl server
(vim.api.nvim_create_autocmd :FileType {:desc "[Basilisp] add `Basilisp` usercmd for starting Basilisp nrepl server"
                     :pattern :clojure
                     :callback (fn [{:buf bufid}] 
  (vim.api.nvim_buf_create_user_command bufid :Basilisp
                                             #(vim.cmd (.. "tabnew | term "
                                                           "basilisp nrepl-server"))
                                             {:nargs "*"}))})

In Lua, it might be:

vim.api.nvim_create_autocmd('FileType', {
    group = vim.api.nvim_create_augroup('basilisp', { clear = true }),
    desc = 'Create user command to start Basilisp nREPL server',
    pattern = 'clojure',
    callback = function()
        vim.api.nvim_buf_create_user_command(0, -- current buffer
            'Basilisp',
            function ()
                vim.cmd('tabnew | term basilisp nrepl-server')
            end,
            { nargs = '*',
                desc = 'Start Basilisp nREPL server',
            })
    end})

Stop the Basilisp nREPL server in another tab

To stop the Basilisp nREPL server running in another tab, you:

• Switch to the tab with the server (:tabnext).
• Press the i key to change into INSERT mode.
• Type Ctl-C to stop the server.
• Switch back to the buffer you were editing (typing a : should do it).

Open and edit!

You should now be able to open a Basilisp file (*.lpy) and evaluate as you normally would. You even get completions!

If you're unsure how to evaluate things with Conjure, please refer to :help conjure, :help conjure-client-clojure-nrepl and :ConjureSchool (an interactive tutorial).