Neovim REPL

Create, use, and remove an interactive REPL within Neovim 0.5.0+.

Installation

{
  "pappasam/nvim-repl",
  init = function()
    vim.g["repl_filetype_commands"] = {
      javascript = "node",
      python = "ipython --no-autoindent"
    }
  end,
  keys = {
    { "<leader>rt", "<cmd>ReplToggle<cr>", desc = "Toggle nvim-repl" },
    { "<leader>rc", "<cmd>ReplRunCell<cr>", desc = "nvim-repl run cell" },
  },
}

For other package management tools, please consult their documentation.

Usage

demo

:Repl or :ReplOpen
without argument: open the default shell which is configured by filetype
:Repl env $env_name:open a python shell with the environment of $env_name, only support for Conda
:Repl arg: open the default shell and exec the arg command
:ReplClose: close the REPL, if open.
:ReplToggle: if REPL is open, close it. If REPL is closed, open it using either the filetype associated REPL or the configured default REPL.
:ReplClear: clear the REPL, if open.
:ReplRunCell: will run the cell under the cursor and the cursor will jump to next cell

Several pluggable, dot-repeatable mappings are provided.

<Plug>ReplSendLine send the current line to the REPL.
<Plug>ReplSendCell send the current cell to the REPL.
<Plug>ReplSendVisual send the visual selection to the REPL.

The user should map these pluggable mappings. Example mappings in config using vim filetype:

nnoremap <Leader>rt <Cmd>ReplToggle<CR>
nmap     <Leader>rc <Plug>ReplSendCell
nmap     <Leader>rr <Plug>ReplSendLine
xmap     <Leader>r  <Plug>ReplSendVisual

Configuration

Use g:repl_filetype_commands to map Neovim file types to REPL. E.g., if you automatically want to run a ipython REPL for python file types and a "node" REPL for JavaScript file types, your configuration might look like this:

let g:repl_filetype_commands = {
  \ 'javascript': 'node',
  \ 'python': 'ipython --no-autoindent',
  \ }

ipython config

You should pip install ipython firstly, then let g:repl_filetype_commands = {'python': 'ipython'}

Use g:repl_default to set the default REPL if no configured REPL is found in g:repl_filetype_commands. Defaults to &shell.

Use g:repl_split to set the REPL window position. vertical and horizontal respect the user-configured global splitright and splitbottom settings.

'bottom'
'top'
'left'
'right'
'horizontal'
'vertical' (default)

If split bottom is preferred, then add below line to configuration.

let g:repl_split = 'bottom'

g:repl_height to set REPL window's height (number of lines) if g:repl_split set 'bottom'/'top'. Default split equally.
g:repl_width to set REPL window's width (number of columns) if g:repl_split set 'left'/'right'. Default vsplit equally.

Cells

Cells are denoted by full-line comments that begin with the characters %%.

Comments are identified by your buffer's filetype's 'commentstring'.

See some examples below:

Python

# %%
print("I am the first cell")
print("I am still the first cell")

# %% anything can follow
print("I am the second cell")
print("I am still the second cell")
print("I am still, still the second cell")
# %%

print("I am the third cell")

Haskell

-- %%
putStrLn "I am the first cell"
putStrLn "I am still the first cell"

-- %% anything can follow
putStrLn "I am the second cell"
putStrLn "I am still the second cell"
putStrLn "I am still, still the second cell"
-- %%

putStrLn "I am the third cell"

Full Documentation

From within Neovim, type:

:help repl

FAQ

Getting strange errors with Python, please help

One such error might be a IndentError. This has to do with quirks related to the default Python interpreter. To get around this, use ipython as your default interpreter for Python files.

Terminal:

pip install ipython

init.vim:

" init.vim
let g:repl_filetype_commands = {'python': 'ipython --no-autoindent'}

Escape doesn't work in Terminal mode

If you find yourself in Terminal mode, use <C-\><C-n> instead of <Esc> to return to Normal mode.

Type :help Terminal-mode and :help CTRL-\_CTRL-N for more information.

pappasam / nvim-repl

readme