A general-perpose terminal wrapper and management plugin for neovim, written in lua
https://asciinema.org/a/88T1XmVG6Xak4580OHsrBV7kW
I know what you're thinking: "There are already dozens of terminal wrapper plugins for vim/neovim out there! Why yet another?" And you'd be partially right - the default configuration of consolation.nvim is basically the same as all the other terminal wrapper plugins out there. But, as is the case with many vim and neovim plugins, consolation.nvim is much more than its default configuration.
The main reason that the author created this plugin is because while there is no shortage of either terminal management plugins (e.g. Neoterm) or floating terminal plugins (e.g. Floaterm), trying to get either the terminal management plugin to work with floating windows or the floating terminal plugin to accept input programmatically is a major pain. The idea of this plugin is to take absolutely any asthetically enhancing terminal plugin and make it easy to use programmatically as well. What this means practically speaking is that you can have a floating terminal (like with Floaterm or FTerm) that can be controlled with lua functions similarly to Neoterm.
Packer.nvim:
use 'pianocomposer321/consolation.nvim'
vim-plug:
Plug 'pianocomposer321/consolation.nvim'
etc.
The way you interact with Consolation is through its Wrapper
object.
Wrapper:new()
Returns a new Wrapper
object
Wrapper:setup(opts)
Setup the Wrapper
using the provided configuration options
create
(function): The function used to create the terminalfunction() vim.cmd("vnew | term") end
open
(function): The function used to open the terminal.function(self)
local winnr = self.get_winnr()
if winnr == -1 then
vim.cmd("vnew")
vim.cmd("b"..self.bufnr)
else
vim.cmd(winnr.."wincmd w")
end
end
close
(function): The function used to close the terminal.function(self)
local winnr = self.get_winnr()
vim.cmd(winnr.."wincmd c")
end
kill
(function): The function used to kill the terminal.function (self) vim.cmd("bd! "..self.bufnr) end
Except for create
, all of these functions accept one argument, which is a reference to the Wrapper
object iself. This way all of its variables like bufnr
, winid
, etc. are avaliable to the functions.
Wrapper:create()
Creates a new terminal buffer, using the create
function specified in the Wrapper:setup(opts)
function, and updates values for the terminal's bufnr
, winid
, etc.
Wrapper:open(args)
Opens the terminal using the open
function specified in the Wrapper:setup(opts)
function.
cmd
(string, default nil
): Command to run upon opening the terminalcreate
(bool, default true
): Whether to create the terminal if it does not already existWrapper:close()
Closes the terminal using the close
function specified in the Wrapper:setup(opts)
function.
Wrapper:kill()
Kills the terminal using the kill
function specified in the Wrapper:setup(opts)
function, and resets the Wrapper
object's channel
, winid
, and bufnr
variables to nil
.
Wrapper:toggle(args)
Toggles the terminal using either the open
or the close
function specified in the Wrapper:setup()
opts function.
create
(bool, default true
): Whether to create the terminal when opening it if it does not already existWrapper:send_command(args)
Sends a command to the terminal.
cmd
(string, REQUIRED): The command to sendopen
(bool, default true
): Whether to open the terminal before running the commandcreate
(bool, default true
): Whether to create the terminal if it does not already existWrapper:is_open()
Utility function that returns whether the terminal buffer is currently displayed in a window (IOW, open).
bool
Wrapper:get_winnr()
Utility function that returns the Wrapper
object's winnr
. (:help bufwinnr()
)
int
:term
command in a vsplitlocal Wrapper = require("consolation").Wrapper
BuiltinTerminalWrapper = Wrapper:new()
BuiltinTerminalWraper:setup {
create = function() vim.cmd("vnew | term") end,
open = function(self)
if self:is_open() then
local winnr = vim.fn.bufwinnr(self.bufnr)
vim.cmd(winnr.."wincmd w")
else
vim.cmd("vnew")
vim.cmd("b"..self.bufnr)
end
end,
close = function(self)
local winnr = vim.fn.bufwinnr(self.bufnr)
vim.cmd(winnr.."wincmd c")
end,
kill = function(self)
vim.cmd("bd! "..self.bufnr)
end
}
-- Try:
-- BuiltinTerminalWraper:open {cmd = "echo hi"}
-- BuiltinTerminalWraper:send_command {cmd = "echo hi again"}
-- BuiltinTerminalWraper:close()
-- BuiltinTerminalWraper:toggle()
-- BuiltinTerminalWraper:kill()
local term = require("Fterm.terminal")
Runner = term:new():setup()
FtermWrapper = Wrapper:new()
FtermWrapper:setup {
create = function() Runner:open() end,
open = function(_) Runner:open() end,
close = function(_) Runner:close() end,
kill = function(_) Runner:close(true) end
}