REPLterm

A neovim plugin to ease the use of neovim's builtin terminal with REPLs like R, python, and julia.

Justification and Features

There a lot of terminal plugins designed for neovim (see here). However, none did fit my desire for an easy to use, non-distracting terminal which is designed to run commands of a script in a read-eval-print loop (e.g., the python interpreter, R interpreter, etc.).

This plugin is designed to help for example in data analysis when the majority of work is done in a script file and only parts of it need to be tested. Thus, you can easily send commands from your current file to the terminal window and show the results (or hide the terminal window). In addition, the used terminal is shared between tabpages. This makes it easier to test scripts that are splitted in different files.

Features:

• Open a (floating) terminal window with the default shell or a REPL (customizable).
• Connect on another tabpage to an already existing terminal buffer. In addition, it is also possible to create a new terminal buffer (using the same or a different REPL).
• Send commands from a file to the terminal and execute the commands.

Missing Features:

• Show a terminal on different tabpages at the same time. Currently it is only possible to have the terminal window on one tabpage. If the terminal is opened on another tabpage, it is hidden on the previous tabpage.
• Configurations like window placement, etc.

Non-Features:

• Open multiple terminal windows on the same tabpage. Refer to this page, if you are looking for a plugin that handles this use case.

Current Status

The plugin is in early development. The basic features (see above) work. However, documentation and features need to be extended in the future.

Development and Contributions

Contributions are welcome!

Development takes place on the codeberg page of this plugin. There is a mirror on github but issues and pull requests won't be accepted their.

Installation

Using packer:

use {
 "https://codeberg.org/mutluyuz/nvim-replterm.git",
 config = require("nvim-replterm").setup({}),
 requires = {
 { "akinsho/toggleterm.nvim", tag = "v2.11.0" },
 },
}

Using lazy.nvim:

{
 url = "https://codeberg.org/mutluyuz/nvim-replterm.git",
 config = true,
 dependencies = {
 { "akinsho/toggleterm.nvim", tag = "v2.11.0" },
 },
},

Configuration

Using Vimscript

The following user commands are defined in vimscript:

• REPLtermOpen: Opens a new REPLterm window. If a terminal buffer doesn't exist, it is created.
• REPLtermClose: Closes an existing REPLterm window. The terminal buffer isn't destroyed.
• REPLtermExit: Closes an existing REPLterm window and destroys the corresponding terminal buffer. Warning: You will probably loose the history and unsaved work from the running REPL.
• REPLtermToggle: If a REPLterm window doesn't exist, opens a new REPLterm window (and a new terminal buffer if necessary). If a REPLterm window exists, closes the window (leaving the terminal buffer untouched).
• REPLtermSendCurrentLine: Sends the current line (where the cursor is placed) to the terminal buffer and executes it.
• REPLtermSendCurrentSelection: Sends the current selection (visual mode) to the terminal buffer and executes it.
• REPLtermSendCurrentBuffer: Sends the whole buffer to the terminal buffer and executes it.
• REPLtermSendCurrentBlock: Sends the current block to the terminal buffer and executes it. A block is assumed to be a "block of code" without any empty lines in-between.
• REPLtermSendCurrentChunk: Sends the current chunk to the terminal buffer and executes it. A chunk is assumed to be a "block of code" with the start and end string defined by replterm_ft_chunk_start and replterm_ft_chunk_end (in the current buffer).
• REPLtermOpenAndInsert: Opens the terminal window of the current buffer and goes into inserting mode.

A sample key configuration might look like (sorry, we call these functions in lua and not in vimscript):

vim.keymap.set({ "n", "i"}, "<F12>", "<Esc>:REPLtermToggle<CR>")
vim.keymap.set({ "n", "i"}, "<c-c><c-c>", "<Esc>:REPLtermSendCurrentLine<CR>")
vim.keymap.set("v", "<c-c><c-c>", ":REPLtermSendCurrentSelection<CR>")
vim.keymap.set({"n", "i"}, "<c-c>i", ":REPLtermJumpToWindow<CR>")
vim.keymap.set({"n", "i"}, "<S-F12>", ":REPLtermSwichtWinTile<CR>")

Using Lua

The following functions can be called:

local replterm = require("replterm")
-- Open a new terminal on the current tabpage. Creates one if there isn't one.
replterm.open()
-- Closes the current REPLterm window of the current tabpage.
replterm.close()
-- Opens a new REPLterm window (and creates a new terminal buffer if necessary)
-- if it does not exist. Closes the current REPLterm window of the current
-- tabpage if a window is open.
replterm.toggle()
-- Destroys the terminal buffer of the current tabpage and closes the
-- corresponding window.
replterm.exit()
-- Runs `command` in the terminal buffer of the current tabpage.
replterm.run(command)
-- Opens the terminal window of the current tabpage and goes into insert mode.
replterm.open_and_insert()

Language-specific Customizations

TBD